Update claude-api skill: Claude Opus 5 (#1476)

* Update claude-api skill: Claude Opus 5

- Add Claude Opus 5 (`claude-opus-5`) as the default model across all
  SDK examples, model tables, pricing, and migration guidance.
- Add an Opus 5 migration section covering the API changes that come
  with it, and move Opus 4.8 into the previous-generation slot.
- Drop the Opus 4.7 fast-mode guidance, which no longer applies.
- Scope the server-side fallbacks beta header to the current version.

* Update claude-api skill: Opus 5 fast-follow corrections

- Server-side refusal fallbacks are available on Claude Platform on AWS,
  not just the Claude API. Correct the availability statements in
  SKILL.md, the migration guide, and the platform-availability table.
- Simplify the effort guidance: start at `high` (the API default) and
  sweep down, rather than starting at `xhigh` for coding work.
- Add a time-to-first-token section with the prompt instruction that
  reduces pre-answer thinking on latency-sensitive routes.
- Replace the two separate thinking-disabled mitigations with the single
  combined instruction that covers both failure modes.

skills/claude-api/SKILL.md

@@ -26,11 +26,26 @@ Never mix the two — don't reach for `requests`/`fetch` in a Python or TypeScri
 
 **Never guess SDK usage.** Function names, class names, namespaces, method signatures, and import paths must come from explicit documentation — either the `{lang}/` files in this skill or the official SDK repositories or documentation links listed in `shared/live-sources.md`. If the binding you need is not explicitly documented in the skill files, WebFetch the relevant SDK repo from `shared/live-sources.md` before writing code. Do not infer Ruby/Java/Go/PHP/C# APIs from cURL shapes or from another language's SDK.
 
+**If WebFetch or repository access fails** (network restricted, timeouts, clone blocked): do not keep retrying — write code from the patterns and namespace/package tables in the `{lang}/` file, run the compiler or interpreter on it, and iterate on the error output. For statically-typed SDKs (C#, Java, Go) a compile-fix loop against local errors reaches working code faster than blocked network research.
+
 ## Defaults
 
 Unless the user requests otherwise:
 
-For the Claude model version, please use Claude Opus 4.8, which you can access via the exact model string `claude-opus-4-8`. Please default to using adaptive thinking (`thinking: {type: "adaptive"}`) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high `max_tokens` — it prevents hitting request timeouts. Use the SDK's `.get_final_message()` / `.finalMessage()` helper to get the complete response if you don't need to handle individual stream events
+For the Claude model version, please use Claude Opus 5, which you can access via the exact model string `claude-opus-5`. Please default to using adaptive thinking (`thinking: {type: "adaptive"}`) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high `max_tokens` — it prevents hitting request timeouts. Use the SDK's `.get_final_message()` / `.finalMessage()` helper to get the complete response if you don't need to handle individual stream events
+
+## ⚠️ API Drift — Your Training Prior May Be Stale
+
+Several common Claude API shapes changed in 2025–2026. If you recall a pattern from training, verify it against the `{lang}/` files in this skill before writing — the rows below are the most frequent drift points:
+
+| Area | Stale prior | Current API |
+|---|---|---|
+| Extended thinking | `thinking: {type: "enabled", budget_tokens: N}` | On Claude 4.6+ models: `thinking: {type: "adaptive"}`. `budget_tokens` is deprecated on Opus 4.6 / Sonnet 4.6 and **rejected with a 400** on Fable 5 / Sonnet 5 / Opus 5 / 4.8 / 4.7. Pre-4.6 models still use `budget_tokens`. |
+| Web search / web fetch tool type | `web_search_20250305`, `web_fetch_20250910` | `web_search_20260209`, `web_fetch_20260209` (dynamic filtering) on Opus 5/4.8/4.7/4.6, Sonnet 5, and Sonnet 4.6. Older models keep the basic variants; on Vertex AI only basic `web_search_20250305` is available (web fetch is not on Vertex) — see the Server Tools QR below. |
+| PHP parameter names | snake_case wire names as named args (`max_tokens`) | Top-level named args are camelCase (`maxTokens`). Nested array keys vary by feature (e.g. `'taskBudget'`, `'skillID'`, `'mcp_server_name'`) — copy the exact key from the documented example; do not bulk-convert. |
+| Managed Agents credentials | Keep secrets host-side via custom tools (the only option before vaults shipped) | Vault `environment_variable` credentials — stored by Anthropic, substituted at egress, never visible in the sandbox (`shared/managed-agents-tools.md` → Vaults). Host-side custom tools remain the fallback for self-hosted sandboxes. |
+
+The `{lang}/` files in this skill are authoritative over recalled patterns.
 
 ---
 
@@ -80,24 +95,15 @@ Before reading code examples, determine which language the user is working in:
 
 ### Language-Specific Feature Support
 
-| Language   | Tool Runner | Managed Agents | Notes                                 |
-| ---------- | ----------- | -------------- | ------------------------------------- |
-| Python     | Yes (beta)  | Yes (beta)     | Full support — `@beta_tool` decorator |
-| TypeScript | Yes (beta)  | Yes (beta)     | Full support — `betaZodTool` + Zod    |
-| Java       | Yes (beta)  | Yes (beta)     | Beta tool use with annotated classes  |
-| Go         | Yes (beta)  | Yes (beta)     | `BetaToolRunner` in `toolrunner` pkg  |
-| Ruby       | Yes (beta)  | Yes (beta)     | `BaseTool` + `tool_runner` in beta    |
-| C#         | Yes (beta)  | Yes (beta)     | `BetaToolRunner` + raw JSON schema    |
-| PHP        | Yes (beta)  | Yes (beta)     | `BetaRunnableTool` + `toolRunner()`   |
-| cURL       | N/A         | Yes (beta)     | Raw HTTP, no SDK features             |
+Every SDK language above supports both the beta Tool Runner and Managed Agents (beta) — Python (`@beta_tool` decorator), TypeScript (`betaZodTool` + Zod), Java (annotated classes), Go (`BetaToolRunner` in the `toolrunner` pkg), Ruby (`BaseTool` + `tool_runner`), C# (`BetaToolRunner` + raw JSON schema), PHP (`BetaRunnableTool` + `toolRunner()`); code entry points are in the Tool Use Patterns quick reference below. cURL is raw HTTP (no SDK features) and supports Managed Agents.
 
-> **Managed Agents code examples**: dedicated language-specific READMEs are provided for Python, TypeScript, Go, Ruby, PHP, Java, and cURL (`{lang}/managed-agents/README.md`, `curl/managed-agents.md`). Read your language's README plus the language-agnostic `shared/managed-agents-*.md` concept files. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI (`ant`) is one convenient way to create agents and environments from version-controlled YAML — see `shared/anthropic-cli.md`. If a binding you need isn't shown in the README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# has beta Managed Agents support via `client.Beta.Agents` and related namespaces.
+> **Managed Agents code examples**: see the reading guide in the `## Managed Agents (Beta)` section below.
 
 ---
 
 ## Which Surface Should I Use?
 
-> **Start simple.** Default to the simplest tier that meets your needs. Single API calls and workflows handle most use cases — only reach for agents when the task genuinely requires open-ended, model-driven exploration.
+> **Start simple.** Default to the simplest tier that meets your needs. Single API calls and workflows handle most use cases — only reach for agents when the task genuinely requires open-ended, model-driven exploration. "Simplest" means the least code you own: for a hosted, scheduled, or memory-backed agent, Managed Agents is usually the simplest option (no loop code, no state files, no scheduler), even though it's a bigger platform.
 
 | Use Case                                        | Tier            | Recommended Surface       | Why                                                          |
 | ----------------------------------------------- | --------------- | ------------------------- | ------------------------------------------------------------ |
@@ -108,37 +114,32 @@ Before reading code examples, determine which language the user is working in:
 | Server-managed stateful agent with workspace    | Agent           | **Managed Agents**        | Anthropic runs the loop and hosts the tool-execution sandbox |
 | Persisted, versioned agent configs              | Agent           | **Managed Agents**        | Agents are stored objects; sessions pin to a version         |
 | Long-running multi-turn agent with file mounts  | Agent           | **Managed Agents**        | Per-session containers, SSE event stream, Skills + MCP       |
+| Agent that runs on a schedule (cron, "every night") | Agent       | **Managed Agents** — scheduled deployments | Deployments fire sessions autonomously; no client-side scheduler |
 
-> **Note:** Managed Agents is the right choice when you want Anthropic to run the agent loop *and* host the container where tools execute — file ops, bash, code execution all run in the per-session workspace. If you want to host the compute yourself or run your own custom tool runtime, Claude API + tool use is the right choice — use the tool runner for automatic loop handling, or the manual loop for fine-grained control (approval gates, custom logging, conditional execution).
+> **Note:** Managed Agents is the right choice when you want Anthropic to run the agent loop *and* host the container where tools execute — file ops, bash, code execution all run in the per-session workspace. If you want to host the compute yourself or run your own custom tool runtime, Claude API + tool use is the right choice — use the tool runner for the agentic loop — its per-turn hooks still give you approval gates, logging, error interception, and conditional execution (see `shared/tool-use-concepts.md`) — or the manual loop when you want to own the entire loop yourself.
 
-> **Cloud-provider access.** **Claude Platform on AWS** is Anthropic-operated with same-day API parity — Managed Agents and every feature in this skill work there, **except self-hosted sandboxes** (see `shared/claude-platform-on-aws.md`). **Amazon Bedrock**, **Google Vertex AI**, and **Microsoft Foundry** do **not** support Managed Agents or Anthropic server-side tools; use **Claude API + tool use** on those.
+> **Cloud-provider access.** **Claude Platform on AWS** is Anthropic-operated with same-day API parity — see `shared/claude-platform-on-aws.md` for client setup. For per-feature availability on **Claude Platform on AWS**, **Amazon Bedrock**, **Google Vertex AI**, and **Microsoft Foundry**, see `shared/platform-availability.md` — that table is the single source of truth in this skill; do not infer availability from anywhere else.
 
-### Decision Tree
+### Building an Agent: Four Approaches
 
-```
-What does your application need?
+Once you've decided you actually need an agent (open-ended, model-driven tool use), there are four distinct ways to build one. Two independent questions separate them: **who supplies the harness** (the agent loop + context management) and **who supplies the deployment** (the infra the agent runs on). The Tool Runner and the Claude Agent SDK both supply a *harness only* — you still host and deploy them yourself — which is why they're easy to conflate. Managed Agents (CMA) is the only option that supplies **both** the harness *and* managed deployment; the manual loop supplies neither.
 
-0. Which provider?
-   ├── First-party API or Claude Platform on AWS → continue (full surface available).
-   └── Amazon Bedrock, Google Vertex AI, or Microsoft Foundry → Claude API (+ tool use for agents); Managed Agents not available there.
+| # | Approach | You write | Harness & deployment | Tools available | Use when |
+|---|----------|-----------|----------------------|-----------------|----------|
+| 1 | **Claude API — manual loop** | The `while stop_reason == "tool_use"` loop yourself | You build the harness; you host | Only tools you define | You want to own the *entire* loop — no beta dependency, or a control flow the Tool Runner's per-turn hooks don't fit |
+| 2 | **Claude API — Tool Runner** (`client.beta.messages.tool_runner` + `@beta_tool` / `betaZodTool`) | Just the tool functions | SDK supplies the loop (**harness only**); you host | Only tools you define | A custom-tool agent without hand-writing the loop (most cases). Per-turn hooks still give you approval gates, error interception, result modification (e.g. `cache_control`), retries, streaming, and compaction |
+| 3 | **Managed Agents** (REST, beta) | Agent config + your tool results | Anthropic supplies the harness **and** hosts a per-session sandbox (**harness + deployment**) | Anthropic-hosted sandbox (bash, files, code exec) + Skills/MCP + your tools | You want Anthropic to run the loop *and* host the per-session workspace; persisted/versioned configs; long-running sessions |
+| 4 | **Claude Agent SDK** — *separate product* (`claude-agent-sdk` / `@anthropic-ai/claude-agent-sdk`) | A prompt + options | SDK supplies the Claude Code harness + built-in tools (**harness only**); you host | Built-in Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch + MCP + subagents | You want a batteries-included coding/filesystem agent running on your own infra |
 
-1. Single LLM call (classification, summarization, extraction, Q&A)
-   └── Claude API — one request, one response
+The harness/deployment split is the key mental model: options 1, 2, and 4 all **leave deployment to you**; only option 3 (CMA) adds managed deployment. Options 1–3 are what this skill generates; option 4 is a different library with its own docs — see the disambiguation below.
 
-2. Do you want Anthropic to run the agent loop and host a per-session
-   container where Claude executes tools (bash, file ops, code)?
-   └── Yes → Managed Agents — server-managed sessions, persisted agent configs,
-       SSE event stream, Skills + MCP, file mounts.
-       Examples: "stateful coding agent with a workspace per task",
-                 "long-running research agent that streams events to a UI",
-                 "agent with persisted, versioned config used across many sessions"
-
-3. Workflow (multi-step, code-orchestrated, with your own tools)
-   └── Claude API with tool use — you control the loop
-
-4. Open-ended agent (model decides its own trajectory, your own tools, you host the compute)
-   └── Claude API agentic loop (maximum flexibility)
-```
+> **Tool Runner ≠ Claude Agent SDK.** These sound alike but are different packages:
+> - **Tool Runner** is part of the regular Anthropic API SDK (`anthropic` / `@anthropic-ai/sdk`), reached via `client.beta.messages.tool_runner`. It automates the request → execute → loop cycle *for tools you define*. No built-in tools, no filesystem access, no sandbox — you supply every tool and host the compute. It is option 2 above, a thin helper over `POST /v1/messages`.
+> - **Claude Agent SDK** (`claude-agent-sdk` / `@anthropic-ai/claude-agent-sdk`) is Claude Code packaged as a library. It ships built-in tools (file read/write/edit, bash, grep, web search), the full agent loop, context management, hooks, subagents, permissions, and sessions. You call `query(prompt, options)` and it drives everything.
+>
+> Both are **harness-only — you host and deploy them.** The difference is scope of harness: the Tool Runner loops over tools *you* define (with per-turn hooks for approval, interception, result modification, and retries — but no built-in tools); the Agent SDK is the full Claude Code harness with built-in tools. Neither provides managed deployment — that's what **Managed Agents (CMA)** adds (Anthropic hosts the loop and a per-session sandbox).
+>
+> **This skill covers the Claude API and Managed Agents (options 1–3); it does not generate Claude Agent SDK code.** If the user actually wants the Claude Agent SDK, point them to its docs (`code.claude.com/docs/en/agent-sdk`) — don't substitute the API Tool Runner for it, or vice-versa.
 
 ### Should I Build an Agent?
 
@@ -167,59 +168,81 @@ Everything goes through `POST /v1/messages`. Tools and output constraints are fe
 
 ---
 
-## Current Models (cached: 2026-06-04)
+## Current Models (cached: 2026-06-24)
 
 | Model             | Model ID            | Context        | Input $/1M | Output $/1M |
 | ----------------- | ------------------- | -------------- | ---------- | ----------- |
 | Claude Fable 5    | `claude-fable-5`      | 1M             | $10.00     | $50.00      |
 | Claude Mythos 5 (Project Glasswing only) | `claude-mythos-5` | 1M | $10.00     | $50.00      |
-| Claude Opus 4.8   | `claude-opus-4-8`   | 1M             | $5.00      | $25.00      |
+| Claude Opus 5     | `claude-opus-5`       | 1M             | $5.00      | $25.00      |
+| Claude Opus 4.8 | `claude-opus-4-8`  | 1M             | $5.00      | $25.00      |
 | Claude Opus 4.7   | `claude-opus-4-7`   | 1M             | $5.00      | $25.00      |
 | Claude Opus 4.6   | `claude-opus-4-6`   | 1M             | $5.00      | $25.00      |
+| Claude Sonnet 5   | `claude-sonnet-5`   | 1M             | $3.00 ($2.00 intro through 2026-08-31) | $15.00 ($10.00 intro) |
 | Claude Sonnet 4.6 | `claude-sonnet-4-6` | 1M             | $3.00      | $15.00      |
 | Claude Haiku 4.5  | `claude-haiku-4-5`  | 200K           | $1.00      | $5.00       |
 
-**ALWAYS use `claude-opus-4-8` unless the user explicitly names a different model.** This is non-negotiable. Do not use `claude-sonnet-4-6`, `claude-sonnet-4-5`, or any other model unless the user literally says "use sonnet" or "use haiku". Never downgrade for cost — that's the user's decision, not yours. Use `claude-fable-5` only when the user explicitly asks for Claude Fable 5, "fable", or Anthropic's most capable model — it has different API behavior than the Opus family (see below) and pricing that exceeds Opus-tier.
+**Partner pricing:** The prices above are Anthropic first-party API rates — they also apply to Claude on Microsoft Foundry, which is billed through the Microsoft Marketplace at standard API rates. Claude on Amazon Bedrock and Vertex AI is partner-operated with separate pricing — see [Bedrock](https://aws.amazon.com/bedrock/pricing/) or [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/pricing#claude-models). For WebFetch, use the Pricing row in `shared/live-sources.md`.
+
+**ALWAYS use `claude-opus-5` unless the user explicitly names a different model.** This is non-negotiable. Do not use `claude-sonnet-5`, `claude-sonnet-4-6`, or any other model unless the user literally says "use sonnet" or "use haiku". Never downgrade for cost — that's the user's decision, not yours. Use `claude-fable-5` only when the user explicitly asks for Claude Fable 5, "fable", or Anthropic's most capable model — it has different API behavior than the Opus family (see below) and pricing that exceeds Opus-tier. **Use only the exact model ID strings from the table — they are complete as-is; never append date suffixes** (`claude-sonnet-4-6`, never `claude-sonnet-4-6-20251114` or any other date-suffixed variant you might recall from training data). If the user requests an older model not in the table (e.g., "opus 4.5", "sonnet 3.7"), read `shared/models.md` for the exact ID — do not construct one yourself.
 
 ### Claude Fable 5 (`claude-fable-5`) — most capable widely released model
 
-Claude Fable 5 is Anthropic's most capable widely released model, for the most demanding reasoning and long-horizon agentic work. **Claude Mythos 5** (`claude-mythos-5`) offers the same capabilities, pricing, and API surface through Project Glasswing (participation is the only way to access it), succeeding the invitation-only Claude Mythos Preview (`claude-mythos-preview`) — everything below applies to both models. 1M context window (the maximum is also the default), 128K max output. Key API differences from Opus-tier — see `shared/model-migration.md` → Migrating to Claude Fable 5 for details:
+Claude Fable 5 is Anthropic's most capable widely released model, for the most demanding reasoning and long-horizon agentic work; everything below also applies to **Claude Mythos 5** (`claude-mythos-5`, Project Glasswing — same capabilities, pricing, and API surface; successor to the invitation-only `claude-mythos-preview`). 1M context window (the maximum is also the default), 128K max output. Key API differences from Opus-tier — see `shared/model-migration.md` → Migrating to Claude Fable 5 for details:
 
 - **Thinking is always on** — omit the `thinking` parameter entirely (or send `{type: "adaptive"}`). Any other explicit configuration is rejected: `{type: "disabled"}` and `{type: "enabled", budget_tokens: N}` both return a 400. Control depth with `output_config.effort` (supports `low` through `xhigh` and `max`).
-- **Protected thinking = the raw chain of thought, not the summary** — responses carry regular `thinking` blocks (not `redacted_thinking`): `display: "summarized"` returns a readable summary, `"omitted"` (the default) leaves the `thinking` field as an empty string; the raw chain of thought is never exposed on any model. Replay rules: pass thinking blocks back exactly as received on the same model (including empty-text blocks — the API rejects *modified* blocks, not read ones); a **different** model **silently ignores** them (not an error), but ignored blocks still bill input tokens — strip them when switching models for good.
-- **New tokenizer** — the same content tokenizes to roughly 30% more tokens than on Opus-tier models. Don't reuse token counts or `max_tokens` settings measured on other models; re-baseline with `count_tokens`.
-- **`refusal` stop reason** — safety classifiers may decline a request (HTTP 200, `stop_reason: "refusal"`, with a `stop_details` category). A pre-output refusal has an empty `content` array and is not billed at all; a mid-stream refusal bills the already-streamed output — discard the partial output. Always check `stop_reason` before reading `content`. To retry on another model: the beta `fallbacks` parameter (Claude API and Claude Platform on AWS) retries server-side in one round trip; the GA SDKs' `BetaRefusalFallbackMiddleware` + `BetaFallbackState` handle client-side retry everywhere else (incl. Bedrock/Vertex); fallback credit refunds the cache-switch cost of client-side retries. See the migration guide's refusal section.
+- **The raw chain of thought is never returned** — responses carry regular `thinking` blocks (not `redacted_thinking`): `display: "summarized"` returns a readable summary, `"omitted"` (the default) leaves the `thinking` field as an empty string. Replay rules: pass thinking blocks back unchanged on the same model; other models drop them silently (unbilled — nothing to strip); details in `shared/model-migration.md`.
+- **Tokenizer** — same tokenizer as Opus 4.8 (introduced with Opus 4.7). Token counts are roughly unchanged when migrating from Opus 4.7/4.8; per-token pricing differs. Coming from Opus 4.6, Sonnet, Haiku, or older, re-baseline with `count_tokens` (the Opus 4.7 tokenizer uses ~1×–1.35× as many tokens).
+- **`refusal` stop reason — handle it, and opt into fallbacks by default** — safety classifiers may decline a request (HTTP 200, `stop_reason: "refusal"`, with a `stop_details` category); always check `stop_reason` before reading `content`. **When you write `claude-fable-5` or `claude-opus-5` code, include the server-side `fallbacks` parameter by default.** Simplest form: `betas: ["server-side-fallback-2026-07-01"]` + `fallbacks: "default"`, which routes by refusal category so you never maintain a model list. (The older array form — `betas: ["server-side-fallback-2026-06-01"]` + `fallbacks: [{"model": "claude-opus-4-8"}]` — still works; Claude API and Claude Platform on AWS — on Bedrock, Vertex and Foundry, use the SDKs' client-side `BetaRefusalFallbackMiddleware` + `BetaFallbackState` instead). Tell the user you've enabled it; drop it only if they decline. Full semantics (billing, mid-stream refusals, credit repricing) in `shared/model-migration.md` → refusal section. **Per-language code examples in `{lang}/claude-api/README.md` § Refusal Fallbacks cover the array form only** — for the `"default"` mode, follow the raw-HTTP shape in `shared/model-migration.md` → Migrating to Claude Opus 5 → New API features and swap `fallbacks: [{...}]` for `fallbacks: "default"` plus the `-2026-07-01` header; the rest of the request is unchanged.
 - **No assistant prefill** — same as the rest of the 4.6+ family.
 - **30-day data retention required** — Claude Fable 5 is not available under zero data retention; requests from an org whose retention configuration doesn't meet the requirement return `400 invalid_request_error`.
-- **Longer turns, different prompting** — single requests on hard tasks can run many minutes (plan timeouts/streaming/progress UX); effort sweeps should include low/medium for routine work; prompts written for prior models are often too prescriptive and reduce output quality. See `shared/model-migration.md` → Migrating to Claude Fable 5 → Behavioral shifts (prompt-tunable) for the recommended prompt snippets (anti-overplanning, no-tidying, grounded progress claims, boundaries, async sub-agents, memory, `send_to_user`).
+- **Longer turns, different prompting** — single requests on hard tasks can run many minutes (plan timeouts/streaming/progress UX); effort sweeps should include low/medium for routine work; prompts written for prior models are often too prescriptive and reduce output quality. See `shared/model-migration.md` → Migrating to Claude Fable 5 → Behavioral shifts (prompt-tunable) for the recommended prompt snippets.
 
-**CRITICAL: Use only the exact model ID strings from the table above — they are complete as-is. Do not append date suffixes.** For example, use `claude-sonnet-4-6`, never `claude-sonnet-4-6-20251114` or any other date-suffixed variant you might recall from training data. If the user requests an older model not in the table (e.g., "opus 4.5", "sonnet 3.7"), read `shared/models.md` for the exact ID — do not construct one yourself.
-
-A note: if any of the model strings above look unfamiliar to you, that's to be expected — that just means they were released after your training data cutoff. Rest assured they are real models; we wouldn't mess with you like that.
+If any model strings above look unfamiliar, that just means they were released after your training data cutoff — they are real models.
 
 **Live capability lookup:** The table above is cached. When the user asks "what's the context window for X", "does X support vision/thinking/effort", or "which models support Y", query the Models API (`client.models.retrieve(id)` / `client.models.list()`) — see `shared/models.md` for the field reference and capability-filter examples.
 
 ---
 
+## Authentication (Quick Reference)
+
+**An unset `ANTHROPIC_API_KEY` does NOT mean there are no credentials.** The SDKs and the `ant` CLI resolve credentials in this order (first match wins): `ANTHROPIC_API_KEY` → `ANTHROPIC_AUTH_TOKEN` → the `ANTHROPIC_PROFILE`-selected or active OAuth profile from `ant auth login` → Workload Identity Federation env vars → the default profile on disk. A bare `Anthropic()` / `new Anthropic()` / `anthropic.NewClient()` works after `ant auth login` with no env var set.
+
+**When you need to call the API and `ANTHROPIC_API_KEY` is unset, don't ask the user for a key.** First run `ant auth status` — it shows which credential source and profile is active. If it reports an active profile:
+
+- **SDK code or `ant` CLI:** just run it. The zero-arg client constructor and every `ant …` subcommand pick up the profile automatically — no env var needed.
+- **Raw `curl` / HTTP:** get a short-lived token with `ant auth print-credentials --access-token` and send it as `Authorization: Bearer <token>` **plus** the header `anthropic-beta: oauth-2025-04-20` (OAuth tokens go on `Authorization: Bearer`, not `x-api-key:` — converting a curl from an API key is a header change, not a key swap). Always pass `--access-token`; the no-flag form prints JSON, not a bare token.
+
+Only ask the user for a key if `ant auth status` reports no active credential source (or `ant` itself isn't installed). Suggest `ant auth login` as the first option — it stores a profile under `~/.config/anthropic/` that the SDKs read automatically — and an exported `ANTHROPIC_API_KEY` as the alternative.
+
+Full auth details (named profiles, scopes, the API-key-shadows-profile trap, refresh-token expiry): `shared/anthropic-cli.md`.
+
+---
+
 ## Thinking & Effort (Quick Reference)
 
-**Fable 5 / Opus 4.8 / 4.7 — Adaptive thinking only:** Use `thinking: {type: "adaptive"}`. `thinking: {type: "enabled", budget_tokens: N}` returns a 400 — adaptive is the only on-mode. On Opus 4.8 and 4.7, `{type: "disabled"}` and omitting `thinking` both work; on Fable 5, an explicit `{type: "disabled"}` returns a 400 — omit the `thinking` param entirely instead. Sampling parameters (`temperature`, `top_p`, `top_k`) are also removed and will 400. Opus 4.8 keeps the same request surface as 4.7 (no new breaking changes) — see `shared/model-migration.md` → Migrating to Opus 4.8 for the behavioral re-tuning, and → Migrating to Opus 4.7 for the full breaking-change list when coming from 4.6 or earlier. Note: with `thinking` disabled, Opus 4.8 may write longer reasoning into the visible response — leave adaptive thinking on, or add a final-answer-only instruction (see the migration guide).
-**Opus 4.6 — Adaptive thinking (recommended):** Use `thinking: {type: "adaptive"}`. Claude dynamically decides when and how much to think. No `budget_tokens` needed — `budget_tokens` is deprecated on Opus 4.6 and Sonnet 4.6 and should not be used for new code. Adaptive thinking also automatically enables interleaved thinking (no beta header needed). **When the user asks for "extended thinking", a "thinking budget", or `budget_tokens`: always use Fable 5, Opus 4.8, 4.7, or 4.6 with `thinking: {type: "adaptive"}`. The concept of a fixed token budget for thinking is deprecated — adaptive thinking replaces it. Do NOT use `budget_tokens` for new 4.6/4.7/4.8 code and do NOT switch to an older model.** *Gradual-migration carve-out:* `budget_tokens` is still functional on Opus 4.6 and Sonnet 4.6 as a transitional escape hatch — if you're migrating existing code and need a hard token ceiling before you've tuned `effort`, see `shared/model-migration.md` → Transitional escape hatch. Note: this carve-out does **not** apply to Fable 5, Opus 4.7 or 4.8 — `budget_tokens` is fully removed there.
-**Effort parameter (GA, no beta header):** Controls thinking depth and overall token spend via `output_config: {effort: "low"|"medium"|"high"|"max"}` (inside `output_config`, not top-level). Default is `high` (equivalent to omitting it). `max` is supported on Fable 5, Opus 4.6 and later, and Sonnet 4.6 (not Haiku or earlier Sonnets). Opus 4.7 added `"xhigh"` (between `high` and `max`) — the best setting for most coding and agentic use cases on Fable 5 / Opus 4.7/4.8, and the default in Claude Code; use a minimum of `high` for most intelligence-sensitive work. Works on Fable 5, Opus 4.5, Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6. Will error on Sonnet 4.5 / Haiku 4.5. On Fable 5, Opus 4.7 and 4.8, effort matters more than on any prior Opus — re-tune it when migrating, and run long-horizon/agentic tasks at `high`/`xhigh` with the full task spec given up front. Combine with adaptive thinking for the best cost-quality tradeoffs. Lower effort means fewer and more-consolidated tool calls, less preamble, and terser confirmations — `high` is often the sweet spot balancing quality and token efficiency; use `max` when correctness matters more than cost; use `low` for subagents or simple tasks.
+Use adaptive thinking (`thinking: {type: "adaptive"}`) on every current model — Claude dynamically decides when and how much to think. Per-model rules:
 
-**Thinking display — `"omitted"` by default on Fable 5 / Mythos 5 / Opus 4.8 / 4.7:** `display: "summarized"` returns a readable summary of the reasoning; `"omitted"` (the default on all four — a silent change from Opus 4.6, where it was `"summarized"`) streams `thinking` blocks with empty text. `display` controls visibility only — thinking happens and is billed the same under every setting; the raw chain of thought is never exposed on any model. If you stream reasoning to users, the default looks like a long pause before output — set `thinking: {type: "adaptive", display: "summarized"}` explicitly. (Independent of display, echo thinking blocks back unchanged when continuing on the same model; other models silently ignore them — see the migration guide.)
+| Model | Thinking config | Omitting `thinking` | `budget_tokens` | Sampling (`temperature`/`top_p`/`top_k`) | Effort levels |
+|---|---|---|---|---|---|
+| Fable 5 | `{type: "adaptive"}` or omit; explicit `{type: "disabled"}` returns 400 — omit the param instead | Runs adaptive (thinking is always on) | Removed — `{type: "enabled", budget_tokens: N}` returns 400 | Removed — 400 | `low`/`medium`/`high`/`xhigh`/`max` |
+| Claude Opus 5 | `{type: "adaptive"}` or omit; `{type: "disabled"}` accepted **only at effort `high` or below** — 400 at `xhigh`/`max`, and see the disabled-thinking pitfall below | Runs **adaptive** (thinking is on by default — unlike Opus 4.8/4.7) | Removed — 400 | Removed — 400 | `low`–`max` (all five) |
+| Opus 4.8 / 4.7 | `{type: "adaptive"}` is the only on-mode; `{type: "disabled"}` accepted | Runs **without** thinking — set `{type: "adaptive"}` explicitly | Removed — 400 | Removed — 400 | `low`/`medium`/`high`/`xhigh`/`max` |
+| Sonnet 5 | `{type: "adaptive"}` is the only on-mode; `{type: "disabled"}` accepted | Runs adaptive | Removed — 400 | Removed — 400 | `low`/`medium`/`high`/`xhigh`/`max` |
+| Opus 4.6 / Sonnet 4.6 | `{type: "adaptive"}` (recommended; auto-enables interleaved thinking, no beta header) | Set `{type: "adaptive"}` explicitly | Deprecated — do not use in new code; transitional escape hatch only (see below) | Allowed | `low`/`medium`/`high`/`max` (`xhigh` arrived with Opus 4.7) |
+| Older (Sonnet 4.5, Haiku 4.5, …) — only if explicitly requested | `{type: "enabled", budget_tokens: N}` | No thinking | Required for thinking; must be less than `max_tokens`, minimum 1024 — errors otherwise | Allowed | `effort` works on Opus 4.5 (`low`/`medium`/`high` only — no `xhigh`/`max`); errors on Sonnet 4.5 / Haiku 4.5 |
 
-**Task Budgets (beta, Fable 5 / Opus 4.7 / 4.8):** `output_config: {task_budget: {type: "tokens", total: N}}` tells the model how many tokens it has for a full agentic loop — it sees a running countdown and self-moderates (minimum 20,000; beta header `task-budgets-2026-03-13`). Distinct from `max_tokens`, which is an enforced per-response ceiling the model is not aware of. See `shared/model-migration.md` → Task Budgets.
+Opus 4.8 keeps the same request surface as 4.7 (no new breaking changes) — see `shared/model-migration.md` → Migrating to Opus 4.8 for the behavioral re-tuning, and → Migrating to Opus 4.7 for the full breaking-change list when coming from 4.6 or earlier. With `thinking` disabled, Opus 4.8 may write longer reasoning into the visible response — leave adaptive thinking on, or add a final-answer-only instruction (see the migration guide).
 
-**Sonnet 4.6:** Supports adaptive thinking (`thinking: {type: "adaptive"}`). `budget_tokens` is deprecated on Sonnet 4.6 — use adaptive thinking instead.
-
-**Older models (only if explicitly requested):** If the user specifically asks for Sonnet 4.5 or another older model, use `thinking: {type: "enabled", budget_tokens: N}`. `budget_tokens` must be less than `max_tokens` (minimum 1024). Never choose an older model just because the user mentions `budget_tokens` — use Opus 4.8 with adaptive thinking instead.
+- **Effort (GA, no beta header):** `output_config: {effort: "low"|"medium"|"high"|"xhigh"|"max"}` — inside `output_config`, not top-level; default `high` (equivalent to omitting it). Controls thinking depth and overall token spend; combine with adaptive thinking for the best cost-quality tradeoffs. `xhigh` (added on Opus 4.7, between `high` and `max`) is the best setting for most coding and agentic use cases on Fable 5 / Opus 4.7/4.8 / Sonnet 5, and the default in Claude Code; effort matters more on those models than on any prior model in their tier — re-tune it when migrating, and run long-horizon/agentic tasks at `high`/`xhigh` with the full task spec given up front. Use a minimum of `high` for intelligence-sensitive work, `max` when correctness matters more than cost, and `low` for subagents or simple tasks — lower effort means fewer and more-consolidated tool calls, less preamble, and terser confirmations (`high` is often the sweet spot balancing quality and token efficiency).
+- **Thinking display — `"omitted"` by default on Fable 5 / Mythos 5 / Opus 5 / 4.8 / 4.7 / Sonnet 5:** `display: "summarized"` returns a readable summary of the reasoning; `"omitted"` (the default on all six — a silent change from Opus 4.6 and Sonnet 4.6, where it was `"summarized"`) streams `thinking` blocks with empty text. `display` controls visibility only — thinking happens and is billed the same under every setting; the raw chain of thought is never exposed on any model. If you stream reasoning to users, the default looks like a long pause before output — set `thinking: {type: "adaptive", display: "summarized"}` explicitly. (Independent of display, echo thinking blocks back unchanged when continuing on the same model; other models silently ignore them — see the migration guide.)
+- **When the user asks for "extended thinking", a "thinking budget", or `budget_tokens`:** always use Fable 5, Opus 5, 4.8, 4.7, or 4.6 with `thinking: {type: "adaptive"}` — the fixed thinking-token-budget concept is deprecated and adaptive thinking replaces it. Do NOT use `budget_tokens` for new 4.6/4.7/4.8 code and do NOT switch to an older model just because the user mentions it. *Gradual-migration carve-out:* `budget_tokens` is still functional on Opus 4.6 and Sonnet 4.6 only, as a transitional escape hatch for existing code that needs a hard token ceiling before you've tuned `effort` — see `shared/model-migration.md` → Transitional escape hatch. It is fully removed on Fable 5, Opus 5/4.7/4.8, and Sonnet 5.
 
 ---
 
 ## Compaction (Quick Reference)
 
-**Beta, Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** For long-running conversations that may exceed the 1M context window, enable server-side compaction. The API automatically summarizes earlier context when it approaches the trigger threshold (default: 150K tokens). Requires beta header `compact-2026-01-12`.
+**Beta, Fable 5, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, and Sonnet 4.6.** For long-running conversations that may exceed the 1M context window, enable server-side compaction. The API automatically summarizes earlier context when it approaches the trigger threshold (default: 150K tokens). Requires beta header `compact-2026-01-12`.
 
 **Critical:** Append `response.content` (not just the text) back to your messages on every turn. Compaction blocks in the response must be preserved — the API uses them to replace the compacted history on the next request. Extracting only the text string and appending that will silently lose the compaction state.
 
@@ -231,7 +254,7 @@ See `{lang}/claude-api/README.md` (Compaction section) for code examples. Full d
 
 **Prefix match.** Any byte change anywhere in the prefix invalidates everything after it. Render order is `tools` → `system` → `messages`. Keep stable content first (frozen system prompt, deterministic tool list), put volatile content (timestamps, per-request IDs, varying questions) after the last `cache_control` breakpoint.
 
-**Mid-conversation operator instructions** (beta header `mid-conversation-system-2026-04-07`, on supporting models): append `{"role": "system", ...}` to `messages[]` instead of editing top-level `system`. Preserves the cached history prefix and is the prompt-injection-safe operator channel. See `shared/prompt-caching.md` § Mid-conversation system messages.
+**Mid-conversation operator instructions** (Claude Opus 5, Claude Opus 4.8, Claude Fable 5, Claude Mythos 5; not Claude Sonnet 5; no beta header): append `{"role": "system", ...}` to `messages[]` instead of editing top-level `system`. Preserves the cached history prefix and is the prompt-injection-safe operator channel. See `shared/prompt-caching.md` § Mid-conversation system messages.
 
 **Top-level auto-caching** (`cache_control: {type: "ephemeral"}` on `messages.create()`) is the simplest option when you don't need fine-grained placement. Max 4 breakpoints per request. Minimum cacheable prefix is ~1024 tokens — shorter prefixes silently won't cache.
 
@@ -241,11 +264,130 @@ For placement patterns, architectural guidance, and the silent-invalidator audit
 
 ---
 
+## Fast Mode (Quick Reference)
+
+**Research preview, Claude Opus 5 / Opus 4.8 only** — Claude API and Managed Agents, not Bedrock / Google Cloud / Foundry. Opus 4.7 fast mode has been removed: `speed: "fast"` on 4.7 returns an error. Fast mode on Claude Opus 5 is priced at $10 / $50 per MTok. Fast mode runs the same model at up to 2.5x higher output tokens per second, at premium pricing. Three things are required on every request: use the **beta** messages endpoint (`client.beta.messages.…`), pass the beta flag `fast-mode-2026-02-01`, and set `speed: "fast"` as a top-level request parameter (not a header, not in `extra_body`).
+
+```python
+client.beta.messages.create(
+    model="claude-opus-5", max_tokens=4096,
+    speed="fast", betas=["fast-mode-2026-02-01"],
+    messages=[...],
+)
+```
+
+| Language | Beta flag | Speed parameter |
+|---|---|---|
+| Python | `betas=["fast-mode-2026-02-01"]` | `speed="fast"` |
+| TypeScript / Ruby | `betas: ["fast-mode-2026-02-01"]` | `speed: "fast"` |
+| Go | `[]anthropic.AnthropicBeta{anthropic.AnthropicBetaFastMode2026_02_01}` | `Speed: anthropic.BetaMessageNewParamsSpeedFast` |
+| Java | `.addBeta(AnthropicBeta.FAST_MODE_2026_02_01)` | `.speed(MessageCreateParams.Speed.FAST)` |
+| C# | `Betas = ["fast-mode-2026-02-01"]` | `Speed = Speed.Fast` (`Anthropic.Models.Beta.Messages`) |
+| PHP | `betas: ['fast-mode-2026-02-01']` | `speed: 'fast'` |
+| cURL | `anthropic-beta: fast-mode-2026-02-01` header | `"speed": "fast"` in body |
+
+`response.usage.speed` reports which speed was used. Fast mode has its own rate limit separate from standard Opus; on 429, either retry after the `retry-after` delay or drop `speed` and fall back to standard (note: switching speed invalidates prompt cache). Not available with Batch API, Priority Tier, Claude Platform on AWS, or third-party platforms.
+
+**Priority Tier does not cover Claude Opus 5.** It is supported on every other current model, including Claude Fable 5 and Opus 4.8, but Claude Opus 5, Claude Sonnet 5, Claude Mythos 5, and Mythos Preview are excluded — a Priority Tier request naming one of them fails validation.
+
+---
+
+## Task Budgets (Quick Reference)
+
+**Beta, Claude Opus 5 / Fable 5 / Sonnet 5 / Opus 4.8 / 4.7.** A task budget gives Claude a token ceiling for an agentic loop so it paces itself and finishes gracefully instead of being cut off — distinct from `max_tokens`, which is an enforced per-response ceiling the model is not aware of. Minimum `total`: 20,000. Set `task_budget` inside `output_config` on `client.beta.messages.stream(...)` with beta flag `task-budgets-2026-03-13` — use streaming so the large `max_tokens` doesn't hit HTTP timeouts (full details: `shared/model-migration.md` → Task Budgets):
+
+```python
+with client.beta.messages.stream(
+    model="claude-opus-5", max_tokens=128000,
+    output_config={"effort": "high", "task_budget": {"type": "tokens", "total": 64000}},
+    betas=["task-budgets-2026-03-13"],
+    messages=[...], tools=[...],
+) as stream:
+    response = stream.get_final_message()
+```
+
+`task_budget` fields: `type` (always `"tokens"`), `total`, and optional `remaining` (defaults to `total`). The server injects a countdown marker Claude sees during generation; the budget counts what Claude generates and the tool results it reads this turn — **not** the full history you resend each request.
+
+**Observing spend:** accumulate `response.usage.output_tokens` (plus the token count of the tool-result blocks you append) across loop iterations if you want to display progress. Leave `remaining` unset in the normal loop — the server tracks the countdown itself, and passing a client-computed `remaining` while also resending full history under-reports the budget. **Only pass `remaining`** when you compact or rewrite history between requests and the server can no longer derive prior spend.
+
+---
+
+## Provider Clients (Quick Reference)
+
+When targeting Claude on a third-party platform, use that platform's dedicated client class — not the first-party `Anthropic()` client with a `base_url` override. After construction the client exposes the same `messages.create` / `.stream` surface as the first-party SDK.
+
+### Amazon Bedrock
+
+Use the **Mantle** client (Messages-API Bedrock endpoint). Bedrock model IDs take an `anthropic.` prefix (e.g. `"anthropic.claude-opus-5"`). Region is required.
+
+| Language | Client |
+|---|---|
+| Python | `from anthropic import AnthropicBedrockMantle` → `AnthropicBedrockMantle(aws_region="…")` |
+| TypeScript | `import { AnthropicBedrockMantle } from "@anthropic-ai/bedrock-sdk"` → `new AnthropicBedrockMantle({ awsRegion: "…" })` |
+| Go | `bedrock.NewMantleClient(ctx, bedrock.MantleClientConfig{ AWSRegion: "…" })` |
+| Java | `AnthropicOkHttpClient.builder().backend(BedrockMantleBackend.fromEnv()).build()` (from `com.anthropic.bedrock.backends`) |
+| C# | `new AnthropicBedrockMantleClient(new() { AwsRegion = "…" })` (package `Anthropic.Bedrock`) |
+| PHP | `use Anthropic\Bedrock\MantleClient;` → `new MantleClient(awsRegion: '…')` |
+| Ruby | `Anthropic::BedrockMantleClient.new(aws_region: "…")` |
+
+`AnthropicBedrock` / `BedrockClient` / `BedrockBackend` (without `Mantle`) are the legacy `bedrock-runtime` InvokeModel path — prefer the Mantle client for new code.
+
+### Microsoft Foundry
+
+| Language | Client |
+|---|---|
+| Python | `from anthropic import AnthropicFoundry` → `AnthropicFoundry(api_key=…, resource="…")` |
+| TypeScript | `import AnthropicFoundry from "@anthropic-ai/foundry-sdk"` → `new AnthropicFoundry({ … })` |
+| Java | `AnthropicOkHttpClient.builder().backend(FoundryBackend.fromEnv()).build()` (from `com.anthropic.foundry.backends`) |
+| C# | `new AnthropicFoundryClient(new AnthropicFoundryApiKeyCredentials(…))` (package `Anthropic.Foundry`) |
+| PHP | `Foundry\Client::withCredentials(…)` |
+
+The Go and Ruby SDKs do not currently support Foundry. For Ruby, use the standard `Anthropic::Client.new(base_url: "<foundry endpoint>")` as a fallback (Entra ID auth is not built in). For Claude Platform on AWS, see `shared/claude-platform-on-aws.md`.
+
+### Google Cloud Vertex AI
+
+Two required constructor args: GCP `project_id` and `region`. Vertex model IDs take **no prefix** — current-generation models (Opus 4.8/4.7/4.6, Sonnet 5, Sonnet 4.6) use the bare first-party ID (e.g. `"claude-opus-5"`); dated-snapshot models use an `@` version separator (e.g. `claude-opus-4-5@20251101`, **not** `claude-opus-4-5-20251101`). Auth is GCP ADC (`gcloud auth application-default login`); no Anthropic API key. `region` can be `"global"` (recommended), a multi-region (`"us"`/`"eu"`), or a specific region. After construction, use the same `messages.create` / `.stream` surface.
+
+| Language | Client |
+|---|---|
+| Python | `from anthropic import AnthropicVertex` → `AnthropicVertex(project_id="…", region="…")` (install `"anthropic[vertex]"`) |
+| TypeScript | `import { AnthropicVertex } from "@anthropic-ai/vertex-sdk"` → `new AnthropicVertex({ projectId, region })` |
+| Go | `import "github.com/anthropics/anthropic-sdk-go/vertex"` → `anthropic.NewClient(vertex.WithGoogleAuth(ctx, region, projectID))` |
+| Java | `AnthropicOkHttpClient.builder().backend(VertexBackend.builder().region("…").project("…").build()).build()` (from `com.anthropic.vertex.backends`) |
+| C# | `new AnthropicClient { Backend = new VertexBackend(projectId, region) }` (package `Anthropic.Vertex`) |
+| PHP | `use Anthropic\Vertex;` → `Vertex\Client::fromEnvironment(location: '…', projectId: '…')` — note `location`, not `region` |
+| Ruby | `Anthropic::VertexClient.new(region: "…", project_id: "…")` |
+
+---
+
+## Context Editing (Quick Reference)
+
+**Beta.** Context editing **clears** old tool results or thinking blocks from the conversation before the model sees it; it is **not compaction** (which summarizes). On `client.beta.messages.*` with beta `context-management-2025-06-27`, pass `context_management.edits` with a strategy type:
+
+```python
+client.beta.messages.create(
+    model="claude-opus-5", max_tokens=4096,
+    betas=["context-management-2025-06-27"],
+    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
+    tools=[...], messages=[...],
+)
+```
+
+Strategy types: `clear_tool_uses_20250919` (clears old tool results; optional `clear_tool_inputs: true` also clears the tool_use params) and `clear_thinking_20251015` (clears thinking blocks). Do **not** use `compact_20260112` or beta `compact-2026-01-12` — those are the separate compaction feature.
+
+---
+
+## Mid-Conversation System Messages (Quick Reference)
+
+**Claude Opus 5, Claude Opus 4.8, Claude Fable 5, and Claude Mythos 5; not Claude Sonnet 5; no beta header.** Append `{"role": "system", "content": "…"}` to the `messages` array (not the top-level `system` field) to add an operator instruction mid-conversation without invalidating the cached prefix. Use the regular `client.messages.create` — there is no beta. A mid-conversation system message must follow a `user` message (or an `assistant` message ending in server-tool use), and must be either the last entry in `messages` or be followed by an `assistant` turn — it cannot be `messages[0]`. Availability: `shared/platform-availability.md`. See `shared/prompt-caching.md` § Mid-conversation system messages.
+
+---
+
 ## Managed Agents (Beta)
 
 **Managed Agents** is a third surface: server-managed stateful agents with Anthropic-hosted tool execution. You create a persisted, versioned Agent config (`POST /v1/agents`), then start Sessions that reference it. Each session provisions a container as the agent's workspace — bash, file ops, and code execution run there; the agent loop itself runs on Anthropic's orchestration layer and acts on the container via tools. The session streams events; you send messages and tool results back.
 
-**Managed Agents is available on the first-party API and Claude Platform on AWS.** It is **not** available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry — for agents there, use Claude API + tool use.
+Availability: `shared/platform-availability.md`. For agents on Bedrock / Vertex / Foundry (where Managed Agents is unsupported), use Claude API + tool use.
 
 **Mandatory flow:** Agent (once) → Session (every run). `model`/`system`/`tools` live on the agent, never the session. See `shared/managed-agents-overview.md` for the full reading guide, beta headers, and pitfalls.
 
@@ -255,76 +397,113 @@ For placement patterns, architectural guidance, and the silent-invalidator audit
 
 | Subcommand | Action |
 |---|---|
-| `managed-agents-onboard` | Walk the user through setting up a Managed Agent from scratch. **Read `shared/managed-agents-onboarding.md` immediately** and follow its interview script: mental model → know-or-explore branch → template config → session setup → **pre-flight viability check** → emit code. The viability check (reconcile the stated job against configured tools/credentials/data) catches under-resourced setups — missing a tool, credential, or data access — before the agent burns budget. Do not summarize — run the interview. |
+| `managed-agents-onboard` | Walk the user through setting up a Managed Agent from scratch. **Read `shared/managed-agents-onboarding.md` immediately** and follow its interview script: **describe → configure the agent (propose, don't interrogate) → environment → session** (same arc as the Console quickstart, auth deferred to the session step) — defaults and inline suggestions do the work, with a silent viability gate (job vs tools/credentials/data) before any code is emitted. Do not summarize — run the interview. |
 
-**Reading guide:** Start with `shared/managed-agents-overview.md`, then the topical `shared/managed-agents-*.md` files (core, environments, tools, events, outcomes, multiagent, webhooks, memory, scheduled-deployments, client-patterns, onboarding, api-reference). For Python, TypeScript, Go, Ruby, PHP, and Java, read `{lang}/managed-agents/README.md` for code examples. For cURL, read `curl/managed-agents.md`. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI (`ant`) is one convenient way to create agents and environments from version-controlled YAML — see `shared/anthropic-cli.md`. If a binding you need isn't shown in the language README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# has beta Managed Agents support via `client.Beta.Agents` and related namespaces.
+**Reading guide:** Start with `shared/managed-agents-overview.md`, then the topical `shared/managed-agents-*.md` files (core, environments, tools, events, outcomes, multiagent, webhooks, memory, scheduled-deployments, client-patterns, onboarding, api-reference). For Python, TypeScript, Go, Ruby, PHP, and Java, read `{lang}/managed-agents/README.md` for code examples. For cURL, read `curl/managed-agents.md`. **Agents are persistent — create once, reference by ID.** Define agents and environments as version-controlled YAML applied with the `ant` CLI — this is the recommended flow (see `shared/anthropic-cli.md`): the CLI owns the control plane (creating and updating agents), your code owns the data plane (`sessions.create` with the stored agent ID). Call `agents.create()` in code only when you must provision programmatically; either way, store the returned agent ID and pass it to every subsequent `sessions.create`; never call `agents.create()` in the request path. If a binding you need isn't shown in the language README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# has beta Managed Agents support via `client.Beta.Agents` and related namespaces — see `csharp/claude-api/README.md` for details, or `curl/managed-agents.md` for raw HTTP reference.
 
 **When the user wants to set up a Managed Agent from scratch** (e.g. "how do I get started", "walk me through creating one", "set up a new agent"): read `shared/managed-agents-onboarding.md` and run its interview — same flow as the `managed-agents-onboard` subcommand.
 
-**When the user asks "how do I write the client code for X":** reach for `shared/managed-agents-client-patterns.md` — covers lossless stream reconnect, `processed_at` queued/processed gate, interrupt, `tool_confirmation` round-trip, the correct idle/terminated break gate, post-idle status race, stream-first ordering, file-mount gotchas, keeping credentials host-side via custom tools, etc.
+**When the user asks "how do I write the client code for X":** reach for `shared/managed-agents-client-patterns.md` — covers lossless stream reconnect, `processed_at` queued/processed gate, interrupt, `tool_confirmation` round-trip, the correct idle/terminated break gate, post-idle status race, stream-first ordering, file-mount gotchas, etc. For credentials, lead with vault `environment_variable` credentials — the first-class mechanism; secrets are substituted at egress and never enter the sandbox (`shared/managed-agents-tools.md` → Vaults). Keeping credentials host-side via custom tools is the fallback where vault credentials don't fit (e.g. self-hosted sandboxes).
 
-**When the user wants the agent to run on a schedule** (cron, "every night", "weekly report"): read `shared/managed-agents-scheduled-deployments.md` — deployments fire sessions autonomously on a cron cadence, with run records, retries, and auto-pause.
+**When the user wants the agent to run on a schedule** (cron, "every night", "weekly report"): read `shared/managed-agents-scheduled-deployments.md` — deployments fire sessions autonomously on a cron cadence, with per-firing run records and lifecycle controls (pause/unpause/archive).
 
+---
+
+## Server Tools (Quick Reference)
+
+Server-side tools run on Anthropic's infrastructure — no client-side execution loop. Declare in `tools`; results arrive as content blocks in the same response. **No beta header** unless noted. **Prefer the latest type variant your model supports.** The `_20260209` web search / web fetch variants below (dynamic filtering) require Opus 5/4.8/4.7/4.6, Sonnet 5, or Sonnet 4.6; the basic variants for older models are listed after the table.
+
+| Tool | `type` | `name` | Key optional params | Result block type |
+|---|---|---|---|---|
+| Web search | `web_search_20260209` | `web_search` | `max_uses`, `allowed_domains`/`blocked_domains`, `user_location` | `web_search_tool_result` → `.content` is a list of `web_search_result` |
+| Web fetch | `web_fetch_20260209` | `web_fetch` | `max_uses`, `allowed_domains`/`blocked_domains`, `citations`, `max_content_tokens` | `web_fetch_tool_result` → `.content` is a `web_fetch_result` with a `document` block |
+| Code execution | `code_execution_20260521` | `code_execution` | none | `bash_code_execution_tool_result` → `.content.stdout` / `.stderr` / `.return_code` |
+| Tool search (regex) | `tool_search_tool_regex_20251119` | `tool_search_tool_regex` | mark other tools `defer_loading: true` | `tool_search_tool_result` |
+| Tool search (BM25) | `tool_search_tool_bm25_20251119` | `tool_search_tool_bm25` | mark other tools `defer_loading: true` | `tool_search_tool_result` |
+
+`web_search_20260209` / `web_fetch_20260209` have built-in dynamic filtering — code execution runs under the hood, so do **not** separately declare `code_execution` in `tools` (a second execution environment confuses the model). For models older than Opus 4.6 / Sonnet 4.6, use the basic variants `web_search_20250305` / `web_fetch_20250910` instead; on Vertex AI only basic `web_search_20250305` is available. `code_execution_20260120` (REPL persistence + programmatic tool calling) runs on Opus 4.5+ / Sonnet 4.5+. **Go SDK only**: `code_execution_20260521` lives under `client.Beta.Messages.New` with `Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25"}` (other languages use plain `client.messages.create`); `code_execution_20260120` uses the non-beta `client.Messages.New` in Go like everywhere else. Web fetch only fetches URLs already present in the conversation. Provider availability varies by tool — see `shared/platform-availability.md`. See `shared/tool-use-concepts.md` for `pause_turn` handling.
+
+## Document & File Input (Quick Reference)
+
+**PDF (base64, no beta):** `{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": <b64 string>}}` in user content, placed before the text block. Base64 string must have no newlines. Limits: 32 MB request, 600 pages (100 for 200k-context models). Java: `ContentBlockParam.ofDocument(DocumentBlockParam... Base64PdfSource.builder().data(...))`.
+
+**Files API (beta `files-api-2025-04-14`):** upload via `client.beta.files.upload(...)` → response `id` is the `file_id`. Reference it as `{"type": "document", "source": {"type": "file", "file_id": "..."}}` for PDF/text, or `{"type": "image", ...}` for images — the content-block type must match the file's MIME type. The beta header is required on **both** the upload and the `messages.create` that references the file. Availability: `shared/platform-availability.md`.
+
+**Citations (no beta):** set `citations: {enabled: true}` on each `document` content block (all or none). Response splits into multiple `text` blocks; cited blocks carry a `citations` array. Each citation has `cited_text`, `document_index`, `document_title`, and a location by `type`: `char_location` (`start_char_index`/`end_char_index`) for plain text, `page_location` (`start_page_number`/`end_page_number`, 1-indexed) for PDF, `content_block_location` for custom content. Incompatible with `output_config.format` (returns a 400).
+
+## Tool Use Patterns (Quick Reference)
+
+**Strict tool use (no beta):** set `strict: true` as a top-level field on the tool definition (alongside `name`/`description`/`input_schema`), **not** on `tool_choice`. Schema must have `additionalProperties: false` + `required`. Guarantees `tool_use.input` validates exactly. Go: `Strict: anthropic.Bool(true)` + `additionalProperties` via `InputSchema.ExtraFields`; Java: `.strict(true)` + `.putAdditionalProperty("additionalProperties", JsonValue.from(false))`.
+
+**Parallel tool use (default on):** one assistant message may contain multiple `tool_use` blocks. Execute them concurrently, then return **all** `tool_result` blocks in a **single** user message — splitting them across multiple messages silently trains Claude to stop making parallel calls. For a failed tool, return `tool_result` with `is_error: true` — don't drop it.
+
+**Tool Runner (SDK beta helper):** drives the tool-call loop for you via `client.beta.messages.*`. Python: `@beta_tool` decorator + `client.beta.messages.tool_runner(...)` → `runner.until_done()`. TypeScript: `betaZodTool({...})` from `@anthropic-ai/sdk/helpers/beta/zod` + `client.beta.messages.toolRunner(...)` → `await runner`. Go: `toolrunner.NewBetaToolFromJSONSchema(...)` + `client.Beta.Messages.NewToolRunner(...)` → `.RunToCompletion(ctx)`. Java requires `.addBeta("structured-outputs-2025-11-13")`. Ruby: `Anthropic::BaseTool` subclass + `client.beta.messages.tool_runner(...)`. PHP: `BetaRunnableTool` + `->toolRunner(...)`. C#: raw JSON-schema tools + `BetaToolRunner` via `client.Beta.Messages.ToolRunner(...)`.
+
+**Programmatic tool calling (no beta header):** Claude calls your custom tool from inside code execution. Add `{"type": "code_execution_20260120", "name": "code_execution"}` **and** set `"allowed_callers": ["code_execution_20260120"]` on your custom tool. Opus 4.5+ / Sonnet 4.5+ (availability: `shared/platform-availability.md`). When responding to a pending programmatic call, the user message must contain **only** `tool_result` blocks (no text). Not compatible with `strict: true`, `disable_parallel_tool_use`, forced `tool_choice`, or MCP tools.
+
+## Other API Surfaces (Quick Reference)
+
+**Message Batches (no beta; availability: `shared/platform-availability.md`):** `client.messages.batches.create(requests=[{custom_id, params}, ...])` → poll `client.messages.batches.retrieve(id).processing_status` until `"ended"` → stream `client.messages.batches.results(id)`. Each result has `.custom_id` + `.result.type` (`succeeded`/`errored`/`canceled`/`expired`); on success read `.result.message.content`. Python wraps requests as `Request(custom_id=..., params=MessageCreateParamsNonStreaming(...))`. Results arrive in **any order** — key by `custom_id`, never by position.
+
+**Models API (no beta; availability: `shared/platform-availability.md`):** `client.models.list()` (auto-paginates) and `client.models.retrieve("claude-opus-5")`. Each model object has `id`, `display_name`, `created_at`, and — since Mar 2026 — `max_input_tokens` (the context window), `max_tokens` (the output cap), and `capabilities`. There is no `context_window` field.
+
+**Stop details (GA, Opus 4.7+):** `response.stop_details` is populated **only when `stop_reason == "refusal"`** (fields: `type: "refusal"`, `category: "cyber"|"bio"|null`, `explanation`). It is `null` for every other `stop_reason` (`end_turn`, `max_tokens`, `tool_use`, `pause_turn`, …) — always guard before reading.
+
+**Client config (no beta):** `timeout` default 10 min; **units differ by SDK** — Python/Ruby: seconds; TypeScript: **milliseconds**; Go `option.WithRequestTimeout(time.Duration)`; Java `Duration`; C# `TimeSpan`. TS scales the default up to 60 min for large `max_tokens` on non-streaming requests; Java does so for streaming requests (Java non-streaming scales 30s–10 min). `max_retries`/`maxRetries` default 2 (retries 408/409/429/5xx + connection errors). `base_url` (or `ANTHROPIC_BASE_URL` env). Per-request override: Python `client.with_options(timeout=5.0).messages.create(...)`; TS `client.messages.create({...}, {timeout: 5_000})`; Ruby `request_options: {timeout: 5}`. Timeouts are retried — wall-clock can reach `timeout × (max_retries+1)`.
+
+## Workload Identity Federation (Quick Reference)
+
+**GA, no beta header.** Construct the normal zero-arg client (`Anthropic()` / `new Anthropic()` / `anthropic.NewClient()` / `AnthropicOkHttpClient.fromEnv()`); the SDK auto-detects WIF when **all** of `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID`, and `ANTHROPIC_IDENTITY_TOKEN_FILE` (or `ANTHROPIC_IDENTITY_TOKEN`) are set, exchanges the JWT at `/v1/oauth/token`, and auto-refreshes. `ANTHROPIC_WORKSPACE_ID` does not gate activation — required only when the federation rule spans multiple workspaces (else 400 `workspace_id_required`), optional for single-workspace rules. `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` (even empty) outrank WIF, and a set `ANTHROPIC_PROFILE` also wins over the federation env vars (a missing named profile is an error, not a fall-through) — unset all three.
 
 ---
 
 ## Reading Guide
 
-After detecting the language, read the relevant files based on what the user needs:
+After detecting the language, read the relevant files based on what the user needs.
+
+**All SDK languages use the same multi-file layout** — directory `{lang}/claude-api/` containing `README.md` (install, client init, basic request, thinking, caching, stop details, misc), `tool-use.md` (tool definitions, agentic loop, Anthropic-defined tools, structured outputs), `streaming.md`, `batches.md`, `files-api.md`. Not every language has every file (e.g., Ruby has no `batches.md`); if a file is absent, that feature's example is not yet documented for that language — fall back to the cURL shape or WebFetch the SDK repo from `shared/live-sources.md`. **cURL** → `curl/examples.md`.
+
+The Quick Task Reference below uses the `{lang}/claude-api/FILE.md` path notation for all languages.
 
 ### Quick Task Reference
 
 **Single text classification/summarization/extraction/Q&A:**
-→ Read only `{lang}/claude-api/README.md`
+→ Read only `{lang}/claude-api/README.md` — **always read the README first** for any task (installation, quick start, common patterns, error handling)
 
 **Chat UI or real-time response display:**
 → Read `{lang}/claude-api/README.md` + `{lang}/claude-api/streaming.md`
 
 **Long-running conversations (may exceed context window):**
 → Read `{lang}/claude-api/README.md` — see Compaction section
-**Migrating to a newer model (Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 4.6) or replacing a retired model:**
+**Migrating to a newer model (Fable 5 / Opus 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 5 / Sonnet 4.6), replacing a retired model, or translating `budget_tokens` / prefill patterns to the current API:**
 → Read `shared/model-migration.md`
 **Prompting or tuning Fable 5 (long turns, effort, verbosity, autonomous runs, sub-agents):**
 → Read `shared/model-migration.md` → Migrating to Fable 5 → Behavioral shifts (prompt-tunable) + Long-running agent recommendations
 **Prompt caching / optimize caching / "why is my cache hit rate low":**
-→ Read `shared/prompt-caching.md` + `{lang}/claude-api/README.md` (Prompt Caching section)
+→ Read `shared/prompt-caching.md` (prefix-stability design, breakpoint placement, anti-patterns that silently invalidate cache) + `{lang}/claude-api/README.md` (Prompt Caching section)
 **Count tokens in a file / prompt / diff ("how many tokens is X"):**
 → Read `shared/token-counting.md` — use `messages.count_tokens`, never `tiktoken`
 
 **Function calling / tool use / agents:**
-→ Read `{lang}/claude-api/README.md` + `shared/tool-use-concepts.md` + `{lang}/claude-api/tool-use.md`
+→ Read `{lang}/claude-api/README.md` + `shared/tool-use-concepts.md` (conceptual foundations: function calling, code execution, memory, structured outputs) + `{lang}/claude-api/tool-use.md` (language-specific code examples: tool runner, manual loop, code execution, memory, structured outputs)
 
 **Agent design (tool surface, context management, caching strategy):**
-→ Read `shared/agent-design.md`
+→ Read `shared/agent-design.md` (bash vs. dedicated tools, programmatic tool calling, tool search/skills, context editing vs. compaction vs. memory, caching principles)
 
-**Batch processing (non-latency-sensitive):**
+**Batch processing (non-latency-sensitive; runs asynchronously at 50% cost):**
 → Read `{lang}/claude-api/README.md` + `{lang}/claude-api/batches.md`
 
-**File uploads across multiple requests:**
+**File uploads across multiple requests (same file without re-uploading):**
 → Read `{lang}/claude-api/README.md` + `{lang}/claude-api/files-api.md`
 
+**Debugging HTTP errors or implementing error handling:**
+→ Read `shared/error-codes.md` — per-SDK typed exception class table and the Go `errors.As` pattern
+
+**Latest official documentation:**
+→ WebFetch the URLs in `shared/live-sources.md`
+
 **Managed Agents (server-managed stateful agents with workspace):**
-→ Read `shared/managed-agents-overview.md` + the rest of the `shared/managed-agents-*.md` files. For Python, TypeScript, Go, Ruby, PHP, and Java, read `{lang}/managed-agents/README.md` for code examples. For cURL, read `curl/managed-agents.md`. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI (`ant`) is one convenient way to create agents and environments from version-controlled YAML — see `shared/anthropic-cli.md`. If a binding you need isn't shown in the language README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# has beta Managed Agents support — see `csharp/claude-api.md` for details, or `curl/managed-agents.md` for raw HTTP reference.
-
-### Claude API (Full File Reference)
-
-Read the **language-specific Claude API folder** (`{language}/claude-api/`):
-
-1. **`{language}/claude-api/README.md`** — **Read this first.** Installation, quick start, common patterns, error handling.
-2. **`shared/tool-use-concepts.md`** — Read when the user needs function calling, code execution, memory, or structured outputs. Covers conceptual foundations.
-3. **`shared/agent-design.md`** — Read when designing an agent: bash vs. dedicated tools, programmatic tool calling, tool search/skills, context editing vs. compaction vs. memory, caching principles.
-4. **`{language}/claude-api/tool-use.md`** — Read for language-specific tool use code examples (tool runner, manual loop, code execution, memory, structured outputs).
-5. **`{language}/claude-api/streaming.md`** — Read when building chat UIs or interfaces that display responses incrementally.
-6. **`{language}/claude-api/batches.md`** — Read when processing many requests offline (not latency-sensitive). Runs asynchronously at 50% cost.
-7. **`{language}/claude-api/files-api.md`** — Read when sending the same file across multiple requests without re-uploading.
-8. **`shared/prompt-caching.md`** — Read when adding or optimizing prompt caching. Covers prefix-stability design, breakpoint placement, and anti-patterns that silently invalidate cache.
-9. **`shared/error-codes.md`** — Read when debugging HTTP errors or implementing error handling.
-10. **`shared/model-migration.md`** — Read when upgrading to newer models, replacing retired models, or translating `budget_tokens` / prefill patterns to the current API.
-11. **`shared/live-sources.md`** — WebFetch URLs for fetching the latest official documentation.
-
-> **Note:** For Java, Go, Ruby, C#, PHP, and cURL — these have a single file each covering all basics. Read that file plus `shared/tool-use-concepts.md` and `shared/error-codes.md` as needed.
-
-> **Note:** For the Managed Agents file reference, see the `## Managed Agents (Beta)` section above — it lists every `shared/managed-agents-*.md` file and the language-specific READMEs.
+→ See the reading guide in the `## Managed Agents (Beta)` section above — it lists every `shared/managed-agents-*.md` file and the language-specific READMEs (`{lang}/managed-agents/README.md`, `curl/managed-agents.md`).
 
 ---
 
@@ -341,16 +520,27 @@ Live documentation URLs are in `shared/live-sources.md`.
 ## Common Pitfalls
 
 - Don't truncate inputs when passing files or content to the API. If the content is too long to fit in the context window, notify the user and discuss options (chunking, summarization, etc.) rather than silently truncating.
-- **Fable 5 / Opus 4.8 / 4.7 thinking:** Adaptive only. `thinking: {type: "enabled", budget_tokens: N}` returns 400 — `budget_tokens` is fully removed (along with `temperature`, `top_p`, `top_k`). Use `thinking: {type: "adaptive"}`. Opus 4.8 inherits this surface from 4.7 with no new breaking changes; Fable 5 adds one — an explicit `thinking: {type: "disabled"}` returns a 400 (accepted on 4.7/4.8); omit the param instead.
-- **Opus 4.6 / Sonnet 4.6 thinking:** Use `thinking: {type: "adaptive"}` — do NOT use `budget_tokens` for new 4.6 code (deprecated on both Opus 4.6 and Sonnet 4.6; for gradual migration of existing code, see the transitional escape hatch in `shared/model-migration.md` — note this carve-out does not apply to Fable 5, Opus 4.7 or 4.8). For older models, `budget_tokens` must be less than `max_tokens` (minimum 1024). This will throw an error if you get it wrong.
-- **Prefill removed (Fable 5 and the 4.6/4.7/4.8 family):** Assistant message prefills (last-assistant-turn prefills) return a 400 error on Fable 5, Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6. Use structured outputs (`output_config.format`) or system prompt instructions to control response format instead. (One exception: the fallback-credit prefill claim — when redeeming a credit with `fallback_has_prefill_claim: true`, the server accepts the echoed assistant message; see the migration guide's refusal section.)
-- **Fable 5 `refusal` stop reason:** Safety classifiers may decline a request — a successful HTTP 200 with `stop_reason: "refusal"` (pre-output: empty `content`, nothing billed; mid-stream: partial output billed — discard it). Check `stop_reason` before reading `response.content[0]`, or you'll hit index errors on refused requests. To retry on another model, replaying history as-is works — other models silently ignore the refused model's thinking blocks — but ignored blocks still bill input tokens, so strip them when switching for good (exception: a fallback-credit redemption must echo the refused body exactly, thinking blocks included).
-- **Fable 5 tokenizer:** ~30% more tokens for the same content vs Opus-tier models. Token counts, context-window budgets, and `max_tokens` values measured on other models don't transfer — re-measure with `count_tokens` passing `model: "claude-fable-5"` (the response includes counts under both tokenizers).
+- **Prefill removed (Fable 5, Opus 5, and the 4.6/4.7/4.8 family):** Assistant message prefills (last-assistant-turn prefills) return a 400 error on Fable 5, Opus 5, Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6. Use structured outputs (`output_config.format`) or system prompt instructions to control response format instead. (One exception: the fallback-credit prefill claim — when redeeming a credit with `fallback_has_prefill_claim: true`, the server accepts the echoed assistant message; see the migration guide's refusal section.)
 - **Confirm migration scope before editing:** When a user asks to migrate code to a newer Claude model without naming a specific file, directory, or file list, **ask which scope to apply first** — the entire working directory, a specific subdirectory, or a specific set of files. Do not start editing until the user confirms. Imperative phrasings like "migrate my codebase", "move my project to X", "upgrade to Sonnet 4.6", or bare "migrate to Opus 4.8" are **still ambiguous** — they tell you what to do but not where, so ask. Proceed without asking only when the prompt names an exact file, a specific directory, or an explicit file list ("migrate `app.py`", "migrate everything under `services/`", "update `a.py` and `b.py`"). See `shared/model-migration.md` Step 0.
 - **`max_tokens` defaults:** Don't lowball `max_tokens` — hitting the cap truncates output mid-thought and requires a retry. For non-streaming requests, default to `~16000` (keeps responses under SDK HTTP timeouts). For streaming requests, default to `~64000` (timeouts aren't a concern, so give the model room). Only go lower when you have a hard reason: classification (`~256`), cost caps, deliberately short outputs, or **`max_tokens: 0`** for cache pre-warming (see `shared/prompt-caching.md` → Pre-warming).
-- **128K output tokens:** Fable 5, Opus 4.6, Opus 4.7, and Opus 4.8 support up to 128K `max_tokens`, but the SDKs require streaming for values that large to avoid HTTP timeouts. Use `.stream()` with `.get_final_message()` / `.finalMessage()`.
-- **Tool call JSON parsing (Fable 5 and the 4.6/4.7/4.8 family):** Fable 5, Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6 may produce different JSON string escaping in tool call `input` fields (e.g., Unicode or forward-slash escaping). Always parse tool inputs with `json.loads()` / `JSON.parse()` — never do raw string matching on the serialized input.
+- **Disabling thinking on Claude Opus 5 has two failure modes — prefer low/medium effort instead.** Only affects code that explicitly opts out; thinking is on by default, so watch for a disabled-thinking setting carried forward from Opus 4.8. With `thinking: {type: "disabled"}`, the model occasionally writes a tool call into its **visible text** instead of a `tool_use` block: the turn succeeds, the call never runs, no error is raised, and in an agentic loop that text pollutes later turns. It can also leak `<thinking>` tags into the response. Turning thinking on and lowering `effort` fixes both and still cuts cost. If a route must stay thinking-off: **delete** any don't-think/don't-reason rule (it makes tag leakage worse), don't name thinking tags, and add the combined instruction *"When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response."* Details: `shared/model-migration.md` → Two failure modes when thinking is disabled.
+- **128K output tokens:** Fable 5, Opus 5, Opus 4.6, Opus 4.7, Opus 4.8, Sonnet 5, and Sonnet 4.6 support up to 128K `max_tokens`, but the SDKs require streaming for values that large to avoid HTTP timeouts. Use `.stream()` with `.get_final_message()` / `.finalMessage()`.
+- **Tool call JSON parsing (Fable 5, Opus 5, and the 4.6/4.7/4.8 family):** Fable 5, Opus 5, Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6 may produce different JSON string escaping in tool call `input` fields (e.g., Unicode or forward-slash escaping). Always parse tool inputs with `json.loads()` / `JSON.parse()` — never do raw string matching on the serialized input.
 - **Structured outputs (all models):** Use `output_config: {format: {...}}` instead of the deprecated `output_format` parameter on `messages.create()`. This is a general API change, not 4.6-specific.
 - **Don't reimplement SDK functionality:** The SDK provides high-level helpers — use them instead of building from scratch. Specifically: use `stream.finalMessage()` instead of wrapping `.on()` events in `new Promise()`; use typed exception classes (`Anthropic.RateLimitError`, etc.) instead of string-matching error messages; use SDK types (`Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.Message`, etc.) instead of redefining equivalent interfaces.
+- **Error handling — catch a chain, not one broad class.** A single `except APIStatusError` / `catch (AnthropicServiceException)` / `rescue APIError` loses the distinction between retryable (429, ≥500, network) and non-retryable (400/404) failures. Write a most-specific-first chain — e.g. `NotFoundError` → `RateLimitError` → `APIStatusError` → `APIConnectionError` (or the Go equivalent: `errors.As` into `*anthropic.Error` then `switch apierr.StatusCode { case 404: …; case 429: …; default: … }`). Per-language class names and namespaces are in `shared/error-codes.md`.
+- **Don't research SDK types — write first.** If a type name isn't shown in the documentation included in this skill, write the code file from the namespace/package tables in the language-specific doc and let the compiler's error point you to the right name. Do not spend turns on WebFetch, SDK-repo clones, or compiling-and-running a separate reflection program to discover type names before writing — produce the source file first, then fix what the compiler reports. A quick `strings` / `jar tf` / `javap` against the installed SDK is acceptable for locating names (it returns in seconds), but don't escalate beyond that. A file with a wrong type name is recoverable; a session spent on discovery with no file written is not.
+- **Bash and text editor tools are Anthropic-defined, schema-less.** Declare `{"type": "bash_20250124", "name": "bash"}` / `{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}` — no `input_schema`. A custom tool with your own schema named `"bash"` is a different tool. Handler paths and security checks are in `shared/tool-use-concepts.md` § Client-Side Tools.
+- **Advisor tool model pairing.** The advisor tool's `model` must be at least as capable as the request's top-level `model` — e.g. executor `claude-sonnet-5` → advisor `claude-opus-4-8` or `claude-opus-4-7`. An invalid pair returns 400. Pairing table in `shared/tool-use-concepts.md` § Advisor. Availability: `shared/platform-availability.md`.
+- **Agent Skills ≠ Managed Agents.** To have Claude generate a `.pptx`/`.xlsx`/etc. via Agent Skills, call `client.beta.messages.create` with `container={"skills": [...]}`, the `code_execution_20260521` tool, and both `code-execution-2025-08-25` + `skills-2025-10-02` betas. Do not use `client.beta.agents` / `sessions` / `environments` here — those are the Managed Agents surface, not Agent Skills.
+- **MCP connector needs both halves.** `mcp_servers=[{type:"url", url, name}]` alone is rejected as a validation error — also add `tools=[{type:"mcp_toolset", mcp_server_name:<same name>}]` with beta `mcp-client-2025-11-20`. Availability: `shared/platform-availability.md`.
+- **`inference_geo` is a direct top-level request parameter** — `client.messages.create(..., inference_geo="us")` / `.inferenceGeo("us")`. Do not put it in `extra_body` / `putAdditionalBodyProperty`. Supported on Opus 4.6 / Sonnet 4.6 and later; availability: `shared/platform-availability.md`. `response.usage.inference_geo` reports where inference ran.
+- **Fine-grained tool streaming is not a beta feature.** Set `eager_input_streaming: true` on the tool definition and call the regular `client.messages.stream(...)`. There is no beta header and no `client.beta.*` path.
+- **Cache diagnostics is beta.** Use `client.beta.messages.*` with beta `cache-diagnosis-2026-04-07`. Pass `diagnostics: {previous_message_id: null}` on the first turn and `diagnostics: {previous_message_id: <previous response id>}` on subsequent turns; the result is on `response.diagnostics`. Availability: `shared/platform-availability.md`.
+- **Memory tool type is `memory_20250818`.** Declare `{"type": "memory_20250818", "name": "memory"}`. Go uses the beta-namespace type `{OfMemoryTool20250818: &anthropic.BetaMemoryTool20250818Param{}}` on `client.Beta.Messages.New`; Python/TypeScript/Ruby/PHP/C# use the non-beta `client.messages.create`; Java has both a non-beta `MemoryTool20250818` and a beta tool-runner path. Python/TypeScript provide `BetaAbstractMemoryTool` / `betaMemoryTool` helpers for implementing the backend.
+- **Use a model the feature actually supports.** Some features are restricted to specific model tiers — fast mode is Claude Opus 5 / Opus 4.8 only (and Claude API only), task budgets are Claude Opus 5 / Fable 5 / Sonnet 5 / Opus 4.8 / 4.7 only, and the advisor tool requires a valid executor↔advisor pair. If the user's prompt names a model that the feature doesn't support, use a supported model instead and note the substitution in the output.
 - **Don't define custom types for SDK data structures:** The SDK exports types for all API objects. Use `Anthropic.MessageParam` for messages, `Anthropic.Tool` for tool definitions, `Anthropic.ToolUseBlock` / `Anthropic.ToolResultBlockParam` for tool results, `Anthropic.Message` for responses. Defining your own `interface ChatMessage { role: string; content: unknown }` duplicates what the SDK already provides and loses type safety.
 - **Report and document output:** For tasks that produce reports, documents, or visualizations, the code execution sandbox has `python-docx`, `python-pptx`, `matplotlib`, `pillow`, and `pypdf` pre-installed. Claude can generate formatted files (DOCX, PDF, charts) and return them via the Files API — consider this for "report" or "document" type requests instead of plain stdout text.
+- **Server-tool errors don't raise.** Web search and web fetch errors return HTTP 200 with a `web_search_tool_result` / `web_fetch_tool_result` block whose `content` is a single error object (e.g. `{error_code: "max_uses_exceeded"}`) — not a raised exception. For web search, a success `content` is a *list*; an error `content` is an *object* — branch on that before indexing.
+- **Code execution output block type:** `code_execution_20260521` returns `bash_code_execution_tool_result` (with `.content.stdout`), **not** the legacy bare `code_execution_tool_result`. Iterate `response.content` and match on the correct type.
+- **Tool search: never defer everything.** The search tool itself must not have `defer_loading: true`, and at least one tool in `tools` must be non-deferred, or the API returns 400 `All tools have defer_loading set`.

skills/claude-api/csharp/claude-api.md

@@ -1,447 +0,0 @@
-# Claude API — C#
-
-> **Note:** The C# SDK is the official Anthropic SDK for C#. Tool use is supported via the Messages API with a beta `BetaToolRunner` for automatic tool execution loops. The SDK also supports Microsoft.Extensions.AI IChatClient integration with function invocation and Managed Agents (beta).
-
-## Installation
-
-```bash
-dotnet add package Anthropic
-```
-
-## Client Initialization
-
-```csharp
-using Anthropic;
-
-// Default (uses ANTHROPIC_API_KEY env var)
-AnthropicClient client = new();
-
-// Explicit API key (use environment variables — never hardcode keys)
-AnthropicClient client = new() {
-    ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
-};
-```
-
----
-
-## Basic Message Request
-
-```csharp
-using Anthropic.Models.Messages;
-
-var parameters = new MessageCreateParams
-{
-    Model = Model.ClaudeOpus4_6,
-    MaxTokens = 16000,
-    Messages = [new() { Role = Role.User, Content = "What is the capital of France?" }]
-};
-var response = await client.Messages.Create(parameters);
-
-// ContentBlock is a union wrapper. .Value unwraps to the variant object,
-// then OfType<T> filters to the type you want. Or use the TryPick* idiom
-// shown in the Thinking section below.
-foreach (var text in response.Content.Select(b => b.Value).OfType<TextBlock>())
-{
-    Console.WriteLine(text.Text);
-}
-```
-
----
-
-## Streaming
-
-```csharp
-using Anthropic.Models.Messages;
-
-var parameters = new MessageCreateParams
-{
-    Model = Model.ClaudeOpus4_6,
-    MaxTokens = 64000,
-    Messages = [new() { Role = Role.User, Content = "Write a haiku" }]
-};
-
-await foreach (RawMessageStreamEvent streamEvent in client.Messages.CreateStreaming(parameters))
-{
-    if (streamEvent.TryPickContentBlockDelta(out var delta) &&
-        delta.Delta.TryPickText(out var text))
-    {
-        Console.Write(text.Text);
-    }
-}
-```
-
-**`RawMessageStreamEvent` TryPick methods** (naming drops the `Message`/`Raw` prefix): `TryPickStart`, `TryPickDelta`, `TryPickStop`, `TryPickContentBlockStart`, `TryPickContentBlockDelta`, `TryPickContentBlockStop`. There is no `TryPickMessageStop` — use `TryPickStop`.
-
----
-
-## Thinking
-
-**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think.
-
-```csharp
-using Anthropic.Models.Messages;
-
-var response = await client.Messages.Create(new MessageCreateParams
-{
-    Model = Model.ClaudeOpus4_6,
-    MaxTokens = 16000,
-    // ThinkingConfigParam? implicitly converts from the concrete variant classes —
-    // no wrapper needed.
-    Thinking = new ThinkingConfigAdaptive(),
-    Messages =
-    [
-        new() { Role = Role.User, Content = "Solve: 27 * 453" },
-    ],
-});
-
-// ThinkingBlock(s) precede TextBlock in Content. TryPick* narrows the union.
-foreach (var block in response.Content)
-{
-    if (block.TryPickThinking(out ThinkingBlock? t))
-    {
-        Console.WriteLine($"[thinking] {t.Thinking}");
-    }
-    else if (block.TryPickText(out TextBlock? text))
-    {
-        Console.WriteLine(text.Text);
-    }
-}
-```
-
-> **Deprecated:** `new ThinkingConfigEnabled { BudgetTokens = N }` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
-
-Alternative to `TryPick*`: `.Select(b => b.Value).OfType<ThinkingBlock>()` (same LINQ pattern as the Basic Message example).
-
----
-
-## Tool Use
-
-### Defining a tool
-
-`Tool` (NOT `ToolParam`) with an `InputSchema` record. `InputSchema.Type` is auto-set to `"object"` by the constructor — don't set it. `ToolUnion` has an implicit conversion from `Tool`, triggered by the collection expression `[...]`.
-
-```csharp
-using System.Text.Json;
-using Anthropic.Models.Messages;
-
-var parameters = new MessageCreateParams
-{
-    Model = Model.ClaudeSonnet4_6,
-    MaxTokens = 16000,
-    Tools = [
-        new Tool {
-            Name = "get_weather",
-            Description = "Get the current weather in a given location",
-            InputSchema = new() {
-                Properties = new Dictionary<string, JsonElement> {
-                    ["location"] = JsonSerializer.SerializeToElement(
-                        new { type = "string", description = "City name" }),
-                },
-                Required = ["location"],
-            },
-        },
-    ],
-    Messages = [new() { Role = Role.User, Content = "Weather in Paris?" }],
-};
-```
-
-Derived from `anthropic-sdk-csharp/src/Anthropic/Models/Messages/Tool.cs` and `ToolUnion.cs:799` (implicit conversion).
-
-See [shared tool use concepts](../shared/tool-use-concepts.md) for the loop pattern.
-### Converting response content to the follow-up assistant message
-
-When echoing Claude's response back in the assistant turn, **there is no `.ToParam()` helper** — manually reconstruct each `ContentBlock` variant as its `*Param` counterpart. Do NOT use `new ContentBlockParam(block.Json)`: it compiles and serializes, but `.Value` stays `null` so `TryPick*`/`Validate()` fail (degraded JSON pass-through, not the typed path).
-
-```csharp
-using Anthropic.Models.Messages;
-
-Message response = await client.Messages.Create(parameters);
-
-// No .ToParam() — reconstruct per variant. Implicit conversions from each
-// *Param type to ContentBlockParam mean no explicit wrapper.
-List<ContentBlockParam> assistantContent = [];
-List<ContentBlockParam> toolResults = [];
-foreach (ContentBlock block in response.Content)
-{
-    if (block.TryPickText(out TextBlock? text))
-    {
-        assistantContent.Add(new TextBlockParam { Text = text.Text });
-    }
-    else if (block.TryPickThinking(out ThinkingBlock? thinking))
-    {
-        // Signature MUST be preserved — the API rejects tampering
-        assistantContent.Add(new ThinkingBlockParam
-        {
-            Thinking = thinking.Thinking,
-            Signature = thinking.Signature,
-        });
-    }
-    else if (block.TryPickRedactedThinking(out RedactedThinkingBlock? redacted))
-    {
-        assistantContent.Add(new RedactedThinkingBlockParam { Data = redacted.Data });
-    }
-    else if (block.TryPickToolUse(out ToolUseBlock? toolUse))
-    {
-        // ToolUseBlock has required Caller; ToolUseBlockParam.Caller is optional — don't copy it
-        assistantContent.Add(new ToolUseBlockParam
-        {
-            ID = toolUse.ID,
-            Name = toolUse.Name,
-            Input = toolUse.Input,
-        });
-        // Execute the tool; collect ONE result per tool_use block — the API
-        // rejects the follow-up if any tool_use ID lacks a matching tool_result.
-        string result = ExecuteYourTool(toolUse.Name, toolUse.Input);
-        toolResults.Add(new ToolResultBlockParam
-        {
-            ToolUseID = toolUse.ID,
-            Content = result,
-        });
-    }
-}
-
-// Follow-up: prior messages + assistant echo + user tool_result(s)
-List<MessageParam> followUpMessages =
-[
-    .. parameters.Messages,
-    new() { Role = Role.Assistant, Content = assistantContent },
-    new() { Role = Role.User, Content = toolResults },
-];
-```
-
-`ToolResultBlockParam` has no tuple constructor — use the object initializer. `Content` is a string-or-list union; a plain `string` implicitly converts.
-
----
-
-## Context Editing / Compaction (Beta)
-
-**Beta-namespace prefix is inconsistent** (source-verified against `src/Anthropic/Models/Beta/Messages/*.cs` @ 12.9.0). No prefix: `MessageCreateParams`, `MessageCountTokensParams`, `Role`. **Everything else has the `Beta` prefix**: `BetaMessageParam`, `BetaMessage`, `BetaContentBlock`, `BetaToolUseBlock`, all block param types. The unprefixed `Role` WILL collide with `Anthropic.Models.Messages.Role` if you import both namespaces (CS0104). Safest: import only Beta; if mixing, alias the beta `Role`:
-
-```csharp
-using Anthropic.Models.Beta.Messages;
-using NonBeta = Anthropic.Models.Messages;  // only if you also need non-beta types
-// Now: MessageCreateParams, BetaMessageParam, Role (beta's), NonBeta.Role (if needed)
-```
-
-
-`BetaMessage.Content` is `IReadOnlyList<BetaContentBlock>` — a 15-variant discriminated union. Narrow with `TryPick*`. **Response `BetaContentBlock` is NOT assignable to param `BetaContentBlockParam`** — there's no `.ToParam()` in C#. Round-trip by converting each block:
-
-```csharp
-using Anthropic.Models.Beta.Messages;
-
-var betaParams = new MessageCreateParams   // no Beta prefix — one of only 2 unprefixed
-{
-    Model = Model.ClaudeOpus4_6,
-    MaxTokens = 16000,
-    Betas = ["compact-2026-01-12"],
-    ContextManagement = new BetaContextManagementConfig
-    {
-        Edits = [new BetaCompact20260112Edit()],
-    },
-    Messages = messages,
-};
-BetaMessage resp = await client.Beta.Messages.Create(betaParams);
-
-foreach (BetaContentBlock block in resp.Content)
-{
-    if (block.TryPickCompaction(out BetaCompactionBlock? compaction))
-    {
-        // Content is nullable — compaction can fail server-side
-        Console.WriteLine($"compaction summary: {compaction.Content}");
-    }
-}
-
-// Context-edit metadata lives on a separate nullable field
-if (resp.ContextManagement is { } ctx)
-{
-    foreach (var edit in ctx.AppliedEdits)
-        Console.WriteLine($"cleared {edit.ClearedInputTokens} tokens");
-}
-
-// ROUND-TRIP: BetaMessageParam.Content is BetaMessageParamContent (a string|list
-// union). It implicit-converts from List<BetaContentBlockParam>, NOT from the
-// response's IReadOnlyList<BetaContentBlock>. Convert each block:
-List<BetaContentBlockParam> paramBlocks = [];
-foreach (var b in resp.Content)
-{
-    if (b.TryPickText(out var t)) paramBlocks.Add(new BetaTextBlockParam { Text = t.Text });
-    else if (b.TryPickCompaction(out var c)) paramBlocks.Add(new BetaCompactionBlockParam { Content = c.Content });
-    // ... other variants as needed
-}
-messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = paramBlocks });
-```
-
-All 15 `BetaContentBlock.TryPick*` variants: `Text`, `Thinking`, `RedactedThinking`, `ToolUse`, `ServerToolUse`, `WebSearchToolResult`, `WebFetchToolResult`, `CodeExecutionToolResult`, `BashCodeExecutionToolResult`, `TextEditorCodeExecutionToolResult`, `ToolSearchToolResult`, `McpToolUse`, `McpToolResult`, `ContainerUpload`, `Compaction`.
-
-**`BetaToolUseBlock.Input` is `IReadOnlyDictionary<string, JsonElement>`** — index by key then call the `JsonElement` extractor:
-
-```csharp
-if (block.TryPickToolUse(out BetaToolUseBlock? tu))
-{
-    int a = tu.Input["a"].GetInt32();
-    string s = tu.Input["name"].GetString()!;
-}
-```
-
----
-
-## Effort Parameter
-
-Effort is nested under `OutputConfig`, NOT a top-level property. `ApiEnum<string, Effort>` has an implicit conversion from the enum, so assign `Effort.High` directly.
-
-```csharp
-OutputConfig = new OutputConfig { Effort = Effort.High },
-```
-
-Values: `Effort.Low`, `Effort.Medium`, `Effort.High`, `Effort.Max`. Combine with `Thinking = new ThinkingConfigAdaptive()` for cost-quality control.
-
----
-
-## Prompt Caching
-
-`System` takes `MessageCreateParamsSystem?` — a union of `string` or `List<TextBlockParam>`. There is no `SystemTextBlockParam`; use plain `TextBlockParam`. The implicit conversion needs the concrete `List<TextBlockParam>` type (array literals won't convert). For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
-
-```csharp
-System = new List<TextBlockParam> {
-    new() {
-        Text = longSystemPrompt,
-        CacheControl = new CacheControlEphemeral(),  // auto-sets Type = "ephemeral"
-    },
-},
-```
-
-Optional `Ttl` on `CacheControlEphemeral`: `new() { Ttl = Ttl.Ttl1h }` or `Ttl.Ttl5m`. `CacheControl` also exists on `Tool.CacheControl` and top-level `MessageCreateParams.CacheControl`.
-
-Verify hits via `response.Usage.CacheCreationInputTokens` / `response.Usage.CacheReadInputTokens`.
-
----
-
-## Token Counting
-
-```csharp
-MessageTokensCount result = await client.Messages.CountTokens(new MessageCountTokensParams {
-    Model = Model.ClaudeOpus4_6,
-    Messages = [new() { Role = Role.User, Content = "Hello" }],
-});
-long tokens = result.InputTokens;
-```
-
-`MessageCountTokensParams.Tools` uses a different union type (`MessageCountTokensTool`) than `MessageCreateParams.Tools` (`ToolUnion`) — if you're passing tools, the compiler will tell you when it matters.
-
----
-
-## Structured Output
-
-```csharp
-OutputConfig = new OutputConfig {
-    Format = new JsonOutputFormat {
-        Schema = new Dictionary<string, JsonElement> {
-            ["type"] = JsonSerializer.SerializeToElement("object"),
-            ["properties"] = JsonSerializer.SerializeToElement(
-                new { name = new { type = "string" } }),
-            ["required"] = JsonSerializer.SerializeToElement(new[] { "name" }),
-        },
-    },
-},
-```
-
-`JsonOutputFormat.Type` is auto-set to `"json_schema"` by the constructor. `Schema` is `required`.
-
----
-
-## PDF / Document Input
-
-`DocumentBlockParam` takes a `DocumentBlockParamSource` union: `Base64PdfSource` / `UrlPdfSource` / `PlainTextSource` / `ContentBlockSource`. `Base64PdfSource` auto-sets `MediaType = "application/pdf"` and `Type = "base64"`.
-
-```csharp
-new MessageParam {
-    Role = Role.User,
-    Content = new List<ContentBlockParam> {
-        new DocumentBlockParam { Source = new Base64PdfSource { Data = base64String } },
-        new TextBlockParam { Text = "Summarize this PDF" },
-    },
-}
-```
-
----
-
-## Server-Side Tools
-
-Web search, bash, text editor, and code execution are built-in server tools. Type names are version-suffixed; constructors auto-set `name`/`type`. All implicit-convert to `ToolUnion`.
-
-```csharp
-Tools = [
-    new WebSearchTool20260209(),
-    new ToolBash20250124(),
-    new ToolTextEditor20250728(),
-    new CodeExecutionTool20260120(),
-],
-```
-
-Also available: `WebFetchTool20260209`, `MemoryTool20250818`. `WebSearchTool20260209` optionals: `AllowedDomains`, `BlockedDomains`, `MaxUses`, `UserLocation`.
-
----
-
-## Files API (Beta)
-
-Files live under `client.Beta.Files` (namespace `Anthropic.Models.Beta.Files`). `BinaryContent` implicit-converts from `Stream` and `byte[]`.
-
-```csharp
-using Anthropic.Models.Beta.Files;
-using Anthropic.Models.Beta.Messages;
-
-FileMetadata meta = await client.Beta.Files.Upload(
-    new FileUploadParams { File = File.OpenRead("doc.pdf") });
-
-// Referencing the uploaded file requires Beta message types:
-new BetaRequestDocumentBlock {
-    Source = new BetaFileDocumentSource { FileID = meta.ID },
-}
-```
-
-The non-beta `DocumentBlockParamSource` union has no file-ID variant — file references need `client.Beta.Messages.Create()`.
-
----
-
-## Tool Runner (Beta)
-
-The C# SDK provides a `BetaToolRunner` for automatic tool execution loops. Define tools with raw JSON schemas, and the runner handles the API call → tool execution → result feedback loop.
-
-```csharp
-using Anthropic.Models.Beta.Messages;
-
-// Define tools and create params as shown in the Tool Use section above,
-// but using the beta namespace types (BetaToolUnion, etc.)
-var runner = client.Beta.Messages.ToolRunner(betaParams);
-
-await foreach (BetaMessage message in runner)
-{
-    foreach (var block in message.Content)
-    {
-        if (block.TryPickText(out var text))
-        {
-            Console.WriteLine(text.Text);
-        }
-    }
-}
-```
-
----
-
-## Stop Details
-
-When `StopReason` is `"refusal"`, the response includes structured `StopDetails`:
-
-```csharp
-if (response.StopReason == "refusal" && response.StopDetails is { } details)
-{
-    Console.WriteLine($"Category: {details.Category}");
-    Console.WriteLine($"Explanation: {details.Explanation}");
-}
-```
-
----
-
-## Managed Agents (Beta)
-
-The C# SDK supports Managed Agents via `client.Beta.Agents`, `client.Beta.Sessions`, `client.Beta.Environments`, and related namespaces. See `shared/managed-agents-overview.md` for the architecture and `curl/managed-agents.md` for the wire-level reference.

skills/claude-api/csharp/claude-api/README.md

@@ -0,0 +1,362 @@
+# Claude API — C#
+
+> **Note:** The C# SDK is the official Anthropic SDK for C#. Tool use is supported via the Messages API with a beta `BetaToolRunner` for automatic tool execution loops. The SDK also supports Microsoft.Extensions.AI IChatClient integration with function invocation and Managed Agents (beta).
+
+## Namespace Reference
+
+Types are organized by namespace. If a type you need isn't shown in an example below, locate it via this table first — don't block on fetching SDK source over the network.
+
+| `using` | Contains |
+|---|---|
+| `Anthropic` | `AnthropicClient`, top-level options |
+| `Anthropic.Models.Messages` | non-beta request/response types — `MessageCreateParams`, `Model`, `Role`, `ContentBlock`, `TextBlock`, `ToolUseBlock`, `ToolResultBlockParam`, `Tool*` (tool definition classes) |
+| `Anthropic.Models.Beta.Messages` | beta-endpoint equivalents — `MessageCreateParams`, `BetaMessage`, `BetaTool*`, `Speed`, `BetaRequestMcpServerUrlDefinition`, context-editing/compaction configs |
+| `Anthropic.Models.Beta` | shared beta constants |
+| `Anthropic.Models.Beta.Files` | Files API types |
+| `Anthropic.Models.Messages.Batches` | Batch API types |
+| `Anthropic.Helpers.Beta` | `BetaToolRunner`, beta helper utilities |
+| `Anthropic.Exceptions` | `AnthropicApiException`, `AnthropicRateLimitException`, `Anthropic5xxException`, etc. — see `shared/error-codes.md` |
+| `Anthropic.Bedrock` / `Anthropic.Vertex` / `Anthropic.Foundry` / `Anthropic.Aws` | platform clients (separate NuGet packages): `AnthropicBedrockMantleClient`, `AnthropicFoundryClient`, `AnthropicAwsClient` |
+
+`client.Messages.*` uses non-beta types; `client.Beta.Messages.*` uses the `Anthropic.Models.Beta.Messages` types. Both namespaces define a `MessageCreateParams` — pick the one matching the client path you call.
+
+### Key types per feature
+
+Write from this table instead of reflecting the SDK assembly. Endpoint column tells you whether to use `client.Messages.*` or `client.Beta.Messages.*`.
+
+| Feature | Endpoint | Key C# types (namespace per table above) |
+|---|---|---|
+| User profiles | beta | `client.Beta.UserProfiles.Create(...)` / `.Retrieve(id)` / `.List()`. Pass the returned profile id on the beta messages call. Requires a beta header — check the SDK's beta-headers reference for the current flag. |
+| Agent Skills | beta | `BetaContainerParams` (with `Skills = [new BetaSkillParams { ... }]`), `BetaCodeExecutionTool20250825`. `Betas = ["code-execution-2025-08-25", "skills-2025-10-02"]`. Download the output via `client.Beta.Files.Download(fileId)`. |
+| Advisor tool | beta | `BetaAdvisorTool20260301` — may not be in all SDK releases yet |
+| Cache diagnostics | beta | `Diagnostics = new() { PreviousMessageID = … }`, `BetaCacheControlEphemeral`, `BetaContentBlockParam` |
+| Context editing | beta | `ContextManagement = new BetaContextManagementConfig { Edits = [new BetaClearToolUses20250919Edit()] }`. `Betas = ["context-management-2025-06-27"]` (not `compact-2026-01-12` — that's for `BetaCompact20260112Edit`). |
+| Memory tool | non-beta | `Tools = [new ToolUnion(new MemoryTool20250818())]` |
+| Programmatic tool calling | non-beta | `CodeExecutionTool20260120`, `ToolResultBlockParam`, `ContentBlockParam` |
+| Task budgets | beta | `BetaOutputConfig` with `TaskBudget = new BetaTokenTaskBudget { ... }` |
+| Tool search | non-beta | `new ToolUnion(new ToolSearchToolRegex20251119 { Type = ToolSearchToolRegex20251119Type.ToolSearchToolRegex20251119 })` — `Type` must be set explicitly. |
+| Web search | non-beta | `new ToolUnion(new WebSearchTool20260209())` — the latest variant with dynamic filtering (Claude Fable 5 + Claude Opus 5 + Opus 4.8/4.7/4.6 + Claude Sonnet 5 + Sonnet 4.6). For older models or Vertex, use `WebSearchTool20250305()` |
+
+### Discovering type and member names
+
+If a type or member you need isn't in the tables above, `strings ~/.nuget/packages/anthropic/*/lib/*/Anthropic.dll | grep -i <term>` is fast and sufficient for locating class and property names. **Do not escalate to a `dotnet run` reflection probe** to dump members precisely — the first compile is slow enough to be backgrounded in many environments, trapping you in a polling loop. Instead, write `Program.cs` using the names `strings | grep` found; if a member name is wrong the compiler error (`error CS1061: 'X' does not contain a definition for 'Y'`) points at it in a few seconds, faster than any reflection probe.
+
+Note that `strings` will not surface wire-format snake_case field names (`output_tokens`, `stop_reason`) — those are stored in the DLL differently. **C# properties are the PascalCase equivalent of the wire field** (`response.Usage.OutputTokens`, `response.StopReason`). If you know the wire field name from the docs, write the PascalCase property and compile; do not probe for the snake_case string.
+
+### Minimal working skeleton
+
+**Write a plain `Program.cs` body** — `using` statements followed by top-level statements, as below. Do **not** add a `#!/usr/bin/env dotnet` shebang or `#:package Anthropic@*` directive: those are .NET file-based-app syntax and fail with `CS1024: Preprocessor directive expected` when the file is compiled via an existing `.csproj`. The standard project setup (per the [C# quickstart](https://platform.claude.com/docs/en/get-started): `dotnet new console` → `dotnet add package Anthropic` → edit `Program.cs` → `dotnet run`) provides the `.csproj` and package reference.
+
+Start from this — it compiles as-is. Fill in the feature-specific fields; do not spend turns running reflection or XML-doc inspection to discover type names first.
+
+```csharp
+using System;
+using Anthropic;
+using Anthropic.Models.Messages;       // or Anthropic.Models.Beta.Messages for beta endpoints
+
+AnthropicClient client = new();
+
+var message = await client.Messages.Create(new MessageCreateParams
+{
+    Model = "claude-opus-5",
+    MaxTokens = 1024,
+    Messages = [ new() { Role = Role.User, Content = "Hello, Claude" } ],
+});
+
+Console.WriteLine(message);
+```
+
+For beta features (anything behind an `anthropic-beta` header), use the beta client path and namespace — same overall shape:
+
+```csharp
+using System;
+using Anthropic;
+using Anthropic.Models.Beta.Messages;
+
+AnthropicClient client = new();
+
+var response = await client.Beta.Messages.Create(new MessageCreateParams
+{
+    Model = "claude-opus-5",
+    MaxTokens = 4096,
+    Betas = ["<beta-flag>"],
+    Messages = [ new() { Role = Role.User, Content = "…" } ],
+    // Tools = new BetaToolUnion[] { new BetaSomeTool { … } },   // for tool features
+});
+
+Console.WriteLine(response);
+```
+
+If a type name the feature needs isn't in this file, write it following the naming pattern in the Namespace Reference above and fix from compiler output — producing a `Program.cs` and iterating beats researching.
+
+### Common C# compile errors
+
+- **CS8803 (top-level statements must precede type declarations):** put any `record`/`class`/`struct` definitions **after** the last top-level statement, at the end of the file. A record defined above `var client = new AnthropicClient()` will not compile.
+- **`await foreach` on a `Task<…Page>`:** `client.Models.List()` returns a `Task<ModelListPage>`, which is not directly async-enumerable. Await it first, then iterate: `var page = await client.Models.List(); foreach (var m in page.Items) {…}`. For auto-pagination, check whether the page type exposes `AutoPagingEachAsync()` or similar before reaching for `await foreach`.
+
+## Installation
+
+```bash
+dotnet add package Anthropic
+```
+
+## Client Initialization
+
+```csharp
+using Anthropic;
+
+// Default (uses ANTHROPIC_API_KEY env var)
+AnthropicClient client = new();
+
+// Explicit API key (use environment variables — never hardcode keys)
+AnthropicClient client = new() {
+    ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
+};
+```
+
+---
+
+## Basic Message Request
+
+```csharp
+using Anthropic.Models.Messages;
+
+var parameters = new MessageCreateParams
+{
+    Model = "claude-opus-5",
+    MaxTokens = 16000,
+    Messages = [new() { Role = Role.User, Content = "What is the capital of France?" }]
+};
+var response = await client.Messages.Create(parameters);
+
+// ContentBlock is a union wrapper. .Value unwraps to the variant object,
+// then OfType<T> filters to the type you want. Or use the TryPick* idiom
+// shown in the Thinking section below.
+foreach (var text in response.Content.Select(b => b.Value).OfType<TextBlock>())
+{
+    Console.WriteLine(text.Text);
+}
+```
+
+---
+
+## Thinking
+
+**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think.
+
+> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (below). `new ThinkingConfigEnabled { BudgetTokens = N }` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Claude Opus 5:** thinking is on by default — omitting `Thinking` runs adaptive (`ThinkingConfigAdaptive` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `ThinkingConfigDisabled` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400.
+> **Older models:** Use `new ThinkingConfigEnabled { BudgetTokens = N }` (budget must be < `MaxTokens`, min 1024).
+
+```csharp
+using Anthropic.Models.Messages;
+
+var response = await client.Messages.Create(new MessageCreateParams
+{
+    Model = "claude-opus-5",
+    MaxTokens = 16000,
+    // ThinkingConfigParam? implicitly converts from the concrete variant classes —
+    // no wrapper needed.
+    // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7
+    Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized },
+    Messages =
+    [
+        new() { Role = Role.User, Content = "Solve: 27 * 453" },
+    ],
+});
+
+// ThinkingBlock(s) precede TextBlock in Content. TryPick* narrows the union.
+foreach (var block in response.Content)
+{
+    if (block.TryPickThinking(out ThinkingBlock? t))
+    {
+        Console.WriteLine($"[thinking] {t.Thinking}");
+    }
+    else if (block.TryPickText(out TextBlock? text))
+    {
+        Console.WriteLine(text.Text);
+    }
+}
+```
+
+Alternative to `TryPick*`: `.Select(b => b.Value).OfType<ThinkingBlock>()` (same LINQ pattern as the Basic Message example).
+
+---
+
+## Context Editing / Compaction (Beta)
+
+**Beta-namespace prefix is inconsistent** (source-verified against `src/Anthropic/Models/Beta/Messages/*.cs` @ 12.9.0). No prefix: `MessageCreateParams`, `MessageCountTokensParams`, `Role`, `Speed`. **Everything else has the `Beta` prefix**: `BetaMessageParam`, `BetaMessage`, `BetaContentBlock`, `BetaToolUseBlock`, all block param types. The unprefixed `Role` WILL collide with `Anthropic.Models.Messages.Role` if you import both namespaces (CS0104). Safest: import only Beta; if mixing, alias the beta `Role`:
+
+```csharp
+using Anthropic.Models.Beta.Messages;
+using NonBeta = Anthropic.Models.Messages;  // only if you also need non-beta types
+// Now: MessageCreateParams, BetaMessageParam, Role (beta's), NonBeta.Role (if needed)
+```
+
+
+`BetaMessage.Content` is `IReadOnlyList<BetaContentBlock>` — a 15-variant discriminated union. Narrow with `TryPick*`. **Response `BetaContentBlock` is NOT assignable to param `BetaContentBlockParam`** — there's no `.ToParam()` in C#. Round-trip by converting each block:
+
+```csharp
+using Anthropic.Models.Beta.Messages;
+
+var betaParams = new MessageCreateParams   // no Beta prefix — see unprefixed list above
+{
+    Model = "claude-opus-5",
+    MaxTokens = 16000,
+    Betas = ["compact-2026-01-12"],
+    ContextManagement = new BetaContextManagementConfig
+    {
+        Edits = [new BetaCompact20260112Edit()],
+    },
+    Messages = messages,
+};
+BetaMessage resp = await client.Beta.Messages.Create(betaParams);
+
+foreach (BetaContentBlock block in resp.Content)
+{
+    if (block.TryPickCompaction(out BetaCompactionBlock? compaction))
+    {
+        // Content is nullable — compaction can fail server-side
+        Console.WriteLine($"compaction summary: {compaction.Content}");
+    }
+}
+
+// Context-edit metadata lives on a separate nullable field
+if (resp.ContextManagement is { } ctx)
+{
+    foreach (var edit in ctx.AppliedEdits)
+        Console.WriteLine($"cleared {edit.ClearedInputTokens} tokens");
+}
+
+// ROUND-TRIP: BetaMessageParam.Content is BetaMessageParamContent (a string|list
+// union). It implicit-converts from List<BetaContentBlockParam>, NOT from the
+// response's IReadOnlyList<BetaContentBlock>. Convert each block:
+List<BetaContentBlockParam> paramBlocks = [];
+foreach (var b in resp.Content)
+{
+    if (b.TryPickText(out var t)) paramBlocks.Add(new BetaTextBlockParam { Text = t.Text });
+    else if (b.TryPickCompaction(out var c)) paramBlocks.Add(new BetaCompactionBlockParam { Content = c.Content });
+    // ... other variants as needed
+}
+messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = paramBlocks });
+```
+
+All 15 `BetaContentBlock.TryPick*` variants: `Text`, `Thinking`, `RedactedThinking`, `ToolUse`, `ServerToolUse`, `WebSearchToolResult`, `WebFetchToolResult`, `CodeExecutionToolResult`, `BashCodeExecutionToolResult`, `TextEditorCodeExecutionToolResult`, `ToolSearchToolResult`, `McpToolUse`, `McpToolResult`, `ContainerUpload`, `Compaction`.
+
+**`BetaToolUseBlock.Input` is `IReadOnlyDictionary<string, JsonElement>`** — index by key then call the `JsonElement` extractor:
+
+```csharp
+if (block.TryPickToolUse(out BetaToolUseBlock? tu))
+{
+    int a = tu.Input["a"].GetInt32();
+    string s = tu.Input["name"].GetString()!;
+}
+```
+
+---
+
+## Effort Parameter
+
+Effort is nested under `OutputConfig`, NOT a top-level property. `ApiEnum<string, Effort>` has an implicit conversion from the enum, so assign `Effort.High` directly.
+
+```csharp
+OutputConfig = new OutputConfig { Effort = Effort.High },
+```
+
+Values: `Effort.Low`, `Effort.Medium`, `Effort.High`, `Effort.Max`. Combine with `Thinking = new ThinkingConfigAdaptive()` for cost-quality control.
+
+---
+
+## Prompt Caching
+
+`System` takes `MessageCreateParamsSystem?` — a union of `string` or `List<TextBlockParam>`. There is no `SystemTextBlockParam`; use plain `TextBlockParam`. The implicit conversion needs the concrete `List<TextBlockParam>` type (array literals won't convert). For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
+
+```csharp
+System = new List<TextBlockParam> {
+    new() {
+        Text = longSystemPrompt,
+        CacheControl = new CacheControlEphemeral(),  // auto-sets Type = "ephemeral"
+    },
+},
+```
+
+Optional `Ttl` on `CacheControlEphemeral`: `new() { Ttl = Ttl.Ttl1h }` or `Ttl.Ttl5m`. `CacheControl` also exists on `Tool.CacheControl` and top-level `MessageCreateParams.CacheControl`.
+
+Verify hits via `response.Usage.CacheCreationInputTokens` / `response.Usage.CacheReadInputTokens`.
+
+---
+
+## Token Counting
+
+```csharp
+MessageTokensCount result = await client.Messages.CountTokens(new MessageCountTokensParams {
+    Model = "claude-opus-5",
+    Messages = [new() { Role = Role.User, Content = "Hello" }],
+});
+long tokens = result.InputTokens;
+```
+
+`MessageCountTokensParams.Tools` uses a different union type (`MessageCountTokensTool`) than `MessageCreateParams.Tools` (`ToolUnion`) — if you're passing tools, the compiler will tell you when it matters.
+
+---
+
+## PDF / Document Input
+
+`DocumentBlockParam` takes a `DocumentBlockParamSource` union: `Base64PdfSource` / `UrlPdfSource` / `PlainTextSource` / `ContentBlockSource`. `Base64PdfSource` auto-sets `MediaType = "application/pdf"` and `Type = "base64"`.
+
+```csharp
+new MessageParam {
+    Role = Role.User,
+    Content = new List<ContentBlockParam> {
+        new DocumentBlockParam { Source = new Base64PdfSource { Data = base64String } },
+        new TextBlockParam { Text = "Summarize this PDF" },
+    },
+}
+```
+
+---
+
+## Fast Mode (Beta)
+
+```csharp
+var response = await client.Beta.Messages.Create(new MessageCreateParams {
+    Model = "claude-opus-5", MaxTokens = 4096,
+    Speed = Speed.Fast,
+    Betas = ["fast-mode-2026-02-01"],
+    Messages = [...],
+});
+```
+
+## Models API
+
+```csharp
+var page = await client.Models.List();
+foreach (var m in page.Items) { Console.WriteLine(m.ID); }
+var one = await client.Models.Retrieve("claude-opus-5");
+```
+
+## Long Output (128k) + Prefill
+
+Set `MaxTokens = 128000` on `client.Messages` and use the streaming path (see `streaming.md`). On Claude 4+ models, 128k output is native — no `output-128k-*` beta header or beta namespace is needed.
+
+**Prefilling the assistant message** (putting a trailing `Role.Assistant` message in the input) is **not supported** on Claude Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6 — requests return a 400. Use `OutputConfig.Format` (structured outputs) instead.
+
+## Stop Details
+
+When `StopReason` is `"refusal"`, the response includes structured `StopDetails`:
+
+```csharp
+if (response.StopReason == "refusal" && response.StopDetails is { } details)
+{
+    Console.WriteLine($"Category: {details.Category}");
+    Console.WriteLine($"Explanation: {details.Explanation}");
+}
+```
+
+**Refusal fallbacks (Claude Fable 5) — opt in by default.** Fallbacks are opt-in: without them a refused request simply stops. In `claude-fable-5` code, include `Fallbacks = [new(Model.ClaudeOpus4_8)]` plus the `AnthropicBeta.ServerSideFallback2026_06_01` beta on the beta messages call by default — a policy decline is re-served by the fallback model inside the same call. Not available on Amazon Bedrock, Vertex AI, or Microsoft Foundry — use the client-side handler there: `new AnthropicClient { Handlers = [new BetaRefusalFallbackHandler { Fallbacks = [new(Model.ClaudeOpus4_8)] }] }` (namespace `Anthropic.Helpers`), with per-conversation state via `BetaFallbackState.Create()` scoped with `using (fallbackState.Use()) { ... }`. Full semantics (billing, sticky routing, streaming) and a runnable example: `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason, and the C# SDK repo's `examples/` (WebFetch via `shared/live-sources.md`).
+
+---
+
+## Managed Agents (Beta)
+
+The C# SDK supports Managed Agents via `client.Beta.Agents`, `client.Beta.Sessions`, `client.Beta.Environments`, and related namespaces. See `shared/managed-agents-overview.md` for the architecture and `curl/managed-agents.md` for the wire-level reference.

skills/claude-api/csharp/claude-api/batches.md

@@ -0,0 +1,14 @@
+# Message Batches — C#
+
+## Message Batches API
+
+```csharp
+var batch = await client.Messages.Batches.Create(new() {
+    Requests = [
+        new() { CustomID = "req-1", Params = new() { Model = "claude-opus-5", MaxTokens = 1024, Messages = [...] } },
+    ],
+});
+// Poll client.Messages.Batches.Retrieve(batch.ID) until ProcessingStatus == "ended",
+// then iterate client.Messages.Batches.Results(batch.ID).
+```
+

skills/claude-api/csharp/claude-api/files-api.md

@@ -0,0 +1,23 @@
+# Files API — C#
+
+## Files API (Beta)
+
+Files live under `client.Beta.Files` (namespace `Anthropic.Models.Beta.Files`). `BinaryContent` implicit-converts from `Stream` and `byte[]`.
+
+```csharp
+using Anthropic.Models.Beta.Files;
+using Anthropic.Models.Beta.Messages;
+
+FileMetadata meta = await client.Beta.Files.Upload(
+    new FileUploadParams { File = File.OpenRead("doc.pdf") });
+
+// Referencing the uploaded file requires Beta message types:
+new BetaRequestDocumentBlock {
+    Source = new BetaFileDocumentSource { FileID = meta.ID },
+}
+```
+
+The non-beta `DocumentBlockParamSource` union has no file-ID variant — file references need `client.Beta.Messages.Create()`.
+
+---
+

skills/claude-api/csharp/claude-api/streaming.md

@@ -0,0 +1,28 @@
+# Streaming — C#
+
+## Streaming
+
+```csharp
+using Anthropic.Models.Messages;
+
+var parameters = new MessageCreateParams
+{
+    Model = Model.ClaudeOpus4_8,
+    MaxTokens = 64000,
+    Messages = [new() { Role = Role.User, Content = "Write a haiku" }]
+};
+
+await foreach (RawMessageStreamEvent streamEvent in client.Messages.CreateStreaming(parameters))
+{
+    if (streamEvent.TryPickContentBlockDelta(out var delta) &&
+        delta.Delta.TryPickText(out var text))
+    {
+        Console.Write(text.Text);
+    }
+}
+```
+
+**`RawMessageStreamEvent` TryPick methods** (naming drops the `Message`/`Raw` prefix): `TryPickStart`, `TryPickDelta`, `TryPickStop`, `TryPickContentBlockStart`, `TryPickContentBlockDelta`, `TryPickContentBlockStop`. There is no `TryPickMessageStop` — use `TryPickStop`.
+
+---
+

skills/claude-api/csharp/claude-api/tool-use.md

@@ -0,0 +1,164 @@
+# Tool Use — C#
+
+For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
+
+## Tool Use
+
+### Defining a tool
+
+`Tool` (NOT `ToolParam`) with an `InputSchema` record. `InputSchema.Type` is auto-set to `"object"` by the constructor — don't set it. `ToolUnion` has an implicit conversion from `Tool`, triggered by the collection expression `[...]`.
+
+```csharp
+using System.Text.Json;
+using Anthropic.Models.Messages;
+
+var parameters = new MessageCreateParams
+{
+    Model = Model.ClaudeSonnet4_6,
+    MaxTokens = 16000,
+    Tools = [
+        new Tool {
+            Name = "get_weather",
+            Description = "Get the current weather in a given location",
+            InputSchema = new() {
+                Properties = new Dictionary<string, JsonElement> {
+                    ["location"] = JsonSerializer.SerializeToElement(
+                        new { type = "string", description = "City name" }),
+                },
+                Required = ["location"],
+            },
+        },
+    ],
+    Messages = [new() { Role = Role.User, Content = "Weather in Paris?" }],
+};
+```
+
+Derived from `anthropic-sdk-csharp/src/Anthropic/Models/Messages/Tool.cs` and `ToolUnion.cs:799` (implicit conversion).
+
+See [shared tool use concepts](../../shared/tool-use-concepts.md) for the loop pattern.
+### Converting response content to the follow-up assistant message
+
+When echoing Claude's response back in the assistant turn, **there is no `.ToParam()` helper** — manually reconstruct each `ContentBlock` variant as its `*Param` counterpart. Do NOT use `new ContentBlockParam(block.Json)`: it compiles and serializes, but `.Value` stays `null` so `TryPick*`/`Validate()` fail (degraded JSON pass-through, not the typed path).
+
+```csharp
+using Anthropic.Models.Messages;
+
+Message response = await client.Messages.Create(parameters);
+
+// No .ToParam() — reconstruct per variant. Implicit conversions from each
+// *Param type to ContentBlockParam mean no explicit wrapper.
+List<ContentBlockParam> assistantContent = [];
+List<ContentBlockParam> toolResults = [];
+foreach (ContentBlock block in response.Content)
+{
+    if (block.TryPickText(out TextBlock? text))
+    {
+        assistantContent.Add(new TextBlockParam { Text = text.Text });
+    }
+    else if (block.TryPickThinking(out ThinkingBlock? thinking))
+    {
+        // Signature MUST be preserved — the API rejects tampering
+        assistantContent.Add(new ThinkingBlockParam
+        {
+            Thinking = thinking.Thinking,
+            Signature = thinking.Signature,
+        });
+    }
+    else if (block.TryPickRedactedThinking(out RedactedThinkingBlock? redacted))
+    {
+        assistantContent.Add(new RedactedThinkingBlockParam { Data = redacted.Data });
+    }
+    else if (block.TryPickToolUse(out ToolUseBlock? toolUse))
+    {
+        // ToolUseBlock has required Caller; ToolUseBlockParam.Caller is optional — don't copy it
+        assistantContent.Add(new ToolUseBlockParam
+        {
+            ID = toolUse.ID,
+            Name = toolUse.Name,
+            Input = toolUse.Input,
+        });
+        // Execute the tool; collect ONE result per tool_use block — the API
+        // rejects the follow-up if any tool_use ID lacks a matching tool_result.
+        string result = ExecuteYourTool(toolUse.Name, toolUse.Input);
+        toolResults.Add(new ToolResultBlockParam
+        {
+            ToolUseID = toolUse.ID,
+            Content = result,
+        });
+    }
+}
+
+// Follow-up: prior messages + assistant echo + user tool_result(s)
+List<MessageParam> followUpMessages =
+[
+    .. parameters.Messages,
+    new() { Role = Role.Assistant, Content = assistantContent },
+    new() { Role = Role.User, Content = toolResults },
+];
+```
+
+`ToolResultBlockParam` has no tuple constructor — use the object initializer. `Content` is a string-or-list union; a plain `string` implicitly converts.
+
+---
+
+## Structured Output
+
+```csharp
+OutputConfig = new OutputConfig {
+    Format = new JsonOutputFormat {
+        Schema = new Dictionary<string, JsonElement> {
+            ["type"] = JsonSerializer.SerializeToElement("object"),
+            ["properties"] = JsonSerializer.SerializeToElement(
+                new { name = new { type = "string" } }),
+            ["required"] = JsonSerializer.SerializeToElement(new[] { "name" }),
+        },
+    },
+},
+```
+
+`JsonOutputFormat.Type` is auto-set to `"json_schema"` by the constructor. `Schema` is `required`.
+
+---
+
+## Anthropic-Defined Tools
+
+Web search, bash, text editor, and code execution are Anthropic-defined tools with built-in schemas. Web search and code execution are server-executed; bash and text editor are client-executed (you handle the `tool_use` locally — see `shared/tool-use-concepts.md`). Type names are version-suffixed; constructors auto-set `name`/`type`. **Wrap each in `new ToolUnion(...)` explicitly.**
+
+```csharp
+Tools = [
+    new ToolUnion(new WebSearchTool20260209()),
+    new ToolUnion(new ToolBash20250124()),
+    new ToolUnion(new ToolTextEditor20250728()),
+    new ToolUnion(new CodeExecutionTool20260120()),
+],
+```
+
+Also available: `new ToolUnion(new WebFetchTool20260209())`, `new ToolUnion(new MemoryTool20250818())`. `WebSearchTool20260209` optionals: `AllowedDomains`, `BlockedDomains`, `MaxUses`, `UserLocation`.
+
+---
+
+## Tool Runner (Beta)
+
+The C# SDK provides a `BetaToolRunner` for automatic tool execution loops. Define tools with raw JSON schemas, and the runner handles the API call → tool execution → result feedback loop.
+
+```csharp
+using Anthropic.Models.Beta.Messages;
+
+// Define tools and create params as shown in the Tool Use section above,
+// but using the beta namespace types (BetaToolUnion, etc.)
+var runner = client.Beta.Messages.ToolRunner(betaParams);
+
+await foreach (BetaMessage message in runner)
+{
+    foreach (var block in message.Content)
+    {
+        if (block.TryPickText(out var text))
+        {
+            Console.WriteLine(text.Text);
+        }
+    }
+}
+```
+
+---
+

skills/claude-api/curl/examples.md

@@ -18,7 +18,7 @@ curl https://api.anthropic.com/v1/messages \
   -H "x-api-key: $ANTHROPIC_API_KEY" \
   -H "anthropic-version: 2023-06-01" \
   -d '{
-    "model": "claude-opus-4-8",
+    "model": "claude-opus-5",
     "max_tokens": 16000,
     "messages": [
       {"role": "user", "content": "What is the capital of France?"}
@@ -38,7 +38,7 @@ response=$(curl -s https://api.anthropic.com/v1/messages \
   -H "Content-Type: application/json" \
   -H "x-api-key: $ANTHROPIC_API_KEY" \
   -H "anthropic-version: 2023-06-01" \
-  -d '{"model":"claude-opus-4-8","max_tokens":16000,"messages":[{"role":"user","content":"Hello"}]}')
+  -d '{"model":"claude-opus-5","max_tokens":16000,"messages":[{"role":"user","content":"Hello"}]}')
 
 # Print the first text block (-r strips the JSON quotes)
 echo "$response" | jq -r '.content[0].text'
@@ -65,7 +65,7 @@ curl https://api.anthropic.com/v1/messages \
   -H "x-api-key: $ANTHROPIC_API_KEY" \
   -H "anthropic-version: 2023-06-01" \
   -d '{
-    "model": "claude-opus-4-8",
+    "model": "claude-opus-5",
     "max_tokens": 64000,
     "stream": true,
     "messages": [{"role": "user", "content": "Write a haiku"}]
@@ -104,7 +104,7 @@ curl https://api.anthropic.com/v1/messages \
   -H "x-api-key: $ANTHROPIC_API_KEY" \
   -H "anthropic-version: 2023-06-01" \
   -d '{
-    "model": "claude-opus-4-8",
+    "model": "claude-opus-5",
     "max_tokens": 16000,
     "tools": [{
       "name": "get_weather",
@@ -129,7 +129,7 @@ curl https://api.anthropic.com/v1/messages \
   -H "x-api-key: $ANTHROPIC_API_KEY" \
   -H "anthropic-version: 2023-06-01" \
   -d '{
-    "model": "claude-opus-4-8",
+    "model": "claude-opus-5",
     "max_tokens": 16000,
     "tools": [{
       "name": "get_weather",
@@ -167,7 +167,7 @@ curl https://api.anthropic.com/v1/messages \
   -H "x-api-key: $ANTHROPIC_API_KEY" \
   -H "anthropic-version: 2023-06-01" \
   -d '{
-    "model": "claude-opus-4-8",
+    "model": "claude-opus-5",
     "max_tokens": 16000,
     "system": [
       {"type": "text", "text": "<large shared prompt...>", "cache_control": {"type": "ephemeral"}}
@@ -182,20 +182,22 @@ For 1-hour TTL: `"cache_control": {"type": "ephemeral", "ttl": "1h"}`. Top-level
 
 ## Extended Thinking
 
-> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Claude Opus 5:** thinking is on by default — omitting `"thinking"` runs adaptive (`{"type": "adaptive"}` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `{"type": "disabled"}` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400.
 > **Older models:** Use `"type": "enabled"` with `"budget_tokens": N` (must be < `max_tokens`, min 1024).
 
 ```bash
-# Fable 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
+# Fable 5 / Claude Opus 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
 curl https://api.anthropic.com/v1/messages \
   -H "Content-Type: application/json" \
   -H "x-api-key: $ANTHROPIC_API_KEY" \
   -H "anthropic-version: 2023-06-01" \
   -d '{
-    "model": "claude-opus-4-8",
+    "model": "claude-opus-5",
     "max_tokens": 16000,
     "thinking": {
-      "type": "adaptive"
+      "type": "adaptive",
+      "display": "summarized"
     },
     "output_config": {
       "effort": "high"
@@ -206,6 +208,44 @@ curl https://api.anthropic.com/v1/messages \
 
 ---
 
+## Refusal Fallbacks (Claude Fable 5) — opt in by default
+
+On `claude-fable-5`, safety classifiers may decline a request (HTTP 200 with `stop_reason: "refusal"`). Fallbacks are **opt-in**: without them the request simply stops. Include the `fallbacks` parameter and its beta header by default — on a policy decline the API re-runs the same request on the fallback model inside the same call. A decline before any output isn't billed (a mid-stream decline bills the streamed partial); the rescue bills at the fallback model's own rates.
+
+```bash
+response=$(curl -s https://api.anthropic.com/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "anthropic-beta: server-side-fallback-2026-06-01" \
+  -d '{
+    "model": "claude-fable-5",
+    "max_tokens": 16000,
+    "fallbacks": [{"model": "claude-opus-4-8"}],
+    "messages": [{"role": "user", "content": "Hello"}]
+  }')
+
+# Which model produced the message
+echo "$response" | jq -r '.model'
+
+# Refusal on the final response means the whole chain refused
+echo "$response" | jq -r '.stop_reason'
+
+# Switch points: one fallback block per model that ran and declined this turn
+echo "$response" | jq -r '.content[] | select(.type == "fallback") | "\(.from.model) declined; \(.to.model) continued"'
+
+# Served-by signal — covers sticky turns, which carry no fallback block.
+# Pair with stop_reason: the fallback model can itself refuse.
+if [ "$(echo "$response" | jq -r '.stop_reason')" != "refusal" ] && \
+   echo "$response" | jq -e '[.usage.iterations[]? | select(.type == "fallback_message")] | length > 0' > /dev/null; then
+  echo "fallback model served this turn"
+fi
+```
+
+The header must be exactly `server-side-fallback-2026-06-01` **for this array form**; the newer `fallbacks: "default"` scalar form uses `server-side-fallback-2026-07-01` instead (see `shared/model-migration.md` → Migrating to Claude Opus 5 → New API features), and pairing either header with the other form returns a 400. The parameter is rejected on the Batches API and unavailable on Amazon Bedrock, Vertex AI, and Microsoft Foundry. Full semantics (sticky routing, billing, streaming, echoing fallback turns back): `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason.
+
+---
+
 ## Required Headers
 
 | Header              | Value              | Description                |

skills/claude-api/curl/managed-agents.md

@@ -65,7 +65,7 @@ curl -X POST https://api.anthropic.com/v1/agents \
   "${HEADERS[@]}" \
   -d '{
     "name": "Coding Assistant",
-    "model": "claude-opus-4-8",
+    "model": "claude-opus-5",
     "tools": [{ "type": "agent_toolset_20260401" }]
   }'
 # → { "id": "agent_abc123", ... }
@@ -77,6 +77,8 @@ curl -X POST https://api.anthropic.com/v1/sessions \
     "agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" },
     "environment_id": "env_abc123"
   }'
+# → { "id": "sesn_abc123", ... }
+# Trace: https://platform.claude.com/workspaces/default/sessions/sesn_abc123  (swap 'default' for your workspace ID if the API key is not in the Default workspace)
 ```
 
 ### With system prompt, custom tools, and GitHub repo
@@ -87,7 +89,7 @@ curl -X POST https://api.anthropic.com/v1/agents \
   "${HEADERS[@]}" \
   -d '{
     "name": "Code Reviewer",
-    "model": "claude-opus-4-8",
+    "model": "claude-opus-5",
     "system": "You are a senior code reviewer. Be thorough and constructive.",
     "tools": [
       { "type": "agent_toolset_20260401" },
@@ -208,7 +210,7 @@ curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
   -d '{
     "events": [
       {
-        "type": "interrupt"
+        "type": "user.interrupt"
       }
     ]
   }'
@@ -293,7 +295,7 @@ curl -X POST https://api.anthropic.com/v1/agents \
   "${HEADERS[@]}" \
   -d '{
     "name": "MCP Agent",
-    "model": "claude-opus-4-8",
+    "model": "claude-opus-5",
     "mcp_servers": [
       { "type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse" }
     ],
@@ -324,7 +326,7 @@ curl -X POST https://api.anthropic.com/v1/agents \
   "${HEADERS[@]}" \
   -d '{
     "name": "Restricted Agent",
-    "model": "claude-opus-4-8",
+    "model": "claude-opus-5",
     "tools": [
       {
         "type": "agent_toolset_20260401",

skills/claude-api/go/claude-api.md

@@ -1,440 +0,0 @@
-# Claude API — Go
-
-> **Note:** The Go SDK supports the Claude API and beta tool use with `BetaToolRunner`. Agent SDK is not yet available for Go.
-
-## Installation
-
-```bash
-go get github.com/anthropics/anthropic-sdk-go
-```
-
-## Client Initialization
-
-```go
-import (
-    "github.com/anthropics/anthropic-sdk-go"
-    "github.com/anthropics/anthropic-sdk-go/option"
-)
-
-// Default (uses ANTHROPIC_API_KEY env var)
-client := anthropic.NewClient()
-
-// Explicit API key
-client := anthropic.NewClient(
-    option.WithAPIKey("your-api-key"),
-)
-```
-
----
-
-## Model Constants
-
-The Go SDK provides typed model constants: `anthropic.ModelClaudeFable5`, `anthropic.ModelClaudeOpus4_8`, `anthropic.ModelClaudeOpus4_7`, `anthropic.ModelClaudeSonnet4_6`, `anthropic.ModelClaudeHaiku4_5_20251001`. Use `ModelClaudeOpus4_8` unless the user specifies otherwise; if they ask for Fable or the most powerful model, use `anthropic.ModelClaudeFable5` (see `shared/models.md` for the full resolution table).
-
----
-
-## Basic Message Request
-
-```go
-response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
-    Model:     anthropic.ModelClaudeOpus4_8,
-    MaxTokens: 16000,
-    Messages: []anthropic.MessageParam{
-        anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")),
-    },
-})
-if err != nil {
-    log.Fatal(err)
-}
-for _, block := range response.Content {
-    switch variant := block.AsAny().(type) {
-    case anthropic.TextBlock:
-        fmt.Println(variant.Text)
-    }
-}
-```
-
----
-
-## Streaming
-
-```go
-stream := client.Messages.NewStreaming(context.Background(), anthropic.MessageNewParams{
-    Model:     anthropic.ModelClaudeOpus4_6,
-    MaxTokens: 64000,
-    Messages: []anthropic.MessageParam{
-        anthropic.NewUserMessage(anthropic.NewTextBlock("Write a haiku")),
-    },
-})
-
-for stream.Next() {
-    event := stream.Current()
-    switch eventVariant := event.AsAny().(type) {
-    case anthropic.ContentBlockDeltaEvent:
-        switch deltaVariant := eventVariant.Delta.AsAny().(type) {
-        case anthropic.TextDelta:
-            fmt.Print(deltaVariant.Text)
-        }
-    }
-}
-if err := stream.Err(); err != nil {
-    log.Fatal(err)
-}
-```
-
-**Accumulating the final message** (there is no `GetFinalMessage()` on the stream):
-
-```go
-stream := client.Messages.NewStreaming(ctx, params)
-message := anthropic.Message{}
-for stream.Next() {
-    message.Accumulate(stream.Current())
-}
-if err := stream.Err(); err != nil { log.Fatal(err) }
-// message.Content now has the complete response
-```
-
-
----
-
-## Tool Use
-
-### Tool Runner (Beta — Recommended)
-
-**Beta:** The Go SDK provides `BetaToolRunner` for automatic tool use loops via the `toolrunner` package.
-
-```go
-import (
-    "context"
-    "fmt"
-    "log"
-
-    "github.com/anthropics/anthropic-sdk-go"
-    "github.com/anthropics/anthropic-sdk-go/toolrunner"
-)
-
-// Define tool input with jsonschema tags for automatic schema generation
-type GetWeatherInput struct {
-    City string `json:"city" jsonschema:"required,description=The city name"`
-}
-
-// Create a tool with automatic schema generation from struct tags
-weatherTool, err := toolrunner.NewBetaToolFromJSONSchema(
-    "get_weather",
-    "Get current weather for a city",
-    func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
-        return anthropic.BetaToolResultBlockParamContentUnion{
-            OfText: &anthropic.BetaTextBlockParam{
-                Text: fmt.Sprintf("The weather in %s is sunny, 72°F", input.City),
-            },
-        }, nil
-    },
-)
-if err != nil {
-    log.Fatal(err)
-}
-
-// Create a tool runner that handles the conversation loop automatically
-runner := client.Beta.Messages.NewToolRunner(
-    []anthropic.BetaTool{weatherTool},
-    anthropic.BetaToolRunnerParams{
-        BetaMessageNewParams: anthropic.BetaMessageNewParams{
-            Model:     anthropic.ModelClaudeOpus4_6,
-            MaxTokens: 16000,
-            Messages: []anthropic.BetaMessageParam{
-                anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Paris?")),
-            },
-        },
-        MaxIterations: 5,
-    },
-)
-
-// Run until Claude produces a final response
-message, err := runner.RunToCompletion(context.Background())
-if err != nil {
-    log.Fatal(err)
-}
-
-// RunToCompletion returns *BetaMessage; content is []BetaContentBlockUnion.
-// Narrow via AsAny() switch — note the Beta-namespace types (BetaTextBlock,
-// not TextBlock):
-for _, block := range message.Content {
-    switch block := block.AsAny().(type) {
-    case anthropic.BetaTextBlock:
-        fmt.Println(block.Text)
-    }
-}
-```
-
-**Key features of the Go tool runner:**
-
-- Automatic schema generation from Go structs via `jsonschema` tags
-- `RunToCompletion()` for simple one-shot usage
-- `All()` iterator for processing each message in the conversation
-- `NextMessage()` for step-by-step iteration
-- Streaming variant via `NewToolRunnerStreaming()` with `AllStreaming()`
-
-### Manual Loop
-
-For fine-grained control over the agentic loop, define tools with `ToolParam`, check `StopReason`, execute tools yourself, and feed `tool_result` blocks back. This is the pattern when you need to intercept, validate, or log tool calls.
-
-Derived from `anthropic-sdk-go/examples/tools/main.go`.
-
-```go
-package main
-
-import (
-    "context"
-    "encoding/json"
-    "fmt"
-    "log"
-
-    "github.com/anthropics/anthropic-sdk-go"
-)
-
-func main() {
-    client := anthropic.NewClient()
-
-    // 1. Define tools. ToolParam.InputSchema uses a map, no struct tags needed.
-    addTool := anthropic.ToolParam{
-        Name:        "add",
-        Description: anthropic.String("Add two integers"),
-        InputSchema: anthropic.ToolInputSchemaParam{
-            Properties: map[string]any{
-                "a": map[string]any{"type": "integer"},
-                "b": map[string]any{"type": "integer"},
-            },
-        },
-    }
-    // ToolParam must be wrapped in ToolUnionParam for the Tools slice
-    tools := []anthropic.ToolUnionParam{{OfTool: &addTool}}
-
-    messages := []anthropic.MessageParam{
-        anthropic.NewUserMessage(anthropic.NewTextBlock("What is 2 + 3?")),
-    }
-
-    for {
-        resp, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
-            Model:     anthropic.ModelClaudeSonnet4_6,
-            MaxTokens: 16000,
-            Messages:  messages,
-            Tools:     tools,
-        })
-        if err != nil {
-            log.Fatal(err)
-        }
-
-        // 2. Append the assistant response to history BEFORE processing tool calls.
-        //    resp.ToParam() converts Message → MessageParam in one call.
-        messages = append(messages, resp.ToParam())
-
-        // 3. Walk content blocks. ContentBlockUnion is a flattened struct;
-        //    use block.AsAny().(type) to switch on the actual variant.
-        toolResults := []anthropic.ContentBlockParamUnion{}
-        for _, block := range resp.Content {
-            switch variant := block.AsAny().(type) {
-            case anthropic.TextBlock:
-                fmt.Println(variant.Text)
-            case anthropic.ToolUseBlock:
-                // 4. Parse the tool input. Use variant.JSON.Input.Raw() to get the
-                //    raw JSON — block.Input is json.RawMessage, not the parsed value.
-                var in struct {
-                    A int `json:"a"`
-                    B int `json:"b"`
-                }
-                if err := json.Unmarshal([]byte(variant.JSON.Input.Raw()), &in); err != nil {
-                    log.Fatal(err)
-                }
-                result := fmt.Sprintf("%d", in.A+in.B)
-                // 5. NewToolResultBlock(toolUseID, content, isError) builds the
-                //    ContentBlockParamUnion for you. block.ID is the tool_use_id.
-                toolResults = append(toolResults,
-                    anthropic.NewToolResultBlock(block.ID, result, false))
-            }
-        }
-
-        // 6. Exit when Claude stops asking for tools
-        if resp.StopReason != anthropic.StopReasonToolUse {
-            break
-        }
-
-        // 7. Tool results go in a user message (variadic: all results in one turn)
-        messages = append(messages, anthropic.NewUserMessage(toolResults...))
-    }
-}
-```
-
-**Key API surface:**
-
-| Symbol | Purpose |
-|---|---|
-| `resp.ToParam()` | Convert `Message` response → `MessageParam` for history |
-| `block.AsAny().(type)` | Type-switch on `ContentBlockUnion` variants |
-| `variant.JSON.Input.Raw()` | Raw JSON string of tool input (for `json.Unmarshal`) |
-| `anthropic.NewToolResultBlock(id, content, isError)` | Build `tool_result` block |
-| `anthropic.NewUserMessage(blocks...)` | Wrap tool results as a user turn |
-| `anthropic.StopReasonToolUse` | `StopReason` constant to check loop termination |
-| `anthropic.ToolUnionParam{OfTool: &t}` | Wrap `ToolParam` in the union for `Tools:` |
-
----
-
-## Thinking
-
-Enable Claude's internal reasoning by setting `Thinking` in `MessageNewParams`. The response will contain `ThinkingBlock` content before the final `TextBlock`.
-
-**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. Combine with the `effort` parameter for cost-quality control.
-
-Derived from `anthropic-sdk-go/message.go` (`ThinkingConfigParamUnion`, `ThinkingConfigAdaptiveParam`).
-
-```go
-// There is no ThinkingConfigParamOfAdaptive helper — construct the union
-// struct-literal directly and take the address of the variant.
-adaptive := anthropic.ThinkingConfigAdaptiveParam{}
-params := anthropic.MessageNewParams{
-    Model:     anthropic.ModelClaudeSonnet4_6,
-    MaxTokens: 16000,
-    Thinking:  anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive},
-    Messages: []anthropic.MessageParam{
-        anthropic.NewUserMessage(anthropic.NewTextBlock("How many r's in strawberry?")),
-    },
-}
-
-resp, err := client.Messages.New(context.Background(), params)
-if err != nil {
-    log.Fatal(err)
-}
-
-// ThinkingBlock(s) precede TextBlock in content
-for _, block := range resp.Content {
-    switch b := block.AsAny().(type) {
-    case anthropic.ThinkingBlock:
-        fmt.Println("[thinking]", b.Thinking)
-    case anthropic.TextBlock:
-        fmt.Println(b.Text)
-    }
-}
-```
-
-> **Deprecated:** `ThinkingConfigParamOfEnabled(budgetTokens)` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
-
-To disable: `anthropic.ThinkingConfigParamUnion{OfDisabled: &anthropic.ThinkingConfigDisabledParam{}}`.
-
----
-
-## Prompt Caching
-
-`System` is `[]TextBlockParam`; set `CacheControl` on the last block to cache tools + system together. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
-
-```go
-System: []anthropic.TextBlockParam{{
-    Text:         longSystemPrompt,
-    CacheControl: anthropic.NewCacheControlEphemeralParam(), // default 5m TTL
-}},
-```
-
-For 1-hour TTL: `anthropic.CacheControlEphemeralParam{TTL: anthropic.CacheControlEphemeralTTLTTL1h}`. There's also a top-level `CacheControl` on `MessageNewParams` that auto-places on the last cacheable block.
-
-Verify hits via `resp.Usage.CacheCreationInputTokens` / `resp.Usage.CacheReadInputTokens`.
-
----
-
-## Server-Side Tools
-
-Version-suffixed struct names with `Param` suffix. `Name`/`Type` are `constant.*` types — zero value marshals correctly, so `{}` works. Wrap in `ToolUnionParam` with the matching `Of*` field.
-
-```go
-Tools: []anthropic.ToolUnionParam{
-    {OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}},
-    {OfBashTool20250124: &anthropic.ToolBash20250124Param{}},
-    {OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
-    {OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}},
-},
-```
-
-Also available: `WebFetchTool20260209Param`, `MemoryTool20250818Param`, `ToolSearchToolBm25_20251119Param`, `ToolSearchToolRegex20251119Param`. For the advisor tool, use `BetaAdvisorTool20260301Param` in the beta namespace.
-
----
-
-## Stop Details
-
-When `StopReason` is `anthropic.StopReasonRefusal`, the response includes structured `StopDetails`:
-
-```go
-if resp.StopReason == anthropic.StopReasonRefusal {
-    fmt.Println("Category:", resp.StopDetails.Category)     // "cyber" | "bio" | ""
-    fmt.Println("Explanation:", resp.StopDetails.Explanation)
-}
-```
-
----
-
-## PDF / Document Input
-
-`NewDocumentBlock` generic helper accepts any source type. `MediaType`/`Type` are auto-set.
-
-```go
-b64 := base64.StdEncoding.EncodeToString(pdfBytes)
-
-msg := anthropic.NewUserMessage(
-    anthropic.NewDocumentBlock(anthropic.Base64PDFSourceParam{Data: b64}),
-    anthropic.NewTextBlock("Summarize this document"),
-)
-```
-
-Other sources: `URLPDFSourceParam{URL: "https://..."}`, `PlainTextSourceParam{Data: "..."}`.
-
----
-
-## Files API (Beta)
-
-Under `client.Beta.Files`. Method is **`Upload`** (NOT `New`/`Create`), params struct is `BetaFileUploadParams`. The `File` field takes an `io.Reader`; use `anthropic.File()` to attach a filename + content-type for the multipart encoding.
-
-```go
-f, _ := os.Open("./upload_me.txt")
-defer f.Close()
-
-meta, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
-    File:  anthropic.File(f, "upload_me.txt", "text/plain"),
-    Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14},
-})
-// meta.ID is the file_id to reference in subsequent message requests
-```
-
-Other `Beta.Files` methods: `List`, `Delete`, `Download`, `GetMetadata`.
-
----
-
-## Context Editing / Compaction (Beta)
-
-Use `Beta.Messages.New` with `ContextManagement` on `BetaMessageNewParams`. There is no `NewBetaAssistantMessage` — use `.ToParam()` for the round-trip.
-
-```go
-params := anthropic.BetaMessageNewParams{
-    Model:     anthropic.ModelClaudeOpus4_6,  // also supported: ModelClaudeSonnet4_6
-    MaxTokens: 16000,
-    Betas:     []anthropic.AnthropicBeta{"compact-2026-01-12"},
-    ContextManagement: anthropic.BetaContextManagementConfigParam{
-        Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
-            {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
-        },
-    },
-    Messages: []anthropic.BetaMessageParam{ /* ... */ },
-}
-
-resp, err := client.Beta.Messages.New(ctx, params)
-if err != nil {
-    log.Fatal(err)
-}
-
-// Round-trip: append response to history via .ToParam()
-params.Messages = append(params.Messages, resp.ToParam())
-
-// Read compaction blocks from the response
-for _, block := range resp.Content {
-    if c, ok := block.AsAny().(anthropic.BetaCompactionBlock); ok {
-        fmt.Println("compaction summary:", c.Content)
-    }
-}
-```
-
-Other edit types: `BetaClearToolUses20250919EditParam`, `BetaClearThinking20251015EditParam`.

skills/claude-api/go/claude-api/README.md

@@ -0,0 +1,188 @@
+# Claude API — Go
+
+> **Note:** The Go SDK supports the Claude API and beta tool use with `BetaToolRunner`. Agent SDK is not yet available for Go.
+
+## Installation
+
+```bash
+go get github.com/anthropics/anthropic-sdk-go
+```
+
+## Client Initialization
+
+```go
+import (
+    "github.com/anthropics/anthropic-sdk-go"
+    "github.com/anthropics/anthropic-sdk-go/option"
+)
+
+// Default (uses ANTHROPIC_API_KEY env var)
+client := anthropic.NewClient()
+
+// Explicit API key
+client := anthropic.NewClient(
+    option.WithAPIKey("your-api-key"),
+)
+```
+
+---
+
+## Model Constants
+
+The Go SDK provides typed model constants: `anthropic.ModelClaudeFable5`, `anthropic.ModelClaudeOpus4_8`, `anthropic.ModelClaudeOpus4_7`, `anthropic.ModelClaudeSonnet4_6`, `anthropic.ModelClaudeHaiku4_5_20251001`. Default to Claude Opus 5 unless the user specifies otherwise; if they ask for Fable or the most powerful model, use `anthropic.ModelClaudeFable5` (see `shared/models.md` for the full resolution table).
+
+`anthropic.Model` is an alias for `string`, so a model with no typed constant yet — including Claude Opus 5 — is passed as the plain id: `Model: "claude-opus-5"`. Check the SDK release notes for a typed `Claude Opus 5` constant before assuming one exists.
+
+---
+
+## Basic Message Request
+
+```go
+response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
+    Model:     "claude-opus-5",
+    MaxTokens: 16000,
+    Messages: []anthropic.MessageParam{
+        anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")),
+    },
+})
+if err != nil {
+    log.Fatal(err)
+}
+for _, block := range response.Content {
+    switch variant := block.AsAny().(type) {
+    case anthropic.TextBlock:
+        fmt.Println(variant.Text)
+    }
+}
+```
+
+---
+
+## Thinking
+
+Enable Claude's internal reasoning by setting `Thinking` in `MessageNewParams`. The response will contain `ThinkingBlock` content before the final `TextBlock`.
+
+**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. Combine with the `effort` parameter for cost-quality control.
+
+Derived from `anthropic-sdk-go/message.go` (`ThinkingConfigParamUnion`, `ThinkingConfigAdaptiveParam`).
+
+```go
+// There is no ThinkingConfigParamOfAdaptive helper — construct the union
+// struct-literal directly and take the address of the variant.
+adaptive := anthropic.ThinkingConfigAdaptiveParam{}
+params := anthropic.MessageNewParams{
+    Model:     anthropic.ModelClaudeSonnet4_6,
+    MaxTokens: 16000,
+    Thinking:  anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive},
+    Messages: []anthropic.MessageParam{
+        anthropic.NewUserMessage(anthropic.NewTextBlock("How many r's in strawberry?")),
+    },
+}
+
+resp, err := client.Messages.New(context.Background(), params)
+if err != nil {
+    log.Fatal(err)
+}
+
+// ThinkingBlock(s) precede TextBlock in content
+for _, block := range resp.Content {
+    switch b := block.AsAny().(type) {
+    case anthropic.ThinkingBlock:
+        fmt.Println("[thinking]", b.Thinking)
+    case anthropic.TextBlock:
+        fmt.Println(b.Text)
+    }
+}
+```
+
+> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (above). `ThinkingConfigParamOfEnabled(budgetTokens)` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Claude Opus 5:** thinking is on by default — leaving `Thinking` unset runs adaptive (the adaptive union is equivalent), unlike Opus 4.8/4.7 where leaving it unset meant no thinking.
+> **Older models:** Use `anthropic.ThinkingConfigParamOfEnabled(N)` (budget must be < `MaxTokens`, min 1024).
+
+To disable: `anthropic.ThinkingConfigParamUnion{OfDisabled: &anthropic.ThinkingConfigDisabledParam{}}`. On Claude Opus 5 that is accepted only at effort `high` or lower — pairing it with `xhigh`/`max` returns a 400.
+
+---
+
+## Prompt Caching
+
+`System` is `[]TextBlockParam`; set `CacheControl` on the last block to cache tools + system together. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
+
+```go
+System: []anthropic.TextBlockParam{{
+    Text:         longSystemPrompt,
+    CacheControl: anthropic.NewCacheControlEphemeralParam(), // default 5m TTL
+}},
+```
+
+For 1-hour TTL: `anthropic.CacheControlEphemeralParam{TTL: anthropic.CacheControlEphemeralTTLTTL1h}`. There's also a top-level `CacheControl` on `MessageNewParams` that auto-places on the last cacheable block.
+
+Verify hits via `resp.Usage.CacheCreationInputTokens` / `resp.Usage.CacheReadInputTokens`.
+
+---
+
+## Stop Details
+
+When `StopReason` is `anthropic.StopReasonRefusal`, the response includes structured `StopDetails`:
+
+```go
+if resp.StopReason == anthropic.StopReasonRefusal {
+    fmt.Println("Category:", resp.StopDetails.Category)     // e.g. "cyber", "bio", "reasoning_extraction", "frontier_llm", or "" — see docs for the full set
+    fmt.Println("Explanation:", resp.StopDetails.Explanation)
+}
+```
+
+**Refusal fallbacks (Claude Fable 5) — opt in by default.** Fallbacks are opt-in: without them a refused request simply stops. In `claude-fable-5` code, include `Fallbacks: []anthropic.BetaFallbackParam{{Model: "claude-opus-4-8"}}` plus the `anthropic.AnthropicBetaServerSideFallback2026_06_01` beta on `client.Beta.Messages.New` by default — a policy decline is re-served by the fallback model inside the same call. Not available on Amazon Bedrock, Vertex AI, or Microsoft Foundry — register the client-side middleware there: `option.WithMiddleware(betafallback.BetaRefusalFallbackMiddleware(...))` from `lib/betafallback`, with per-conversation state via `betafallback.WithBetaFallbackState(&betafallback.BetaFallbackState{})`. Full semantics (billing, sticky routing, streaming) and a runnable example: `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason, and the Go SDK repo's `examples/` (WebFetch via `shared/live-sources.md`).
+
+---
+
+## PDF / Document Input
+
+`NewDocumentBlock` generic helper accepts any source type. `MediaType`/`Type` are auto-set.
+
+```go
+b64 := base64.StdEncoding.EncodeToString(pdfBytes)
+
+msg := anthropic.NewUserMessage(
+    anthropic.NewDocumentBlock(anthropic.Base64PDFSourceParam{Data: b64}),
+    anthropic.NewTextBlock("Summarize this document"),
+)
+```
+
+Other sources: `URLPDFSourceParam{URL: "https://..."}`, `PlainTextSourceParam{Data: "..."}`.
+
+---
+
+## Context Editing / Compaction (Beta)
+
+Use `Beta.Messages.New` with `ContextManagement` on `BetaMessageNewParams`. There is no `NewBetaAssistantMessage` — use `.ToParam()` for the round-trip.
+
+```go
+params := anthropic.BetaMessageNewParams{
+    Model:     "claude-opus-5",  // also supported: ModelClaudeOpus4_8, ModelClaudeSonnet4_6
+    MaxTokens: 16000,
+    Betas:     []anthropic.AnthropicBeta{"compact-2026-01-12"},
+    ContextManagement: anthropic.BetaContextManagementConfigParam{
+        Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
+            {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
+        },
+    },
+    Messages: []anthropic.BetaMessageParam{ /* ... */ },
+}
+
+resp, err := client.Beta.Messages.New(ctx, params)
+if err != nil {
+    log.Fatal(err)
+}
+
+// Round-trip: append response to history via .ToParam()
+params.Messages = append(params.Messages, resp.ToParam())
+
+// Read compaction blocks from the response
+for _, block := range resp.Content {
+    if c, ok := block.AsAny().(anthropic.BetaCompactionBlock); ok {
+        fmt.Println("compaction summary:", c.Content)
+    }
+}
+```
+
+Other edit types: `BetaClearToolUses20250919EditParam`, `BetaClearThinking20251015EditParam` — these need `Betas: []anthropic.AnthropicBeta{"context-management-2025-06-27"}`, not `compact-2026-01-12`.

skills/claude-api/go/claude-api/files-api.md

@@ -0,0 +1,21 @@
+# Files API — Go
+
+## Files API (Beta)
+
+Under `client.Beta.Files`. Method is **`Upload`** (NOT `New`/`Create`), params struct is `BetaFileUploadParams`. The `File` field takes an `io.Reader`; use `anthropic.File()` to attach a filename + content-type for the multipart encoding.
+
+```go
+f, _ := os.Open("./upload_me.txt")
+defer f.Close()
+
+meta, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
+    File:  anthropic.File(f, "upload_me.txt", "text/plain"),
+    Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14},
+})
+// meta.ID is the file_id to reference in subsequent message requests
+```
+
+Other `Beta.Files` methods: `List`, `Delete`, `Download`, `GetMetadata`.
+
+---
+

skills/claude-api/go/claude-api/streaming.md

@@ -0,0 +1,43 @@
+# Streaming — Go
+
+## Streaming
+
+```go
+stream := client.Messages.NewStreaming(context.Background(), anthropic.MessageNewParams{
+    Model:     anthropic.ModelClaudeOpus4_8,
+    MaxTokens: 64000,
+    Messages: []anthropic.MessageParam{
+        anthropic.NewUserMessage(anthropic.NewTextBlock("Write a haiku")),
+    },
+})
+
+for stream.Next() {
+    event := stream.Current()
+    switch eventVariant := event.AsAny().(type) {
+    case anthropic.ContentBlockDeltaEvent:
+        switch deltaVariant := eventVariant.Delta.AsAny().(type) {
+        case anthropic.TextDelta:
+            fmt.Print(deltaVariant.Text)
+        }
+    }
+}
+if err := stream.Err(); err != nil {
+    log.Fatal(err)
+}
+```
+
+**Accumulating the final message** (there is no `GetFinalMessage()` on the stream):
+
+```go
+stream := client.Messages.NewStreaming(ctx, params)
+message := anthropic.Message{}
+for stream.Next() {
+    message.Accumulate(stream.Current())
+}
+if err := stream.Err(); err != nil { log.Fatal(err) }
+// message.Content now has the complete response
+```
+
+
+---
+

skills/claude-api/go/claude-api/tool-use.md

@@ -0,0 +1,220 @@
+# Tool Use — Go
+
+For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
+
+## Tool Use
+
+### Tool Runner (Beta — Recommended)
+
+**Beta:** The Go SDK provides `BetaToolRunner` for automatic tool use loops via the `toolrunner` package.
+
+```go
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/anthropics/anthropic-sdk-go"
+    "github.com/anthropics/anthropic-sdk-go/toolrunner"
+)
+
+// Define tool input with jsonschema tags for automatic schema generation
+type GetWeatherInput struct {
+    City string `json:"city" jsonschema:"required,description=The city name"`
+}
+
+// Create a tool with automatic schema generation from struct tags
+weatherTool, err := toolrunner.NewBetaToolFromJSONSchema(
+    "get_weather",
+    "Get current weather for a city",
+    func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
+        return anthropic.BetaToolResultBlockParamContentUnion{
+            OfText: &anthropic.BetaTextBlockParam{
+                Text: fmt.Sprintf("The weather in %s is sunny, 72°F", input.City),
+            },
+        }, nil
+    },
+)
+if err != nil {
+    log.Fatal(err)
+}
+
+// Create a tool runner that handles the conversation loop automatically
+runner := client.Beta.Messages.NewToolRunner(
+    []anthropic.BetaTool{weatherTool},
+    anthropic.BetaToolRunnerParams{
+        BetaMessageNewParams: anthropic.BetaMessageNewParams{
+            Model:     anthropic.ModelClaudeOpus4_8,
+            MaxTokens: 16000,
+            Messages: []anthropic.BetaMessageParam{
+                anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Paris?")),
+            },
+        },
+        MaxIterations: 5,
+    },
+)
+
+// Run until Claude produces a final response
+message, err := runner.RunToCompletion(context.Background())
+if err != nil {
+    log.Fatal(err)
+}
+
+// RunToCompletion returns *BetaMessage; content is []BetaContentBlockUnion.
+// Narrow via AsAny() switch — note the Beta-namespace types (BetaTextBlock,
+// not TextBlock):
+for _, block := range message.Content {
+    switch block := block.AsAny().(type) {
+    case anthropic.BetaTextBlock:
+        fmt.Println(block.Text)
+    }
+}
+```
+
+**Key features of the Go tool runner:**
+
+- Automatic schema generation from Go structs via `jsonschema` tags
+- `RunToCompletion()` for simple one-shot usage
+- `All()` iterator for processing each message in the conversation
+- `NextMessage()` for step-by-step iteration
+- Streaming variant via `NewToolRunnerStreaming()` with `AllStreaming()`
+
+### Manual Loop
+
+Prefer the tool runner above. For interception, validation, logging, or human-in-the-loop approval, gate inside the tool's run function or step the runner with `NextMessage()`/`All()` and inspect each message (the runner's public `Params` field lets you adjust the next request) — a manual loop is not required. Drop to a manual loop only when you need control the runner does not expose: define tools with `ToolParam`, check `StopReason`, execute tools yourself, and feed `tool_result` blocks back.
+
+Derived from `anthropic-sdk-go/examples/tools/main.go`.
+
+```go
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "fmt"
+    "log"
+
+    "github.com/anthropics/anthropic-sdk-go"
+)
+
+func main() {
+    client := anthropic.NewClient()
+
+    // 1. Define tools. ToolParam.InputSchema uses a map, no struct tags needed.
+    addTool := anthropic.ToolParam{
+        Name:        "add",
+        Description: anthropic.String("Add two integers"),
+        InputSchema: anthropic.ToolInputSchemaParam{
+            Properties: map[string]any{
+                "a": map[string]any{"type": "integer"},
+                "b": map[string]any{"type": "integer"},
+            },
+        },
+    }
+    // ToolParam must be wrapped in ToolUnionParam for the Tools slice
+    tools := []anthropic.ToolUnionParam{{OfTool: &addTool}}
+
+    messages := []anthropic.MessageParam{
+        anthropic.NewUserMessage(anthropic.NewTextBlock("What is 2 + 3?")),
+    }
+
+    for {
+        resp, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
+            Model:     anthropic.ModelClaudeSonnet4_6,
+            MaxTokens: 16000,
+            Messages:  messages,
+            Tools:     tools,
+        })
+        if err != nil {
+            log.Fatal(err)
+        }
+
+        // 2. Append the assistant response to history BEFORE processing tool calls.
+        //    resp.ToParam() converts Message → MessageParam in one call.
+        messages = append(messages, resp.ToParam())
+
+        // 3. Walk content blocks. ContentBlockUnion is a flattened struct;
+        //    use block.AsAny().(type) to switch on the actual variant.
+        toolResults := []anthropic.ContentBlockParamUnion{}
+        for _, block := range resp.Content {
+            switch variant := block.AsAny().(type) {
+            case anthropic.TextBlock:
+                fmt.Println(variant.Text)
+            case anthropic.ToolUseBlock:
+                // 4. Parse the tool input. Use variant.JSON.Input.Raw() to get the
+                //    raw JSON — block.Input is json.RawMessage, not the parsed value.
+                var in struct {
+                    A int `json:"a"`
+                    B int `json:"b"`
+                }
+                if err := json.Unmarshal([]byte(variant.JSON.Input.Raw()), &in); err != nil {
+                    log.Fatal(err)
+                }
+                result := fmt.Sprintf("%d", in.A+in.B)
+                // 5. NewToolResultBlock(toolUseID, content, isError) builds the
+                //    ContentBlockParamUnion for you. block.ID is the tool_use_id.
+                toolResults = append(toolResults,
+                    anthropic.NewToolResultBlock(block.ID, result, false))
+            }
+        }
+
+        // 6. Exit when Claude stops asking for tools
+        if resp.StopReason != anthropic.StopReasonToolUse {
+            break
+        }
+
+        // 7. Tool results go in a user message (variadic: all results in one turn)
+        messages = append(messages, anthropic.NewUserMessage(toolResults...))
+    }
+}
+```
+
+**Key API surface:**
+
+| Symbol | Purpose |
+|---|---|
+| `resp.ToParam()` | Convert `Message` response → `MessageParam` for history |
+| `block.AsAny().(type)` | Type-switch on `ContentBlockUnion` variants |
+| `variant.JSON.Input.Raw()` | Raw JSON string of tool input (for `json.Unmarshal`) |
+| `anthropic.NewToolResultBlock(id, content, isError)` | Build `tool_result` block |
+| `anthropic.NewUserMessage(blocks...)` | Wrap tool results as a user turn |
+| `anthropic.StopReasonToolUse` | `StopReason` constant to check loop termination |
+| `anthropic.ToolUnionParam{OfTool: &t}` | Wrap `ToolParam` in the union for `Tools:` |
+
+---
+
+## Anthropic-Defined Tools
+
+Version-suffixed struct names with `Param` suffix. `Name`/`Type` are `constant.*` types — zero value marshals correctly, so `{}` works. Wrap in `ToolUnionParam` with the matching `Of*` field. Web search and code execution are server-executed; bash and text editor are client-executed (you handle the `tool_use` locally — see `shared/tool-use-concepts.md`).
+
+```go
+Tools: []anthropic.ToolUnionParam{
+    {OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}},
+    {OfBashTool20250124: &anthropic.ToolBash20250124Param{}},
+    {OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
+    {OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}},
+},
+```
+
+Also available: `WebFetchTool20260209Param`, `ToolSearchToolBm25_20251119Param`, `ToolSearchToolRegex20251119Param`. For the advisor and memory tools, use `BetaAdvisorTool20260301Param` / `BetaMemoryTool20250818Param` in the beta namespace on `client.Beta.Messages.New`.
+
+### Advisor tool (beta)
+
+Server-side — no tool_result round-trip. The advisor model must be ≥ the executor (top-level) model; invalid pairs return 400.
+
+```go
+response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
+    Model:     anthropic.ModelClaudeSonnet4_6,
+    MaxTokens: 4096,
+    Tools: []anthropic.BetaToolUnionParam{
+        {OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
+            Model: anthropic.ModelClaudeOpus4_8,
+        }},
+    },
+    Messages: []anthropic.BetaMessageParam{ /* ... */ },
+    Betas:    []anthropic.AnthropicBeta{anthropic.AnthropicBetaAdvisorTool2026_03_01},
+})
+```
+
+---
+

skills/claude-api/go/managed-agents/README.md

@@ -2,7 +2,7 @@
 
 > **Bindings not shown here:** This README covers the most common managed-agents flows for Go. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Go SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
 
-> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.New` and pass it to every subsequent `sessions.New`; do not call `agents.New` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
+> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.New` and pass it to every subsequent `sessions.New`; do not call `agents.New` in the request path. **Recommended:** define agents and environments as version-controlled YAML applied with the `ant` CLI — see `shared/anthropic-cli.md` (its live-docs URL is in `shared/live-sources.md`). The CLI owns the control plane (create/update); your code owns the data plane (sessions with the stored ID). The examples below show in-code creation for when you must provision programmatically; in production the create call belongs in setup, not in the request path.
 
 ## Installation
 
@@ -38,9 +38,11 @@ ctx := context.Background()
 ```go
 environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
     Name: "my-dev-env",
-    Config: anthropic.BetaCloudConfigParams{
-        Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
-            OfUnrestricted: &anthropic.UnrestrictedNetworkParam{},
+    Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
+        OfCloud: &anthropic.BetaCloudConfigParams{
+            Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
+                OfUnrestricted: &anthropic.BetaUnrestrictedNetworkParam{},
+            },
         },
     },
 })
@@ -63,7 +65,7 @@ fmt.Println(environment.ID) // env_...
 agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
     Name: "Coding Assistant",
     Model: anthropic.BetaManagedAgentsModelConfigParams{
-        ID:   "claude-opus-4-8",
+        ID:   "claude-opus-5",
         Type: anthropic.BetaManagedAgentsModelConfigParamsTypeModelConfig,
     },
     System: anthropic.String("You are a helpful coding assistant."),
@@ -93,6 +95,7 @@ if err != nil {
     panic(err)
 }
 fmt.Printf("Session ID: %s, status: %s\n", session.ID, session.Status)
+fmt.Printf("Trace: https://platform.claude.com/workspaces/default/sessions/%s\n", session.ID) // swap 'default' for your workspace ID if the API key is not in the Default workspace
 ```
 
 ### Updating an Agent
@@ -132,7 +135,7 @@ if err != nil {
 
 ```go
 _, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
-    Events: []anthropic.SendEventsParamsUnion{{
+    Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
         OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
             Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
             Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
@@ -161,7 +164,7 @@ stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.Be
 defer stream.Close()
 
 if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
-    Events: []anthropic.SendEventsParamsUnion{{
+    Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
         OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
             Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
             Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
@@ -380,11 +383,11 @@ if err != nil {
 agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
     Name: "GitHub Assistant",
     Model: anthropic.BetaManagedAgentsModelConfigParams{
-        ID:   "claude-opus-4-8",
+        ID:   "claude-opus-5",
         Type: anthropic.BetaManagedAgentsModelConfigParamsTypeModelConfig,
     },
-    MCPServers: []anthropic.BetaManagedAgentsUrlmcpServerParams{{
-        Type: anthropic.BetaManagedAgentsUrlmcpServerParamsTypeURL,
+    MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{
+        Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,
         Name: "github",
         URL:  "https://api.githubcopilot.com/mcp/",
     }},

skills/claude-api/java/claude-api/README.md

@@ -0,0 +1,238 @@
+# Claude API — Java
+
+> **Note:** The Java SDK supports the Claude API and beta tool use with annotated classes. Agent SDK is not yet available for Java.
+
+## Package Reference
+
+Types are organized by package. If a class you need isn't shown in an example below, locate it via this table first — don't block on fetching SDK source over the network.
+
+| `import` prefix | Contains |
+|---|---|
+| `com.anthropic.client` / `com.anthropic.client.okhttp` | `AnthropicClient`, `AnthropicOkHttpClient` |
+| `com.anthropic.models.messages` | non-beta request/response types — `MessageCreateParams`, `Model`, `Message`, `TextBlockParam`, `ContentBlockParam`, `ToolUseBlockParam`, `ToolResultBlockParam`, `CacheControlEphemeral`, `Tool*` (e.g. `ToolBash20250124`, `ToolTextEditor20250728`), `StopReason`, `StructuredMessage*` |
+| `com.anthropic.models.messages.batches` | Batch API — `BatchResultsParams`, `MessageBatchIndividualResponse` |
+| `com.anthropic.models.beta` | `AnthropicBeta` (beta-flag constants) |
+| `com.anthropic.models.beta.messages` | beta-endpoint types — `MessageCreateParams`, `BetaMessage`, `BetaStopReason`, `BetaContextManagementConfig`, `BetaMcpToolset`, `BetaRequestMcpServerUrlDefinition`, `BetaTool*` |
+| `com.anthropic.core` | `JsonValue`, `JsonField`, `JsonSchemaLocalValidation`, `com.anthropic.core.http.StreamResponse` |
+| `com.anthropic.errors` | typed exceptions — `AnthropicServiceException`, `RateLimitException`, `NotFoundException`, etc. (see `shared/error-codes.md`) |
+
+`client.messages()` uses `com.anthropic.models.messages.*`; `client.beta().messages()` uses `com.anthropic.models.beta.messages.*`. Both packages define a `MessageCreateParams` — import the one matching the client path you call.
+
+### Key types per feature
+
+Write from this table instead of `javap`/jar inspection. Endpoint column tells you whether to use `client.messages()` or `client.beta().messages()`.
+
+| Feature | Endpoint | Key Java types / builder calls |
+|---|---|---|
+| User profiles | beta | `client.beta().userProfiles().create(...)` / `.retrieve(id)` / `.list()`. Pass the returned profile id on the beta `MessageCreateParams`. Requires a beta header — check the SDK's beta-headers reference for the current flag. |
+| Agent Skills | beta | `BetaContainerParams`, `BetaSkillParams`, `BetaCodeExecutionTool20250825`. `.addBeta("code-execution-2025-08-25").addBeta("skills-2025-10-02")`. Download the output via `client.beta().files().download(fileId)`. |
+| Cache diagnostics | beta | `BetaDiagnosticsParam`, `BetaCacheControlEphemeral` |
+| Context editing | beta | `.contextManagement(BetaContextManagementConfig.builder()…)`. The edit strategy is a `BetaClearToolUses20250919Edit` (or `BetaClearThinking20251015Edit`); its trigger is a `BetaInputTokensTrigger` built separately and passed to the edit's builder — there is no direct `.inputTokensTrigger(N)` shortcut on the edit builder. `javap` the edit and trigger classes for the exact setter names. |
+| Memory tool | non-beta | `.addTool(MemoryTool20250818.builder().build())` from `com.anthropic.models.messages` |
+| Programmatic tool calling | non-beta | `CodeExecutionTool20260120`, `Tool`, `ContentBlockParam` |
+| Strict tool use | non-beta | `Tool`, `Tool.InputSchema` |
+| Task budgets | beta | `.outputConfig(BetaOutputConfig.builder().taskBudget(BetaTokenTaskBudget.builder()...))` |
+| Tool search | non-beta | `.addTool(ToolSearchToolRegex20251119.builder()...)` from `com.anthropic.models.messages` |
+| Web search | non-beta | `WebSearchTool20260209` from `com.anthropic.models.messages` — the latest variant with dynamic filtering (Claude Fable 5 + Claude Opus 5 + Opus 4.8/4.7/4.6 + Claude Sonnet 5 + Sonnet 4.6). For older models or Vertex, use `WebSearchTool20250305` |
+
+### Discovering type and member names
+
+If a class or builder method you need isn't in the tables above, `jar tf <anthropic-java-core jar> | grep -i <term>` or `javap -classpath <jar> com.anthropic.models.…` is fast enough to locate names. **Do not compile and run a separate reflection program** to enumerate members — the first build is slow enough to be backgrounded in many environments, trapping you in a polling loop. Write the script with the names you found and let the compiler error (`cannot find symbol`) point at any wrong member.
+
+## Installation
+
+Maven:
+
+```xml
+<dependency>
+    <groupId>com.anthropic</groupId>
+    <artifactId>anthropic-java</artifactId>
+    <version>2.34.0</version>
+</dependency>
+```
+
+Gradle:
+
+```groovy
+implementation("com.anthropic:anthropic-java:2.34.0")
+```
+
+## Client Initialization
+
+```java
+import com.anthropic.client.AnthropicClient;
+import com.anthropic.client.okhttp.AnthropicOkHttpClient;
+
+// Default (reads ANTHROPIC_API_KEY from environment)
+AnthropicClient client = AnthropicOkHttpClient.fromEnv();
+
+// Explicit API key
+AnthropicClient client = AnthropicOkHttpClient.builder()
+    .apiKey("your-api-key")
+    .build();
+```
+
+---
+
+## Basic Message Request
+
+```java
+import com.anthropic.models.messages.MessageCreateParams;
+import com.anthropic.models.messages.Message;
+
+MessageCreateParams params = MessageCreateParams.builder()
+    .model("claude-opus-5")  // .model(String) overload — use it for ids with no typed Model constant yet
+    .maxTokens(16000L)
+    .addUserMessage("What is the capital of France?")
+    .build();
+
+Message response = client.messages().create(params);
+response.content().stream()
+    .flatMap(block -> block.text().stream())
+    .forEach(textBlock -> System.out.println(textBlock.text()));
+```
+
+---
+
+## Thinking
+
+**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. The builder has a direct `.thinking(ThinkingConfigAdaptive)` overload — no manual union wrapping.
+
+> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (below). `ThinkingConfigEnabled.builder().budgetTokens(N)` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Claude Opus 5:** thinking is on by default — omitting `.thinking(...)` runs adaptive (`ThinkingConfigAdaptive` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `ThinkingConfigDisabled` is accepted only at effort `HIGH` or lower; pairing it with `XHIGH`/`MAX` returns a 400.
+> **Older models:** Use `.thinking(ThinkingConfigEnabled.builder().budgetTokens(N).build())` (budget must be < `maxTokens`, min 1024).
+
+```java
+import com.anthropic.models.messages.ContentBlock;
+import com.anthropic.models.messages.MessageCreateParams;
+import com.anthropic.models.messages.Model;
+import com.anthropic.models.messages.ThinkingConfigAdaptive;
+
+MessageCreateParams params = MessageCreateParams.builder()
+    .model(Model.CLAUDE_SONNET_4_6)
+    .maxTokens(16000L)
+    .thinking(ThinkingConfigAdaptive.builder().build())
+    .addUserMessage("Solve this step by step: 27 * 453")
+    .build();
+
+for (ContentBlock block : client.messages().create(params).content()) {
+    block.thinking().ifPresent(t -> System.out.println("[thinking] " + t.thinking()));
+    block.text().ifPresent(t -> System.out.println(t.text()));
+}
+```
+
+`ContentBlock` narrowing: `.thinking()` / `.text()` return `Optional<T>` — use `.ifPresent(...)` or `.stream().flatMap(...)`. Alternative: `isThinking()` / `asThinking()` boolean+unwrap pairs (throws on wrong variant).
+
+---
+
+## Effort Parameter
+
+Effort is nested inside `OutputConfig` — there is NO `.effort()` directly on `MessageCreateParams.Builder`.
+
+```java
+import com.anthropic.models.messages.OutputConfig;
+
+.outputConfig(OutputConfig.builder()
+    .effort(OutputConfig.Effort.HIGH)  // or LOW, MEDIUM, XHIGH, MAX
+    .build())
+```
+
+Combine with `Thinking = ThinkingConfigAdaptive` for cost-quality control.
+
+---
+
+## Prompt Caching
+
+System message as a list of `TextBlockParam` with `CacheControlEphemeral`. Use `.systemOfTextBlockParams(...)` — the plain `.system(String)` overload can't carry cache control. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
+
+```java
+import com.anthropic.models.messages.TextBlockParam;
+import com.anthropic.models.messages.CacheControlEphemeral;
+
+.systemOfTextBlockParams(List.of(
+    TextBlockParam.builder()
+        .text(longSystemPrompt)
+        .cacheControl(CacheControlEphemeral.builder()
+            .ttl(CacheControlEphemeral.Ttl.TTL_1H)  // optional; also TTL_5M
+            .build())
+        .build()))
+```
+
+There's also a top-level `.cacheControl(CacheControlEphemeral)` on `MessageCreateParams.Builder` and on `Tool.builder()`.
+
+Verify hits via `response.usage().cacheCreationInputTokens()` / `response.usage().cacheReadInputTokens()`.
+
+---
+
+## Token Counting
+
+```java
+import com.anthropic.models.messages.MessageCountTokensParams;
+
+long tokens = client.messages().countTokens(
+    MessageCountTokensParams.builder()
+        .model(Model.CLAUDE_SONNET_4_6)
+        .addUserMessage("Hello")
+        .build()
+).inputTokens();
+```
+
+---
+
+## PDF / Document Input
+
+`DocumentBlockParam` builder has source shortcuts. Wrap in `ContentBlockParam.ofDocument()` and pass via `.addUserMessageOfBlockParams()`.
+
+```java
+import com.anthropic.models.messages.DocumentBlockParam;
+import com.anthropic.models.messages.ContentBlockParam;
+import com.anthropic.models.messages.TextBlockParam;
+
+DocumentBlockParam doc = DocumentBlockParam.builder()
+    .source(Base64PdfSource.builder().data(base64String).build())
+    // or .source(UrlPdfSource.builder().url("https://...").build())
+    .title("My Document")        // optional
+    .build();
+```
+
+For **Files API** document references, use the beta path and beta types — see `files-api.md`: `BetaRequestDocumentBlock.builder().source(BetaFileDocumentSource.builder().fileId(id).build())`.
+
+```java
+.addUserMessageOfBlockParams(List.of(
+    ContentBlockParam.ofDocument(doc),
+    ContentBlockParam.ofText(TextBlockParam.builder().text("Summarize this").build())))
+```
+
+---
+
+## Stop Details
+
+When `stopReason()` is `"refusal"`, the response includes structured `stopDetails()`:
+
+```java
+response.stopDetails().ifPresent(details -> {
+    System.out.println("Category: " + details.category());
+    System.out.println("Explanation: " + details.explanation());
+});
+```
+
+**Refusal fallbacks (Claude Fable 5) — opt in by default.** Fallbacks are opt-in: without them a refused request simply stops. New `claude-fable-5` code should include the server-side `fallbacks` parameter (beta header `server-side-fallback-2026-06-01`, fallback model `claude-opus-4-8`, on the beta messages call) by default. The exact Java builder methods (and the client-side middleware for providers without server-side support) are not documented here — WebFetch the Java SDK repo's `examples/` from `shared/live-sources.md`; full semantics in `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason.
+
+---
+
+## Error Type
+
+`AnthropicServiceException` exposes `.errorType()` returning `Optional<ErrorType>` for programmatic error classification:
+
+```java
+try {
+    client.messages().create(params);
+} catch (AnthropicServiceException e) {
+    e.errorType().ifPresent(type ->
+        System.out.println("Error type: " + type)  // RATE_LIMIT_ERROR, OVERLOADED_ERROR, etc.
+    );
+}
+```
+
+---
+

skills/claude-api/java/claude-api/files-api.md

@@ -0,0 +1,25 @@
+# Files API — Java
+
+## Files API (Beta)
+
+Under `client.beta().files()`. File references in messages need the beta message types (non-beta `DocumentBlockParam.Source` has no file-ID variant).
+
+```java
+import com.anthropic.models.beta.files.FileUploadParams;
+import com.anthropic.models.beta.files.FileMetadata;
+import com.anthropic.models.beta.messages.BetaRequestDocumentBlock;
+import com.anthropic.models.beta.messages.BetaFileDocumentSource;
+import java.nio.file.Paths;
+
+FileMetadata meta = client.beta().files().upload(
+    FileUploadParams.builder()
+        .file(Paths.get("/path/to/doc.pdf"))  // or .file(InputStream) or .file(byte[])
+        .build());
+
+// Reference in a beta message:
+BetaRequestDocumentBlock doc = BetaRequestDocumentBlock.builder()
+    .source(BetaFileDocumentSource.builder().fileId(meta.id()).build())
+    .build();
+```
+
+Other methods: `.list()`, `.delete(String fileId)`, `.download(String fileId)`, `.retrieveMetadata(String fileId)`.

skills/claude-api/java/claude-api/streaming.md

@@ -0,0 +1,24 @@
+# Streaming — Java
+
+## Streaming
+
+```java
+import com.anthropic.core.http.StreamResponse;
+import com.anthropic.models.messages.RawMessageStreamEvent;
+
+MessageCreateParams params = MessageCreateParams.builder()
+    .model(Model.CLAUDE_OPUS_4_8)
+    .maxTokens(64000L)
+    .addUserMessage("Write a haiku")
+    .build();
+
+try (StreamResponse<RawMessageStreamEvent> streamResponse = client.messages().createStreaming(params)) {
+    streamResponse.stream()
+        .flatMap(event -> event.contentBlockDelta().stream())
+        .flatMap(deltaEvent -> deltaEvent.delta().text().stream())
+        .forEach(textDelta -> System.out.print(textDelta.text()));
+}
+```
+
+---
+

skills/claude-api/java/claude-api/tool-use.md

@@ -1,113 +1,6 @@
-# Claude API — Java
+# Tool Use — Java
 
-> **Note:** The Java SDK supports the Claude API and beta tool use with annotated classes. Agent SDK is not yet available for Java.
-
-## Installation
-
-Maven:
-
-```xml
-<dependency>
-    <groupId>com.anthropic</groupId>
-    <artifactId>anthropic-java</artifactId>
-    <version>2.34.0</version>
-</dependency>
-```
-
-Gradle:
-
-```groovy
-implementation("com.anthropic:anthropic-java:2.34.0")
-```
-
-## Client Initialization
-
-```java
-import com.anthropic.client.AnthropicClient;
-import com.anthropic.client.okhttp.AnthropicOkHttpClient;
-
-// Default (reads ANTHROPIC_API_KEY from environment)
-AnthropicClient client = AnthropicOkHttpClient.fromEnv();
-
-// Explicit API key
-AnthropicClient client = AnthropicOkHttpClient.builder()
-    .apiKey("your-api-key")
-    .build();
-```
-
----
-
-## Basic Message Request
-
-```java
-import com.anthropic.models.messages.MessageCreateParams;
-import com.anthropic.models.messages.Message;
-import com.anthropic.models.messages.Model;
-
-MessageCreateParams params = MessageCreateParams.builder()
-    .model(Model.CLAUDE_OPUS_4_6)
-    .maxTokens(16000L)
-    .addUserMessage("What is the capital of France?")
-    .build();
-
-Message response = client.messages().create(params);
-response.content().stream()
-    .flatMap(block -> block.text().stream())
-    .forEach(textBlock -> System.out.println(textBlock.text()));
-```
-
----
-
-## Streaming
-
-```java
-import com.anthropic.core.http.StreamResponse;
-import com.anthropic.models.messages.RawMessageStreamEvent;
-
-MessageCreateParams params = MessageCreateParams.builder()
-    .model(Model.CLAUDE_OPUS_4_6)
-    .maxTokens(64000L)
-    .addUserMessage("Write a haiku")
-    .build();
-
-try (StreamResponse<RawMessageStreamEvent> streamResponse = client.messages().createStreaming(params)) {
-    streamResponse.stream()
-        .flatMap(event -> event.contentBlockDelta().stream())
-        .flatMap(deltaEvent -> deltaEvent.delta().text().stream())
-        .forEach(textDelta -> System.out.print(textDelta.text()));
-}
-```
-
----
-
-## Thinking
-
-**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. The builder has a direct `.thinking(ThinkingConfigAdaptive)` overload — no manual union wrapping.
-
-```java
-import com.anthropic.models.messages.ContentBlock;
-import com.anthropic.models.messages.MessageCreateParams;
-import com.anthropic.models.messages.Model;
-import com.anthropic.models.messages.ThinkingConfigAdaptive;
-
-MessageCreateParams params = MessageCreateParams.builder()
-    .model(Model.CLAUDE_SONNET_4_6)
-    .maxTokens(16000L)
-    .thinking(ThinkingConfigAdaptive.builder().build())
-    .addUserMessage("Solve this step by step: 27 * 453")
-    .build();
-
-for (ContentBlock block : client.messages().create(params).content()) {
-    block.thinking().ifPresent(t -> System.out.println("[thinking] " + t.thinking()));
-    block.text().ifPresent(t -> System.out.println(t.text()));
-}
-```
-
-> **Deprecated:** `ThinkingConfigEnabled.builder().budgetTokens(N)` (and the `.enabledThinking(N)` shortcut) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
-
-`ContentBlock` narrowing: `.thinking()` / `.text()` return `Optional<T>` — use `.ifPresent(...)` or `.stream().flatMap(...)`. Alternative: `isThinking()` / `asThinking()` boolean+unwrap pairs (throws on wrong variant).
-
----
+For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
 
 ## Tool Use (Beta)
 
@@ -136,7 +29,7 @@ static class GetWeather implements Supplier<String> {
 
 BetaToolRunner toolRunner = client.beta().messages().toolRunner(
     MessageCreateParams.builder()
-        .model("claude-opus-4-8")
+        .model("claude-opus-5")
         .maxTokens(16000L)
         .putAdditionalHeader("anthropic-beta", "structured-outputs-2025-11-13")
         .addTool(GetWeather.class)
@@ -164,7 +57,7 @@ import com.anthropic.models.beta.messages.ToolRunnerCreateParams;
 BetaMemoryToolHandler memoryHandler = new FileSystemMemoryToolHandler(sandboxRoot);
 
 MessageCreateParams createParams = MessageCreateParams.builder()
-    .model("claude-opus-4-8")
+    .model("claude-opus-5")
     .maxTokens(4096L)
     .addTool(BetaMemoryTool20250818.builder().build())
     .addUserMessage("Remember that my favorite color is blue")
@@ -181,7 +74,7 @@ for (BetaMessage message : toolRunner) {
 }
 ```
 
-See the [shared memory tool concepts](../shared/tool-use-concepts.md) for more details on the memory tool.
+See the [shared memory tool concepts](../../shared/tool-use-concepts.md) for more details on the memory tool.
 
 ### Non-Beta Tool Declaration (manual JSON schema)
 
@@ -210,7 +103,7 @@ MessageCreateParams params = MessageCreateParams.builder()
     .build();
 ```
 
-For manual tool loops, handle `tool_use` blocks in the response, send `tool_result` back, loop until `stop_reason` is `"end_turn"`. See [shared tool use concepts](../shared/tool-use-concepts.md).
+For manual tool loops, handle `tool_use` blocks in the response, send `tool_result` back, loop until `stop_reason` is `"end_turn"`. See [shared tool use concepts](../../shared/tool-use-concepts.md).
 
 ### Building `MessageParam` with Content Blocks (Tool Result Round-Trip)
 
@@ -236,60 +129,6 @@ MessageParam toolResultMsg = MessageParam.builder()
 
 ---
 
-## Effort Parameter
-
-Effort is nested inside `OutputConfig` — there is NO `.effort()` directly on `MessageCreateParams.Builder`.
-
-```java
-import com.anthropic.models.messages.OutputConfig;
-
-.outputConfig(OutputConfig.builder()
-    .effort(OutputConfig.Effort.HIGH)  // or LOW, MEDIUM, MAX
-    .build())
-```
-
-Combine with `Thinking = ThinkingConfigAdaptive` for cost-quality control.
-
----
-
-## Prompt Caching
-
-System message as a list of `TextBlockParam` with `CacheControlEphemeral`. Use `.systemOfTextBlockParams(...)` — the plain `.system(String)` overload can't carry cache control. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
-
-```java
-import com.anthropic.models.messages.TextBlockParam;
-import com.anthropic.models.messages.CacheControlEphemeral;
-
-.systemOfTextBlockParams(List.of(
-    TextBlockParam.builder()
-        .text(longSystemPrompt)
-        .cacheControl(CacheControlEphemeral.builder()
-            .ttl(CacheControlEphemeral.Ttl.TTL_1H)  // optional; also TTL_5M
-            .build())
-        .build()))
-```
-
-There's also a top-level `.cacheControl(CacheControlEphemeral)` on `MessageCreateParams.Builder` and on `Tool.builder()`.
-
-Verify hits via `response.usage().cacheCreationInputTokens()` / `response.usage().cacheReadInputTokens()`.
-
----
-
-## Token Counting
-
-```java
-import com.anthropic.models.messages.MessageCountTokensParams;
-
-long tokens = client.messages().countTokens(
-    MessageCountTokensParams.builder()
-        .model(Model.CLAUDE_SONNET_4_6)
-        .addUserMessage("Hello")
-        .build()
-).inputTokens();
-```
-
----
-
 ## Structured Output
 
 The class-based overload auto-derives the JSON schema from your POJO and gives you a typed `.text()` return — no manual schema, no manual parsing.
@@ -319,30 +158,9 @@ Supports Jackson annotations: `@JsonPropertyDescription`, `@JsonIgnore`, `@Array
 
 ---
 
-## PDF / Document Input
+## Anthropic-Defined Tools
 
-`DocumentBlockParam` builder has source shortcuts. Wrap in `ContentBlockParam.ofDocument()` and pass via `.addUserMessageOfBlockParams()`.
-
-```java
-import com.anthropic.models.messages.DocumentBlockParam;
-import com.anthropic.models.messages.ContentBlockParam;
-import com.anthropic.models.messages.TextBlockParam;
-
-DocumentBlockParam doc = DocumentBlockParam.builder()
-    .base64Source(base64String)  // or .urlSource("https://...") or .textSource("...")
-    .title("My Document")        // optional
-    .build();
-
-.addUserMessageOfBlockParams(List.of(
-    ContentBlockParam.ofDocument(doc),
-    ContentBlockParam.ofText(TextBlockParam.builder().text("Summarize this").build())))
-```
-
----
-
-## Server-Side Tools
-
-Version-suffixed types; `name`/`type` auto-set by builder. Direct `.addTool()` overloads exist for every type — no manual `ToolUnion` wrapping.
+Version-suffixed types; `name`/`type` auto-set by builder. Direct `.addTool()` overloads exist for most tool types; where one is missing (newer or less-common tools — see the advisor note below), wrap via the union type's static factory: `.addTool(BetaToolUnion.of<ToolName>(builder…build()))`. Web search and code execution are server-executed; bash and text editor are client-executed (you handle the `tool_use` locally — see `shared/tool-use-concepts.md`).
 
 ```java
 import com.anthropic.models.messages.WebSearchTool20260209;
@@ -359,7 +177,7 @@ import com.anthropic.models.messages.CodeExecutionTool20260120;
 .addTool(CodeExecutionTool20260120.builder().build())
 ```
 
-Also available: `WebFetchTool20260209`, `MemoryTool20250818`, `ToolSearchToolBm25_20251119`. For the advisor tool, use `BetaAdvisorTool20260301` in the beta namespace.
+Also available: `WebFetchTool20260209`, `MemoryTool20250818`, `ToolSearchToolBm25_20251119`. For the advisor tool, use `BetaAdvisorTool20260301` in the beta namespace with `.addBeta("advisor-tool-2026-03-01")` (server-side; advisor model ≥ executor model). There is no direct `.addTool(BetaAdvisorTool20260301)` overload on the beta builder — wrap it via the `BetaToolUnion` static factory for the advisor type; if `javac` rejects the specific factory method name, `javap com.anthropic.models.beta.messages.BetaToolUnion | grep -i advisor` shows the exact one.
 
 ### Beta namespace (MCP, compaction)
 
@@ -372,7 +190,7 @@ import com.anthropic.models.beta.messages.BetaCodeExecutionTool20260120;
 import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
 
 MessageCreateParams params = MessageCreateParams.builder()
-    .model(Model.CLAUDE_OPUS_4_6)
+    .model(Model.CLAUDE_OPUS_4_8)
     .maxTokens(16000L)
     .addBeta("mcp-client-2025-11-20")
     .addTool(BetaToolBash20250124.builder().build())
@@ -408,54 +226,3 @@ for (ContentBlock block : response.content()) {
 
 ---
 
-## Stop Details
-
-When `stopReason()` is `"refusal"`, the response includes structured `stopDetails()`:
-
-```java
-response.stopDetails().ifPresent(details -> {
-    System.out.println("Category: " + details.category());
-    System.out.println("Explanation: " + details.explanation());
-});
-```
-
----
-
-## Error Type
-
-`AnthropicServiceException` exposes `.errorType()` returning `Optional<ErrorType>` for programmatic error classification:
-
-```java
-try {
-    client.messages().create(params);
-} catch (AnthropicServiceException e) {
-    e.errorType().ifPresent(type ->
-        System.out.println("Error type: " + type)  // RATE_LIMIT_ERROR, OVERLOADED_ERROR, etc.
-    );
-}
-```
-
----
-
-## Files API (Beta)
-
-Under `client.beta().files()`. File references in messages need the beta message types (non-beta `DocumentBlockParam.Source` has no file-ID variant).
-
-```java
-import com.anthropic.models.beta.files.FileUploadParams;
-import com.anthropic.models.beta.files.FileMetadata;
-import com.anthropic.models.beta.messages.BetaRequestDocumentBlock;
-import java.nio.file.Paths;
-
-FileMetadata meta = client.beta().files().upload(
-    FileUploadParams.builder()
-        .file(Paths.get("/path/to/doc.pdf"))  // or .file(InputStream) or .file(byte[])
-        .build());
-
-// Reference in a beta message:
-BetaRequestDocumentBlock doc = BetaRequestDocumentBlock.builder()
-    .fileSource(meta.id())
-    .build();
-```
-
-Other methods: `.list()`, `.delete(String fileId)`, `.download(String fileId)`, `.retrieveMetadata(String fileId)`.

skills/claude-api/java/managed-agents/README.md

@@ -2,7 +2,7 @@
 
 > **Bindings not shown here:** This README covers the most common managed-agents flows for Java. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Java SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
 
-> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta().agents().create` and pass it to every subsequent `client.beta().sessions().create`; do not call `agents().create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
+> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta().agents().create` and pass it to every subsequent `client.beta().sessions().create`; do not call `agents().create` in the request path. **Recommended:** define agents and environments as version-controlled YAML applied with the `ant` CLI — see `shared/anthropic-cli.md` (its live-docs URL is in `shared/live-sources.md`). The CLI owns the control plane (create/update); your code owns the data plane (sessions with the stored ID). The examples below show in-code creation for when you must provision programmatically; in production the create call belongs in setup, not in the request path.
 
 ## Installation
 
@@ -28,13 +28,13 @@ var client = AnthropicOkHttpClient.fromEnv();
 
 ```java
 import com.anthropic.models.beta.environments.BetaCloudConfigParams;
+import com.anthropic.models.beta.environments.BetaUnrestrictedNetwork;
 import com.anthropic.models.beta.environments.EnvironmentCreateParams;
-import com.anthropic.models.beta.environments.UnrestrictedNetwork;
 
 var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
     .name("my-dev-env")
     .config(BetaCloudConfigParams.builder()
-        .networking(UnrestrictedNetwork.builder().build())
+        .networking(BetaUnrestrictedNetwork.builder().build())
         .build())
     .build());
 System.out.println("Environment ID: " + environment.id()); // env_...
@@ -57,7 +57,7 @@ import com.anthropic.models.beta.sessions.SessionCreateParams;
 // 1. Create the agent (reusable, versioned)
 var agent = client.beta().agents().create(AgentCreateParams.builder()
     .name("Coding Assistant")
-    .model("claude-opus-4-8")
+    .model("claude-opus-5")
     .system("You are a helpful coding assistant.")
     .addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
         .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
@@ -75,6 +75,7 @@ var session = client.beta().sessions().create(SessionCreateParams.builder()
     .title("Quickstart session")
     .build());
 System.out.println("Session ID: " + session.id());
+System.out.println("Trace: https://platform.claude.com/workspaces/default/sessions/" + session.id()); // swap 'default' for your workspace ID if the API key is not in the Default workspace
 ```
 
 ### Updating an Agent
@@ -290,14 +291,14 @@ client.beta().sessions().delete(session.id());
 
 ```java
 import com.anthropic.models.beta.agents.BetaManagedAgentsMcpToolsetParams;
-import com.anthropic.models.beta.agents.BetaManagedAgentsUrlmcpServerParams;
+import com.anthropic.models.beta.agents.BetaManagedAgentsUrlMcpServerParams;
 
 // Agent declares MCP server (no auth here — auth goes in a vault)
 var agent = client.beta().agents().create(AgentCreateParams.builder()
     .name("GitHub Assistant")
-    .model("claude-opus-4-8")
-    .addMcpServer(BetaManagedAgentsUrlmcpServerParams.builder()
-        .type(BetaManagedAgentsUrlmcpServerParams.Type.URL)
+    .model("claude-opus-5")
+    .addMcpServer(BetaManagedAgentsUrlMcpServerParams.builder()
+        .type(BetaManagedAgentsUrlMcpServerParams.Type.URL)
         .name("github")
         .url("https://api.githubcopilot.com/mcp/")
         .build())

skills/claude-api/php/claude-api.md

@@ -1,402 +0,0 @@
-# Claude API — PHP
-
-> **Note:** The PHP SDK is the official Anthropic SDK for PHP. A beta tool runner is available via `$client->beta->messages->toolRunner()`. Structured output helpers are supported via `StructuredOutputModel` classes. Agent SDK is not available. Bedrock, Vertex AI, and Foundry clients are supported.
-
-## Installation
-
-```bash
-composer require "anthropic-ai/sdk"
-```
-
-## Client Initialization
-
-```php
-use Anthropic\Client;
-
-// Using API key from environment variable
-$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
-```
-
-### Amazon Bedrock
-
-```php
-use Anthropic\Bedrock;
-
-// Constructor is private — use the static factory. Reads AWS credentials from env.
-$client = Bedrock\Client::fromEnvironment(region: 'us-east-1');
-```
-
-### Google Vertex AI
-
-```php
-use Anthropic\Vertex;
-
-// Constructor is private. Parameter is `location`, not `region`.
-$client = Vertex\Client::fromEnvironment(
-    location: 'us-east5',
-    projectId: 'my-project-id',
-);
-```
-
-### Anthropic Foundry
-
-```php
-use Anthropic\Foundry;
-
-// Constructor is private. baseUrl or resource is required.
-$client = Foundry\Client::withCredentials(
-    authToken: getenv('ANTHROPIC_FOUNDRY_AUTH_TOKEN'),
-    baseUrl: 'https://<resource>.services.ai.azure.com/anthropic',
-);
-```
-
----
-
-## Basic Message Request
-
-```php
-$message = $client->messages->create(
-    model: 'claude-opus-4-8',
-    maxTokens: 16000,
-    messages: [
-        ['role' => 'user', 'content' => 'What is the capital of France?'],
-    ],
-);
-
-// content is an array of polymorphic blocks (TextBlock, ToolUseBlock,
-// ThinkingBlock). Accessing ->text on content[0] without checking the block
-// type will throw if the first block is not a TextBlock (e.g., when extended
-// thinking is enabled and a ThinkingBlock comes first). Always guard:
-foreach ($message->content as $block) {
-    if ($block->type === 'text') {
-        echo $block->text;
-    }
-}
-```
-
-If you only want the first text block:
-
-```php
-foreach ($message->content as $block) {
-    if ($block->type === 'text') {
-        echo $block->text;
-        break;
-    }
-}
-```
-
----
-
-## Streaming
-
-> **Requires SDK v0.5.0+.** v0.4.0 and earlier used a single `$params` array; calling with named parameters throws `Unknown named parameter $model`. Upgrade: `composer require "anthropic-ai/sdk:^0.7"`
-
-```php
-use Anthropic\Messages\RawContentBlockDeltaEvent;
-use Anthropic\Messages\TextDelta;
-
-$stream = $client->messages->createStream(
-    model: 'claude-opus-4-8',
-    maxTokens: 64000,
-    messages: [
-        ['role' => 'user', 'content' => 'Write a haiku'],
-    ],
-);
-
-foreach ($stream as $event) {
-    if ($event instanceof RawContentBlockDeltaEvent && $event->delta instanceof TextDelta) {
-        echo $event->delta->text;
-    }
-}
-```
-
----
-
-## Tool Use
-
-### Tool Runner (Beta)
-
-**Beta:** The PHP SDK provides a tool runner via `$client->beta->messages->toolRunner()`. Define tools with `BetaRunnableTool` — a definition array plus a `run` closure:
-
-```php
-use Anthropic\Lib\Tools\BetaRunnableTool;
-
-$weatherTool = new BetaRunnableTool(
-    definition: [
-        'name' => 'get_weather',
-        'description' => 'Get the current weather for a location.',
-        'input_schema' => [
-            'type' => 'object',
-            'properties' => [
-                'location' => ['type' => 'string', 'description' => 'City and state'],
-            ],
-            'required' => ['location'],
-        ],
-    ],
-    run: function (array $input): string {
-        return "The weather in {$input['location']} is sunny and 72°F.";
-    },
-);
-
-$runner = $client->beta->messages->toolRunner(
-    maxTokens: 16000,
-    messages: [['role' => 'user', 'content' => 'What is the weather in Paris?']],
-    model: 'claude-opus-4-8',
-    tools: [$weatherTool],
-);
-
-foreach ($runner as $message) {
-    foreach ($message->content as $block) {
-        if ($block->type === 'text') {
-            echo $block->text;
-        }
-    }
-}
-```
-
-### Manual Loop
-
-Tools are passed as arrays. **The SDK uses camelCase keys** (`inputSchema`, `toolUseID`, `stopReason`) and auto-maps to the API's snake_case on the wire — since v0.5.0. See [shared tool use concepts](../shared/tool-use-concepts.md) for the loop pattern.
-
-```php
-use Anthropic\Messages\ToolUseBlock;
-
-$tools = [
-    [
-        'name' => 'get_weather',
-        'description' => 'Get the current weather in a given location',
-        'inputSchema' => [  // camelCase, not input_schema
-            'type' => 'object',
-            'properties' => [
-                'location' => ['type' => 'string', 'description' => 'City and state'],
-            ],
-            'required' => ['location'],
-        ],
-    ],
-];
-
-$messages = [['role' => 'user', 'content' => 'What is the weather in SF?']];
-
-$response = $client->messages->create(
-    model: 'claude-opus-4-8',
-    maxTokens: 16000,
-    tools: $tools,
-    messages: $messages,
-);
-
-while ($response->stopReason === 'tool_use') {  // camelCase property
-    $toolResults = [];
-    foreach ($response->content as $block) {
-        if ($block instanceof ToolUseBlock) {
-            // $block->name  : string               — tool name to dispatch on
-            // $block->input : array<string,mixed>  — parsed JSON input
-            // $block->id    : string               — pass back as toolUseID
-            $result = executeYourTool($block->name, $block->input);
-            $toolResults[] = [
-                'type' => 'tool_result',
-                'toolUseID' => $block->id,  // camelCase, not tool_use_id
-                'content' => $result,
-            ];
-        }
-    }
-
-    // Append assistant turn + user turn with tool results
-    $messages[] = ['role' => 'assistant', 'content' => $response->content];
-    $messages[] = ['role' => 'user', 'content' => $toolResults];
-
-    $response = $client->messages->create(
-        model: 'claude-opus-4-8',
-        maxTokens: 16000,
-        tools: $tools,
-        messages: $messages,
-    );
-}
-
-// Final text response
-foreach ($response->content as $block) {
-    if ($block->type === 'text') {
-        echo $block->text;
-    }
-}
-```
-
-`$block->type === 'tool_use'` also works; `instanceof ToolUseBlock` narrows for PHPStan.
-
-
----
-
-## Extended Thinking
-
-**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think.
-
-```php
-use Anthropic\Messages\ThinkingBlock;
-
-$message = $client->messages->create(
-    model: 'claude-opus-4-8',
-    maxTokens: 16000,
-    thinking: ['type' => 'adaptive'],
-    messages: [
-        ['role' => 'user', 'content' => 'Solve: 27 * 453'],
-    ],
-);
-
-// ThinkingBlock(s) precede TextBlock in content
-foreach ($message->content as $block) {
-    if ($block instanceof ThinkingBlock) {
-        echo "Thinking:\n{$block->thinking}\n\n";
-        // $block->signature is an opaque string — preserve verbatim if
-        // passing thinking blocks back in multi-turn conversations
-    } elseif ($block->type === 'text') {
-        echo "Answer: {$block->text}\n";
-    }
-}
-```
-
-> **Deprecated:** `['type' => 'enabled', 'budgetTokens' => N]` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
-
-`$block->type === 'thinking'` also works for the check; `instanceof` narrows for PHPStan.
-
----
-
-## Prompt Caching
-
-`system:` takes an array of text blocks; set `cacheControl` on the last block. Array-shape syntax (camelCase keys) is idiomatic. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
-
-```php
-$message = $client->messages->create(
-    model: 'claude-opus-4-8',
-    maxTokens: 16000,
-    system: [
-        ['type' => 'text', 'text' => $longSystemPrompt, 'cacheControl' => ['type' => 'ephemeral']],
-    ],
-    messages: [['role' => 'user', 'content' => 'Summarize the key points']],
-);
-```
-
-For 1-hour TTL: `'cacheControl' => ['type' => 'ephemeral', 'ttl' => '1h']`. There's also a top-level `cacheControl:` on `messages->create(...)` that auto-places on the last cacheable block.
-
-Verify hits via `$message->usage->cacheCreationInputTokens` / `$message->usage->cacheReadInputTokens`.
-
----
-
-## Structured Outputs
-
-### Using StructuredOutputModel (Recommended)
-
-Define a PHP class implementing `StructuredOutputModel` and pass it as `outputConfig`:
-
-```php
-use Anthropic\Lib\Contracts\StructuredOutputModel;
-use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
-use Anthropic\Lib\Attributes\Constrained;
-
-class Person implements StructuredOutputModel
-{
-    use StructuredOutputModelTrait;
-
-    #[Constrained(description: 'Full name')]
-    public string $name;
-
-    public int $age;
-
-    public ?string $email = null;  // nullable = optional field
-}
-
-$message = $client->messages->create(
-    model: 'claude-opus-4-8',
-    maxTokens: 16000,
-    messages: [['role' => 'user', 'content' => 'Generate a profile for Alice, age 30']],
-    outputConfig: ['format' => Person::class],
-);
-
-$person = $message->parsedOutput();  // Person instance
-echo $person->name;
-```
-
-Types are inferred from PHP type hints. Use `#[Constrained(description: '...')]` to add descriptions. Nullable properties (`?string`) become optional fields.
-
-### Raw Schema
-
-```php
-$message = $client->messages->create(
-    model: 'claude-opus-4-8',
-    maxTokens: 16000,
-    messages: [['role' => 'user', 'content' => 'Extract: John (john@co.com), Enterprise plan']],
-    outputConfig: [
-        'format' => [
-            'type' => 'json_schema',
-            'schema' => [
-                'type' => 'object',
-                'properties' => [
-                    'name' => ['type' => 'string'],
-                    'email' => ['type' => 'string'],
-                    'plan' => ['type' => 'string'],
-                ],
-                'required' => ['name', 'email', 'plan'],
-                'additionalProperties' => false,
-            ],
-        ],
-    ],
-);
-
-// First text block contains valid JSON
-foreach ($message->content as $block) {
-    if ($block->type === 'text') {
-        $data = json_decode($block->text, true);
-        break;
-    }
-}
-```
-
----
-
-## Beta Features & Server-Side Tools
-
-**`betas:` is NOT a param on `$client->messages->create()`** — it only exists on the beta namespace. Use it for features that need an explicit opt-in header:
-
-```php
-use Anthropic\Beta\Messages\BetaRequestMCPServerURLDefinition;
-
-$response = $client->beta->messages->create(
-    model: 'claude-opus-4-8',
-    maxTokens: 16000,
-    mcpServers: [
-        BetaRequestMCPServerURLDefinition::with(
-            name: 'my-server',
-            url: 'https://example.com/mcp',
-        ),
-    ],
-    betas: ['mcp-client-2025-11-20'],  // only valid on ->beta->messages
-    messages: [['role' => 'user', 'content' => 'Use the MCP tools']],
-);
-```
-
-**Server-side tools** (bash, web_search, text_editor, code_execution) are GA and work on both paths — `Anthropic\Messages\ToolBash20250124` / `WebSearchTool20260209` / `ToolTextEditor20250728` / `CodeExecutionTool20260120` for non-beta, `Anthropic\Beta\Messages\BetaToolBash20250124` / `BetaWebSearchTool20260209` / `BetaToolTextEditor20250728` / `BetaCodeExecutionTool20260120` for beta. No `betas:` header needed for these.
-
----
-
-## Stop Details
-
-When `stopReason` is `'refusal'`, the response includes structured `stopDetails`:
-
-```php
-if ($message->stopReason === 'refusal' && $message->stopDetails !== null) {
-    echo "Category: " . $message->stopDetails->category . "\n";     // "cyber" | "bio" | null
-    echo "Explanation: " . $message->stopDetails->explanation . "\n";
-}
-```
-
----
-
-## Error Type
-
-`APIStatusException` exposes a `->type` property for programmatic error classification:
-
-```php
-try {
-    $client->messages->create(...);
-} catch (\Anthropic\Core\Exceptions\APIStatusException $e) {
-    echo $e->type?->value;  // "rate_limit_error", "overloaded_error", etc.
-}
-```

skills/claude-api/php/claude-api/README.md

@@ -0,0 +1,174 @@
+# Claude API — PHP
+
+> **Note:** The PHP SDK is the official Anthropic SDK for PHP. A beta tool runner is available via `$client->beta->messages->toolRunner()`. Structured output helpers are supported via `StructuredOutputModel` classes. Agent SDK is not available. Bedrock, Vertex AI, and Foundry clients are supported.
+
+## Installation
+
+```bash
+composer require "anthropic-ai/sdk"
+```
+
+## Client Initialization
+
+```php
+use Anthropic\Client;
+
+// Using API key from environment variable
+$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
+```
+
+### Amazon Bedrock
+
+```php
+use Anthropic\Bedrock\MantleClient;
+
+// Messages-API Bedrock endpoint. Reads AWS credentials from env.
+$client = new MantleClient(awsRegion: 'us-east-1');
+```
+
+Model IDs on Bedrock take an `anthropic.` prefix — e.g. `model: 'anthropic.claude-opus-5'`.
+
+### Google Vertex AI
+
+```php
+use Anthropic\Vertex;
+
+// Constructor is private. Parameter is `location`, not `region`.
+$client = Vertex\Client::fromEnvironment(
+    location: 'us-east5',
+    projectId: 'my-project-id',
+);
+```
+
+### Anthropic Foundry
+
+```php
+use Anthropic\Foundry;
+
+// Constructor is private. baseUrl or resource is required.
+$client = Foundry\Client::withCredentials(
+    apiKey: getenv('ANTHROPIC_FOUNDRY_API_KEY'),
+    baseUrl: 'https://<resource>.services.ai.azure.com/anthropic/v1',
+);
+```
+
+---
+
+## Basic Message Request
+
+```php
+$message = $client->messages->create(
+    model: 'claude-opus-5',
+    maxTokens: 16000,
+    messages: [
+        ['role' => 'user', 'content' => 'What is the capital of France?'],
+    ],
+);
+
+// content is an array of polymorphic blocks (TextBlock, ToolUseBlock,
+// ThinkingBlock). Accessing ->text on content[0] without checking the block
+// type will throw if the first block is not a TextBlock (e.g., when extended
+// thinking is enabled and a ThinkingBlock comes first). Always guard:
+foreach ($message->content as $block) {
+    if ($block->type === 'text') {
+        echo $block->text;
+    }
+}
+```
+
+If you only want the first text block:
+
+```php
+foreach ($message->content as $block) {
+    if ($block->type === 'text') {
+        echo $block->text;
+        break;
+    }
+}
+```
+
+---
+
+## Extended Thinking
+
+**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think.
+
+```php
+use Anthropic\Messages\ThinkingBlock;
+
+$message = $client->messages->create(
+    model: 'claude-opus-5',
+    maxTokens: 16000,
+    thinking: ['type' => 'adaptive', 'display' => 'summarized'], // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7
+    messages: [
+        ['role' => 'user', 'content' => 'Solve: 27 * 453'],
+    ],
+);
+
+// ThinkingBlock(s) precede TextBlock in content
+foreach ($message->content as $block) {
+    if ($block instanceof ThinkingBlock) {
+        echo "Thinking:\n{$block->thinking}\n\n";
+        // $block->signature is an opaque string — preserve verbatim if
+        // passing thinking blocks back in multi-turn conversations
+    } elseif ($block->type === 'text') {
+        echo "Answer: {$block->text}\n";
+    }
+}
+```
+
+> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (above). `['type' => 'enabled', 'budgetTokens' => N]` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Claude Opus 5:** thinking is on by default — omitting `thinking:` runs adaptive (`['type' => 'adaptive']` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `['type' => 'disabled']` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400.
+> **Older models:** Use `thinking: ['type' => 'enabled', 'budgetTokens' => N]` (budget must be < `maxTokens`, min 1024).
+
+`$block->type === 'thinking'` also works for the check; `instanceof` narrows for PHPStan.
+
+---
+
+## Prompt Caching
+
+`system:` takes an array of text blocks; set `cacheControl` on the last block. Array-shape syntax (camelCase keys) is idiomatic. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
+
+```php
+$message = $client->messages->create(
+    model: 'claude-opus-5',
+    maxTokens: 16000,
+    system: [
+        ['type' => 'text', 'text' => $longSystemPrompt, 'cacheControl' => ['type' => 'ephemeral']],
+    ],
+    messages: [['role' => 'user', 'content' => 'Summarize the key points']],
+);
+```
+
+For 1-hour TTL: `'cacheControl' => ['type' => 'ephemeral', 'ttl' => '1h']`. There's also a top-level `cacheControl:` on `messages->create(...)` that auto-places on the last cacheable block.
+
+Verify hits via `$message->usage->cacheCreationInputTokens` / `$message->usage->cacheReadInputTokens`.
+
+---
+
+## Stop Details
+
+When `stopReason` is `'refusal'`, the response includes structured `stopDetails`:
+
+```php
+if ($message->stopReason === 'refusal' && $message->stopDetails !== null) {
+    echo "Category: " . $message->stopDetails->category . "\n";     // e.g. "cyber", "bio", "reasoning_extraction", "frontier_llm", or null — see docs for the full set
+    echo "Explanation: " . $message->stopDetails->explanation . "\n";
+}
+```
+
+**Refusal fallbacks (Claude Fable 5) — opt in by default.** Fallbacks are opt-in: without them a refused request simply stops. New `claude-fable-5` code should include the server-side `fallbacks` parameter (beta header `server-side-fallback-2026-06-01`, fallback model `claude-opus-4-8`, on the beta messages call) by default. The exact PHP binding (and the client-side middleware for providers without server-side support) is not documented here — WebFetch the PHP SDK repo's `examples/` from `shared/live-sources.md`; full semantics in `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason.
+
+---
+
+## Error Type
+
+`APIStatusException` exposes a `->type` property for programmatic error classification:
+
+```php
+try {
+    $client->messages->create(...);
+} catch (\Anthropic\Core\Exceptions\APIStatusException $e) {
+    echo $e->type?->value;  // "rate_limit_error", "overloaded_error", etc.
+}
+```

skills/claude-api/php/claude-api/batches.md

@@ -0,0 +1,15 @@
+# Message Batches — PHP
+
+## Message Batches API
+
+```php
+$batch = $client->messages->batches->create(requests: [
+    ['customId' => 'req-1', 'params' => ['model' => 'claude-opus-5', 'maxTokens' => 1024, 'messages' => [...]]],
+    ['customId' => 'req-2', 'params' => [...]],
+]);
+// Poll $client->messages->batches->retrieve($batch->id) until processingStatus === 'ended',
+// then iterate $client->messages->batches->results($batch->id).
+```
+
+---
+

skills/claude-api/php/claude-api/files-api.md

@@ -0,0 +1,11 @@
+# Files API — PHP
+
+## Files API
+
+```php
+$file = $client->beta->files->upload(
+    file: fopen('upload_me.txt', 'r'),
+    betas: ['files-api-2025-04-14'],
+);
+// Reference $file->id as a file content block on ->beta->messages->create().
+```

skills/claude-api/php/claude-api/streaming.md

@@ -0,0 +1,27 @@
+# Streaming — PHP
+
+## Streaming
+
+> **Requires SDK v0.5.0+.** v0.4.0 and earlier used a single `$params` array; calling with named parameters throws `Unknown named parameter $model`. Upgrade: `composer require "anthropic-ai/sdk:^0.7"`
+
+```php
+use Anthropic\Messages\RawContentBlockDeltaEvent;
+use Anthropic\Messages\TextDelta;
+
+$stream = $client->messages->createStream(
+    model: 'claude-opus-5',
+    maxTokens: 64000,
+    messages: [
+        ['role' => 'user', 'content' => 'Write a haiku'],
+    ],
+);
+
+foreach ($stream as $event) {
+    if ($event instanceof RawContentBlockDeltaEvent && $event->delta instanceof TextDelta) {
+        echo $event->delta->text;
+    }
+}
+```
+
+---
+

skills/claude-api/php/claude-api/tool-use.md

@@ -0,0 +1,253 @@
+# Tool Use — PHP
+
+For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
+
+## Tool Use
+
+### Tool Runner (Beta)
+
+**Beta:** The PHP SDK provides a tool runner via `$client->beta->messages->toolRunner()`. Define tools with `BetaRunnableTool` — a definition array plus a `run` closure:
+
+```php
+use Anthropic\Lib\Tools\BetaRunnableTool;
+
+$weatherTool = new BetaRunnableTool(
+    definition: [
+        'name' => 'get_weather',
+        'description' => 'Get the current weather for a location.',
+        'inputSchema' => [
+            'type' => 'object',
+            'properties' => [
+                'location' => ['type' => 'string', 'description' => 'City and state'],
+            ],
+            'required' => ['location'],
+        ],
+    ],
+    run: function (array $input): string {
+        return "The weather in {$input['location']} is sunny and 72°F.";
+    },
+);
+
+$runner = $client->beta->messages->toolRunner(
+    maxTokens: 16000,
+    messages: [['role' => 'user', 'content' => 'What is the weather in Paris?']],
+    model: 'claude-opus-5',
+    tools: [$weatherTool],
+);
+
+foreach ($runner as $message) {
+    foreach ($message->content as $block) {
+        if ($block->type === 'text') {
+            echo $block->text;
+        }
+    }
+}
+```
+
+### Manual Loop
+
+Tools are passed as arrays. **The SDK uses camelCase keys** (`inputSchema`, `toolUseID`, `stopReason`) and auto-maps to the API's snake_case on the wire — since v0.5.0. See [shared tool use concepts](../../shared/tool-use-concepts.md) for the loop pattern.
+
+```php
+use Anthropic\Messages\ToolUseBlock;
+
+$tools = [
+    [
+        'name' => 'get_weather',
+        'description' => 'Get the current weather in a given location',
+        'inputSchema' => [  // camelCase, not input_schema
+            'type' => 'object',
+            'properties' => [
+                'location' => ['type' => 'string', 'description' => 'City and state'],
+            ],
+            'required' => ['location'],
+        ],
+    ],
+];
+
+$messages = [['role' => 'user', 'content' => 'What is the weather in SF?']];
+
+$response = $client->messages->create(
+    model: 'claude-opus-5',
+    maxTokens: 16000,
+    tools: $tools,
+    messages: $messages,
+);
+
+while ($response->stopReason === 'tool_use') {  // camelCase property
+    $toolResults = [];
+    foreach ($response->content as $block) {
+        if ($block instanceof ToolUseBlock) {
+            // $block->name  : string               — tool name to dispatch on
+            // $block->input : array<string,mixed>  — parsed JSON input
+            // $block->id    : string               — pass back as toolUseID
+            $result = executeYourTool($block->name, $block->input);
+            $toolResults[] = [
+                'type' => 'tool_result',
+                'toolUseID' => $block->id,  // camelCase, not tool_use_id
+                'content' => $result,
+            ];
+        }
+    }
+
+    // Append assistant turn + user turn with tool results
+    $messages[] = ['role' => 'assistant', 'content' => $response->content];
+    $messages[] = ['role' => 'user', 'content' => $toolResults];
+
+    $response = $client->messages->create(
+        model: 'claude-opus-5',
+        maxTokens: 16000,
+        tools: $tools,
+        messages: $messages,
+    );
+}
+
+// Final text response
+foreach ($response->content as $block) {
+    if ($block->type === 'text') {
+        echo $block->text;
+    }
+}
+```
+
+`$block->type === 'tool_use'` also works; `instanceof ToolUseBlock` narrows for PHPStan.
+
+
+---
+
+## Structured Outputs
+
+### Using StructuredOutputModel (Recommended)
+
+Define a PHP class implementing `StructuredOutputModel` and pass it as `outputConfig`:
+
+```php
+use Anthropic\Lib\Contracts\StructuredOutputModel;
+use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
+use Anthropic\Lib\Attributes\Constrained;
+
+class Person implements StructuredOutputModel
+{
+    use StructuredOutputModelTrait;
+
+    #[Constrained(description: 'Full name')]
+    public string $name;
+
+    public int $age;
+
+    public ?string $email = null;  // nullable = optional field
+}
+
+$message = $client->messages->create(
+    model: 'claude-opus-5',
+    maxTokens: 16000,
+    messages: [['role' => 'user', 'content' => 'Generate a profile for Alice, age 30']],
+    outputConfig: ['format' => Person::class],
+);
+
+$person = $message->parsedOutput();  // Person instance
+echo $person->name;
+```
+
+Types are inferred from PHP type hints. Use `#[Constrained(description: '...')]` to add descriptions. Nullable properties (`?string`) become optional fields.
+
+### Raw Schema
+
+```php
+$message = $client->messages->create(
+    model: 'claude-opus-5',
+    maxTokens: 16000,
+    messages: [['role' => 'user', 'content' => 'Extract: John (john@co.com), Enterprise plan']],
+    outputConfig: [
+        'format' => [
+            'type' => 'json_schema',
+            'schema' => [
+                'type' => 'object',
+                'properties' => [
+                    'name' => ['type' => 'string'],
+                    'email' => ['type' => 'string'],
+                    'plan' => ['type' => 'string'],
+                ],
+                'required' => ['name', 'email', 'plan'],
+                'additionalProperties' => false,
+            ],
+        ],
+    ],
+);
+
+// First text block contains valid JSON
+foreach ($message->content as $block) {
+    if ($block->type === 'text') {
+        $data = json_decode($block->text, true);
+        break;
+    }
+}
+```
+
+---
+
+## Beta Features & Anthropic-Defined Tools
+
+**`betas:` is NOT a param on `$client->messages->create()`** — it only exists on the beta namespace. Use it for features that need an explicit opt-in header:
+
+```php
+use Anthropic\Beta\Messages\BetaRequestMCPServerURLDefinition;
+
+$response = $client->beta->messages->create(
+    model: 'claude-opus-5',
+    maxTokens: 16000,
+    mcpServers: [
+        BetaRequestMCPServerURLDefinition::with(
+            name: 'my-server',
+            url: 'https://example.com/mcp',
+        ),
+    ],
+    betas: ['mcp-client-2025-11-20'],  // only valid on ->beta->messages
+    messages: [['role' => 'user', 'content' => 'Use the MCP tools']],
+);
+```
+
+### Task budgets
+
+```php
+$response = $client->beta->messages->create(
+    model: 'claude-opus-5',
+    maxTokens: 16000,
+    outputConfig: ['taskBudget' => ['type' => 'tokens', 'total' => 64000]],
+    tools: [...],
+    messages: [...],
+    betas: ['task-budgets-2026-03-13'],
+);
+```
+
+### Cache diagnostics
+
+Pass the previous response's `id` on the next request; print the `diagnostics` object on the response:
+
+```php
+$r2 = $client->beta->messages->create(
+    model: 'claude-opus-5', maxTokens: 1024,
+    diagnostics: ['previousMessageId' => $r1->id],
+    betas: ['cache-diagnosis-2026-04-07'],
+    messages: [...],
+);
+```
+
+**Anthropic-defined tools** (bash, web_search, text_editor, code_execution) are GA and work on both paths. Of these, web_search and code_execution are server-executed; bash and text_editor are client-executed (you handle the `tool_use` locally) — `Anthropic\Messages\ToolBash20250124` / `WebSearchTool20260209` / `ToolTextEditor20250728` / `CodeExecutionTool20260120` for non-beta, `Anthropic\Beta\Messages\BetaToolBash20250124` / `BetaWebSearchTool20260209` / `BetaToolTextEditor20250728` / `BetaCodeExecutionTool20260120` for beta. No `betas:` header needed for these.
+
+### Tool search (non-beta, server-side)
+
+```php
+tools: [
+    ['type' => 'tool_search_tool_regex_20251119', 'name' => 'tool_search_tool_regex'],
+    ['name' => 'get_weather', 'description' => '...', 'inputSchema' => [...], 'deferLoading' => true],
+    // ... other user tools with 'deferLoading' => true
+],
+```
+
+### Memory tool (non-beta, client-executed)
+
+Declare `['type' => 'memory_20250818', 'name' => 'memory']`. Handle the `tool_use` by reading/writing files under a fixed `/memories` directory. **Validate every model-supplied path**: resolve to its canonical form and verify it remains within the memory directory; reject traversal (`..`, symlinks) — see `shared/tool-use-concepts.md` § Client-Side Tools.
+
+---
+

skills/claude-api/php/managed-agents/README.md

@@ -2,12 +2,12 @@
 
 > **Bindings not shown here:** This README covers the most common managed-agents flows for PHP. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the PHP SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
 
-> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `$client->beta->agents->create` and pass it to every subsequent `->sessions->create`; do not call `agents->create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
+> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `$client->beta->agents->create` and pass it to every subsequent `->sessions->create`; do not call `agents->create` in the request path. **Recommended:** define agents and environments as version-controlled YAML applied with the `ant` CLI — see `shared/anthropic-cli.md` (its live-docs URL is in `shared/live-sources.md`). The CLI owns the control plane (create/update); your code owns the data plane (sessions with the stored ID). The examples below show in-code creation for when you must provision programmatically; in production the create call belongs in setup, not in the request path.
 
 ## Installation
 
 ```bash
-composer require "anthropic-ai/sdk"
+composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7"
 ```
 
 ## Client Initialization
@@ -48,7 +48,7 @@ use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
 // 1. Create the agent (reusable, versioned)
 $agent = $client->beta->agents->create(
     name: 'Coding Assistant',
-    model: 'claude-opus-4-8',
+    model: 'claude-opus-5',
     system: 'You are a helpful coding assistant.',
     tools: [
         BetaManagedAgentsAgentToolset20260401Params::with(
@@ -64,6 +64,7 @@ $session = $client->beta->sessions->create(
     title: 'Quickstart session',
 );
 echo "Session ID: {$session->id}\n";
+echo "Trace: https://platform.claude.com/workspaces/default/sessions/{$session->id}\n"; // swap 'default' for your workspace ID if the API key is not in the Default workspace
 ```
 
 ### Updating an Agent
@@ -263,7 +264,14 @@ $client->beta->sessions->resources->delete($resource->id, sessionID: $session->i
 
 ## List and Download Session Files
 
-> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for PHP in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic-ai/sdk` PHP repository for the file list/download bindings.
+```php
+$files = $client->beta->files->list(
+    scopeID: 'sesn_abc123',
+    betas: ['managed-agents-2026-04-01'],
+);
+$content = $client->beta->files->download($files->data[0]->id);
+file_put_contents('output.txt', $content);
+```
 
 ---
 
@@ -293,15 +301,15 @@ $client->beta->sessions->delete($session->id);
 ```php
 use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
 use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetParams;
-use Anthropic\Beta\Agents\BetaManagedAgentsUrlmcpServerParams;
+use Anthropic\Beta\Agents\BetaManagedAgentsURLMCPServerParams;
 use Anthropic\Beta\Sessions\BetaManagedAgentsAgentParams;
 
 // Agent declares MCP server (no auth here — auth goes in a vault)
 $agent = $client->beta->agents->create(
     name: 'GitHub Assistant',
-    model: 'claude-opus-4-8',
+    model: 'claude-opus-5',
     mcpServers: [
-        BetaManagedAgentsUrlmcpServerParams::with(
+        BetaManagedAgentsURLMCPServerParams::with(
             type: 'url',
             name: 'github',
             url: 'https://api.githubcopilot.com/mcp/',
@@ -395,8 +403,8 @@ $session = $client->beta->sessions->create(
         [
             'type' => 'github_repository',
             'url' => 'https://github.com/org/repo',
-            'mountPath' => '/workspace/repo',
-            'authorizationToken' => 'ghp_your_github_token',
+            'mount_path' => '/workspace/repo',
+            'authorization_token' => 'ghp_your_github_token',
         ],
     ],
 );
@@ -409,14 +417,14 @@ $resources = [
     [
         'type' => 'github_repository',
         'url' => 'https://github.com/org/frontend',
-        'mountPath' => '/workspace/frontend',
-        'authorizationToken' => 'ghp_your_github_token',
+        'mount_path' => '/workspace/frontend',
+        'authorization_token' => 'ghp_your_github_token',
     ],
     [
         'type' => 'github_repository',
         'url' => 'https://github.com/org/backend',
-        'mountPath' => '/workspace/backend',
-        'authorizationToken' => 'ghp_your_github_token',
+        'mount_path' => '/workspace/backend',
+        'authorization_token' => 'ghp_your_github_token',
     ],
 ];
 ```

skills/claude-api/python/claude-api/README.md

@@ -33,7 +33,7 @@ Use `with_options()` to override client settings for a single call without mutat
 
 ```python
 client.with_options(timeout=5.0, max_retries=5).messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=1024,
     messages=[{"role": "user", "content": "Hello"}],
 )
@@ -90,7 +90,7 @@ Set `ANTHROPIC_LOG=debug` (or `info`) to enable SDK logging via the standard `lo
 
 ```python
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[
         {"role": "user", "content": "What is the capital of France?"}
@@ -109,16 +109,16 @@ for block in response.content:
 
 ```python
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     system="You are a helpful coding assistant. Always provide examples in Python.",
     messages=[{"role": "user", "content": "How do I read a JSON file?"}]
 )
 ```
 
-### Mid-conversation system messages (beta, model-gated)
+### Mid-conversation system messages (model-gated)
 
-For operator instructions that arrive mid-conversation (mode switches, injected state), append `{"role": "system", ...}` to `messages` instead of editing top-level `system` — this preserves the cached prefix and carries operator authority. Must follow a user message; cannot be `messages[0]`. Unsupported models return a 400 (`role 'system' is not supported on this model`). See `shared/prompt-caching.md` for when to use this vs. top-level `system`.
+For operator instructions that arrive mid-conversation (mode switches, injected state), append `{"role": "system", ...}` to `messages` instead of editing top-level `system` — this preserves the cached prefix and carries operator authority. Must follow a user message (or an `assistant` message ending in server-tool use), and must be either the last entry in `messages` or be followed by an `assistant` turn; cannot be `messages[0]`. Unsupported models return a 400 (`role 'system' is not supported on this model`). See `shared/prompt-caching.md` for when to use this vs. top-level `system`.
 
 ```python
 response = client.messages.create(
@@ -129,8 +129,7 @@ response = client.messages.create(
         {"role": "user", "content": user_message},
         {"role": "system", "content": "Terse mode enabled — keep responses under 40 words."},
     ],
-    extra_headers={"anthropic-beta": "mid-conversation-system-2026-04-07"},
-)
+)  # No beta header needed — use regular client.messages.create
 ```
 
 ---
@@ -146,7 +145,7 @@ with open("image.png", "rb") as f:
     image_data = base64.standard_b64encode(f.read()).decode("utf-8")
 
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{
         "role": "user",
@@ -169,7 +168,7 @@ response = client.messages.create(
 
 ```python
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{
         "role": "user",
@@ -199,7 +198,7 @@ Use top-level `cache_control` to automatically cache the last cacheable block in
 
 ```python
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     cache_control={"type": "ephemeral"},  # auto-caches the last cacheable block
     system="You are an expert on this large document...",
@@ -213,7 +212,7 @@ For fine-grained control, add `cache_control` to specific content blocks:
 
 ```python
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     system=[{
         "type": "text",
@@ -225,7 +224,7 @@ response = client.messages.create(
 
 # With explicit TTL (time-to-live)
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     system=[{
         "type": "text",
@@ -250,16 +249,17 @@ If `cache_read_input_tokens` is zero across repeated identical-prefix requests,
 
 ## Extended Thinking
 
-> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Claude Opus 5:** thinking is on by default — omitting `thinking` runs adaptive (`{"type": "adaptive"}` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `{"type": "disabled"}` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400.
 > **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024).
 
 ```python
-# Fable 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
+# Fable 5 / Claude Opus 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
-    thinking={"type": "adaptive"},
-    output_config={"effort": "high"},  # low | medium | high | max
+    thinking={"type": "adaptive", "display": "summarized"},  # display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7
+    output_config={"effort": "high"},  # low | medium | high | xhigh | max
     messages=[{"role": "user", "content": "Solve this step by step..."}]
 )
 
@@ -317,7 +317,7 @@ To access raw headers or other response metadata, use `.with_raw_response`:
 
 ```python
 raw = client.messages.with_raw_response.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=1024,
     messages=[{"role": "user", "content": "Hello"}],
 )
@@ -363,7 +363,7 @@ class ConversationManager:
 # Usage
 conversation = ConversationManager(
     client=anthropic.Anthropic(),
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     system="You are a helpful assistant."
 )
 
@@ -375,13 +375,13 @@ response2 = conversation.send("What's my name?")  # Claude remembers "Alice"
 
 - Consecutive same-role messages are allowed — the API combines them into a single turn
 - First message must be `user`
-- `role: "system"` messages are allowed mid-conversation under the `mid-conversation-system-2026-04-07` beta on supporting models — see § Mid-conversation system messages above
+- `role: "system"` messages are allowed mid-conversation on supporting models (no beta header needed) — see § Mid-conversation system messages above
 
 ---
 
 ### Compaction (long conversations)
 
-> **Beta, Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text.
+> **Beta, Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text.
 
 ```python
 import anthropic
@@ -394,7 +394,7 @@ def chat(user_message: str) -> str:
 
     response = client.beta.messages.create(
         betas=["compact-2026-01-12"],
-        model="claude-opus-4-8",
+        model="claude-opus-5",
         max_tokens=16000,
         messages=messages,
         context_management={
@@ -434,10 +434,39 @@ When `stop_reason` is `"refusal"`, the response includes a `stop_details` object
 
 ```python
 if response.stop_reason == "refusal" and response.stop_details:
-    print(f"Category: {response.stop_details.category}")   # "cyber" | "bio" | None
+    print(f"Category: {response.stop_details.category}")   # e.g. "cyber", "bio", "reasoning_extraction", "frontier_llm", or None — see docs for the full set
     print(f"Explanation: {response.stop_details.explanation}")
 ```
 
+### Refusal Fallbacks (Claude Fable 5) — opt in by default
+
+Fallbacks are **opt-in**: without them a refused request simply stops. Include the server-side `fallbacks` parameter in `claude-fable-5` code by default — on a policy decline the API re-runs the same request on the fallback model inside the same call. A decline before any output isn't billed (a mid-stream decline bills the streamed partial); the rescue bills at the fallback model's own rates, with cache repricing applied automatically.
+
+```python
+response = client.beta.messages.create(
+    model="claude-fable-5",
+    max_tokens=16000,
+    betas=["server-side-fallback-2026-06-01"],
+    fallbacks=[{"model": "claude-opus-4-8"}],
+    messages=[{"role": "user", "content": "..."}],
+)
+
+# Switch points: one fallback block per model that ran and declined this turn
+for block in response.content:
+    if block.type == "fallback":
+        print(f"{block.from_.model} declined; {block.to.model} continued")
+
+# Served-by signal — covers sticky turns, which carry no fallback block.
+# Pair with stop_reason: the fallback model can itself refuse.
+fallback_ran = any(
+    entry.type == "fallback_message" for entry in response.usage.iterations or []
+)
+if fallback_ran and response.stop_reason != "refusal":
+    print(f"Served by {response.model}")
+```
+
+A `stop_reason: "refusal"` on the final response means the whole chain refused. The header must be exactly `server-side-fallback-2026-06-01` **for this array form**; the newer `fallbacks: "default"` scalar form uses `server-side-fallback-2026-07-01` instead (see `shared/model-migration.md` → Migrating to Claude Opus 5 → New API features), and pairing either header with the other form returns a 400. The parameter is rejected on the Batches API and unavailable on Amazon Bedrock, Vertex AI, and Microsoft Foundry — register the client-side `BetaRefusalFallbackMiddleware` on the client there instead. Full semantics (sticky routing, billing, streaming, echoing fallback turns back): `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason.
+
 ---
 
 ## Cost Optimization Strategies
@@ -447,7 +476,7 @@ if response.stop_reason == "refusal" and response.stop_details:
 ```python
 # Automatic caching (simplest — caches the last cacheable block)
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     cache_control={"type": "ephemeral"},
     system=large_document_text,  # e.g., 50KB of context
@@ -463,14 +492,14 @@ response = client.messages.create(
 ```python
 # Default to Opus for most tasks
 response = client.messages.create(
-    model="claude-opus-4-8",  # $5.00/$25.00 per 1M tokens
+    model="claude-opus-5",  # $5.00/$25.00 per 1M tokens
     max_tokens=16000,
     messages=[{"role": "user", "content": "Explain quantum computing"}]
 )
 
 # Use Sonnet for high-volume production workloads
 standard_response = client.messages.create(
-    model="claude-sonnet-4-6",  # $3.00/$15.00 per 1M tokens
+    model="claude-sonnet-5",  # $3.00/$15.00 per 1M tokens
     max_tokens=16000,
     messages=[{"role": "user", "content": "Summarize this document"}]
 )
@@ -487,7 +516,7 @@ simple_response = client.messages.create(
 
 ```python
 count_response = client.messages.count_tokens(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     messages=messages,
     system=system
 )

skills/claude-api/python/claude-api/batches.md

@@ -26,7 +26,7 @@ message_batch = client.messages.batches.create(
         Request(
             custom_id="request-1",
             params=MessageCreateParamsNonStreaming(
-                model="claude-opus-4-8",
+                model="claude-opus-5",
                 max_tokens=16000,
                 messages=[{"role": "user", "content": "Summarize climate change impacts"}]
             )
@@ -34,7 +34,7 @@ message_batch = client.messages.batches.create(
         Request(
             custom_id="request-2",
             params=MessageCreateParamsNonStreaming(
-                model="claude-opus-4-8",
+                model="claude-opus-5",
                 max_tokens=16000,
                 messages=[{"role": "user", "content": "Explain quantum computing basics"}]
             )
@@ -130,7 +130,7 @@ message_batch = client.messages.batches.create(
         Request(
             custom_id=f"analysis-{i}",
             params=MessageCreateParamsNonStreaming(
-                model="claude-opus-4-8",
+                model="claude-opus-5",
                 max_tokens=16000,
                 system=shared_system,
                 messages=[{"role": "user", "content": question}]

skills/claude-api/python/claude-api/files-api.md

@@ -40,7 +40,7 @@ print(f"Size: {uploaded.size_bytes} bytes")
 
 ```python
 response = client.beta.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{
         "role": "user",
@@ -69,7 +69,7 @@ image_file = client.beta.files.upload(
 )
 
 response = client.beta.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{
         "role": "user",
@@ -147,7 +147,7 @@ questions = [
 
 for question in questions:
     response = client.beta.messages.create(
-        model="claude-opus-4-8",
+        model="claude-opus-5",
         max_tokens=16000,
         messages=[{
             "role": "user",

skills/claude-api/python/claude-api/streaming.md

@@ -4,7 +4,7 @@
 
 ```python
 with client.messages.stream(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=64000,
     messages=[{"role": "user", "content": "Write a story"}]
 ) as stream:
@@ -16,7 +16,7 @@ with client.messages.stream(
 
 ```python
 async with async_client.messages.stream(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=64000,
     messages=[{"role": "user", "content": "Write a story"}]
 ) as stream:
@@ -30,7 +30,7 @@ async with async_client.messages.stream(
 
 ```python
 for event in client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=64000,
     messages=[{"role": "user", "content": "Write a story"}],
     stream=True,
@@ -46,13 +46,13 @@ No final-message accumulation is done for you in this form.
 
 Claude may return text, thinking blocks, or tool use. Handle each appropriately:
 
-> **Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead.
+> **Fable 5 / Claude Opus 5 / Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On Claude Opus 5 adaptive is also what you get by omitting `thinking` entirely. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead.
 
 ```python
 with client.messages.stream(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=64000,
-    thinking={"type": "adaptive"},
+    thinking={"type": "adaptive", "display": "summarized"},  # display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7
     messages=[{"role": "user", "content": "Analyze this problem"}]
 ) as stream:
     for event in stream:
@@ -73,11 +73,11 @@ with client.messages.stream(
 
 ## Streaming with Tool Use
 
-The Python tool runner currently returns complete messages. Use streaming for individual API calls within a manual loop if you need per-token streaming with tools:
+The Python tool runner supports streaming: pass `stream=True` to `client.beta.messages.tool_runner(...)` and each iteration yields a stream you consume event-by-event, with `get_final_message()` for the accumulated message per turn (see `shared/tool-use-concepts.md` → Tool Runner vs Manual Loop). Use the manual-loop pattern below only when you're not using the tool runner and need per-token streaming with tools:
 
 ```python
 with client.messages.stream(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=64000,
     tools=tools,
     messages=messages
@@ -95,7 +95,7 @@ with client.messages.stream(
 
 ```python
 with client.messages.stream(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=64000,
     messages=[{"role": "user", "content": "Hello"}]
 ) as stream:
@@ -142,7 +142,7 @@ def stream_with_progress(client, **kwargs):
 ```python
 try:
     with client.messages.stream(
-        model="claude-opus-4-8",
+        model="claude-opus-5",
         max_tokens=64000,
         messages=[{"role": "user", "content": "Write a story"}]
     ) as stream:

skills/claude-api/python/claude-api/tool-use.md

@@ -27,7 +27,7 @@ def get_weather(location: str, unit: str = "celsius") -> str:
 
 # The tool runner handles the agentic loop automatically
 runner = client.beta.messages.tool_runner(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     tools=[get_weather],
     messages=[{"role": "user", "content": "What's the weather in Paris?"}],
@@ -47,6 +47,43 @@ For async usage, use `@beta_async_tool` with `async def` functions.
 - Tool schemas are generated automatically from function signatures
 - Iteration stops automatically when Claude has no more tool calls
 
+### Server tools with the tool runner
+
+The runner's `tools` list accepts raw server-tool definitions (`web_search_20260209`, `web_fetch_20260209`, code execution) alongside decorated tools — pass the literal tool dict; server tools run on Anthropic's servers, so there is no function to implement.
+
+**Caution — the runner does not auto-resume `pause_turn` (as of `anthropic` 0.116.0).** A long-running server-tool turn can stop with `stop_reason: "pause_turn"`. The runner only continues after a client tool produces a result, so a paused turn ends the loop and is returned as the final message — no error, no warning, just a silently truncated answer. Unlike the TypeScript runner, the Python runner cannot be resumed mid-loop: it exits unconditionally when no client tool ran, and `runner.append_messages(...)` does not prevent the exit. To handle `pause_turn`, mirror the conversation history as you iterate, then restart the runner with the paused turn appended:
+
+```python
+messages = [{"role": "user", "content": user_input}]
+
+max_restarts = 5  # cap pause_turn restarts, mirroring max_continuations advice
+restarts = 0
+while True:
+    runner = client.beta.messages.tool_runner(
+        model="claude-opus-5",
+        max_tokens=16000,
+        tools=tools,  # may mix @beta_tool functions and server-tool definitions
+        messages=messages,
+    )
+    last = None
+    for message in runner:
+        last = message
+        # Mirror the history — the runner keeps its own copy and does not expose it
+        messages.append({"role": "assistant", "content": message.content})
+        tool_response = runner.generate_tool_call_response()  # cached; tools still run once
+        if tool_response is not None:
+            messages.append(tool_response)
+    if last is None or last.stop_reason != "pause_turn":
+        break
+    restarts += 1
+    if restarts > max_restarts:
+        raise RuntimeError("giving up: turn still paused after max_restarts")
+    # Paused mid-turn: `messages` already ends with the paused assistant
+    # turn, so the next runner resumes it
+```
+
+Alternatively, use the manual loop below, which handles `pause_turn` explicitly.
+
 ---
 
 ## MCP Tool Conversion Helpers
@@ -72,7 +109,7 @@ async with stdio_client(StdioServerParameters(command="mcp-server")) as (read, w
         tools_result = await mcp_client.list_tools()
         # tool_runner is sync — returns the runner, not a coroutine
         runner = client.beta.messages.tool_runner(
-            model="claude-opus-4-8",
+            model="claude-opus-5",
             max_tokens=16000,
             messages=[{"role": "user", "content": "Use the available tools"}],
             tools=[async_mcp_tool(t, mcp_client) for t in tools_result.tools],
@@ -90,7 +127,7 @@ from anthropic.lib.tools.mcp import mcp_message
 
 prompt = await mcp_client.get_prompt(name="my-prompt")
 response = await client.beta.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[mcp_message(m) for m in prompt.messages],
 )
@@ -103,7 +140,7 @@ from anthropic.lib.tools.mcp import mcp_resource_to_content
 
 resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
 response = await client.beta.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{
         "role": "user",
@@ -130,7 +167,9 @@ Conversion functions raise `UnsupportedMCPValueError` if an MCP value cannot be
 
 ## Manual Agentic Loop
 
-Use this when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval):
+Prefer the tool runner above. Drop to a manual loop only when you need control the runner does not expose (e.g., a custom transport, request shapes the SDK cannot build, or avoiding a beta dependency — the runner is beta). Human-in-the-loop approval does *not* require a manual loop — gate inside the tool function (return a "user declined" result) or inspect pending `tool_use` blocks in the `for message in runner:` body and call `runner.set_messages_params()`.
+
+If you do need a manual loop:
 
 ```python
 import anthropic
@@ -142,7 +181,7 @@ messages = [{"role": "user", "content": user_input}]
 # Agentic loop: keep going until Claude stops calling tools
 while True:
     response = client.messages.create(
-        model="claude-opus-4-8",
+        model="claude-opus-5",
         max_tokens=16000,
         tools=tools,
         messages=messages
@@ -189,7 +228,7 @@ final_text = next(b.text for b in response.content if b.type == "text")
 
 ```python
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     tools=tools,
     messages=[{"role": "user", "content": "What's the weather in Paris?"}]
@@ -204,7 +243,7 @@ for block in response.content:
         result = execute_tool(tool_name, tool_input)
 
         followup = client.messages.create(
-            model="claude-opus-4-8",
+            model="claude-opus-5",
             max_tokens=16000,
             tools=tools,
             messages=[
@@ -241,7 +280,7 @@ for block in response.content:
 # Send all results back at once
 if tool_results:
     followup = client.messages.create(
-        model="claude-opus-4-8",
+        model="claude-opus-5",
         max_tokens=16000,
         tools=tools,
         messages=[
@@ -271,7 +310,7 @@ tool_result = {
 
 ```python
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     tools=tools,
     tool_choice={"type": "tool", "name": "get_weather"},  # Force specific tool
@@ -291,7 +330,7 @@ import anthropic
 client = anthropic.Anthropic()
 
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{
         "role": "user",
@@ -319,7 +358,7 @@ uploaded = client.beta.files.upload(file=open("sales_data.csv", "rb"))
 # 2. Pass to code execution via container_upload block
 # Code execution is GA; Files API is still beta (pass via extra_headers)
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     extra_headers={"anthropic-beta": "files-api-2025-04-14"},
     messages=[{
@@ -364,7 +403,7 @@ for block in response.content:
 ```python
 # First request: set up environment
 response1 = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{"role": "user", "content": "Install tabulate and create data.json with sample data"}],
     tools=[{"type": "code_execution_20260120", "name": "code_execution"}]
@@ -376,7 +415,7 @@ container_id = response1.container.id
 # Second request: reuse the same container
 response2 = client.messages.create(
     container=container_id,
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{"role": "user", "content": "Read data.json and display as a formatted table"}],
     tools=[{"type": "code_execution_20260120", "name": "code_execution"}]
@@ -416,7 +455,7 @@ import anthropic
 client = anthropic.Anthropic()
 
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{"role": "user", "content": "Remember that my preferred language is Python."}],
     tools=[{"type": "memory_20250818", "name": "memory"}],
@@ -442,7 +481,7 @@ memory = MyMemoryTool()
 
 # Use with tool runner
 runner = client.beta.messages.tool_runner(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     tools=[memory],
     messages=[{"role": "user", "content": "Remember my preferences"}],
@@ -477,7 +516,7 @@ class ContactInfo(BaseModel):
 client = anthropic.Anthropic()
 
 response = client.messages.parse(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{
         "role": "user",
@@ -496,7 +535,7 @@ print(contact.interests)      # ["API", "SDKs"]
 
 ```python
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{
         "role": "user",
@@ -530,7 +569,7 @@ data = json.loads(text)
 
 ```python
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{"role": "user", "content": "Book a flight to Tokyo for 2 passengers on March 15"}],
     tools=[{
@@ -555,7 +594,7 @@ response = client.messages.create(
 
 ```python
 response = client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=16000,
     messages=[{"role": "user", "content": "Plan a trip to Paris next month"}],
     output_config={

skills/claude-api/python/managed-agents/README.md

@@ -2,7 +2,7 @@
 
 > **Bindings not shown here:** This README covers the most common managed-agents flows for Python. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Python SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
 
-> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
+> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. **Recommended:** define agents and environments as version-controlled YAML applied with the `ant` CLI — see `shared/anthropic-cli.md` (its live-docs URL is in `shared/live-sources.md`). The CLI owns the control plane (create/update); your code owns the data plane (sessions with the stored ID). The examples below show in-code creation for when you must provision programmatically; in production the create call belongs in setup, not in the request path.
 
 ## Installation
 
@@ -51,7 +51,7 @@ print(environment.id)  # env_...
 # 1. Create the agent (reusable, versioned)
 agent = client.beta.agents.create(
     name="Coding Assistant",
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}],
 )
 
@@ -61,6 +61,7 @@ session = client.beta.sessions.create(
     environment_id=environment.id,
 )
 print(session.id, session.status)
+print(f"Trace: https://platform.claude.com/workspaces/default/sessions/{session.id}")  # swap 'default' for your workspace ID if the API key is not in the Default workspace
 ```
 
 ### With system prompt and custom tools
@@ -70,7 +71,7 @@ import os
 
 agent = client.beta.agents.create(
     name="Code Reviewer",
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     system="You are a senior code reviewer.",
     tools=[
         {"type": "agent_toolset_20260401"},
@@ -313,7 +314,7 @@ client.beta.sessions.archive(session_id="sesn_011CZxAbc123Def456")
 # Agent declares MCP server (no auth here — auth goes in a vault)
 agent = client.beta.agents.create(
     name="MCP Agent",
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     mcp_servers=[
         {"type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse"},
     ],

skills/claude-api/ruby/claude-api/README.md

@@ -26,7 +26,7 @@ client = Anthropic::Client.new(api_key: "your-api-key")
 
 ```ruby
 message = client.messages.create(
-  model: :"claude-opus-4-8",
+  model: :"claude-opus-5",
   max_tokens: 16000,
   messages: [
     { role: "user", content: "What is the capital of France?" }
@@ -42,55 +42,28 @@ end
 
 ---
 
-## Streaming
+## Extended Thinking
+
+> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Claude Opus 5:** thinking is on by default — omitting `thinking:` runs adaptive (`{ type: "adaptive" }` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `{ type: "disabled" }` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400.
+> **Older models:** Use `thinking: { type: "enabled", budget_tokens: N }` (must be < `max_tokens`, min 1024).
 
 ```ruby
-stream = client.messages.stream(
-  model: :"claude-opus-4-8",
-  max_tokens: 64000,
-  messages: [{ role: "user", content: "Write a haiku" }]
+message = client.messages.create(
+  model: :"claude-opus-5",
+  max_tokens: 16000,
+  thinking: { type: "adaptive" },
+  messages: [{ role: "user", content: "Solve: 27 * 453" }]
 )
 
-stream.text.each { |text| print(text) }
-```
-
----
-
-## Tool Use
-
-The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution.
-
-### Tool Runner (Beta)
-
-```ruby
-class GetWeatherInput < Anthropic::BaseModel
-  required :location, String, doc: "City and state, e.g. San Francisco, CA"
-end
-
-class GetWeather < Anthropic::BaseTool
-  doc "Get the current weather for a location"
-
-  input_schema GetWeatherInput
-
-  def call(input)
-    "The weather in #{input.location} is sunny and 72°F."
+message.content.each do |block|
+  case block.type
+  when :thinking then puts "Thinking: #{block.thinking}"
+  when :text then puts "Response: #{block.text}"
   end
 end
-
-client.beta.messages.tool_runner(
-  model: :"claude-opus-4-8",
-  max_tokens: 16000,
-  tools: [GetWeather.new],
-  messages: [{ role: "user", content: "What's the weather in San Francisco?" }]
-).each_message do |message|
-  puts message.content
-end
 ```
 
-### Manual Loop
-
-See the [shared tool use concepts](../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern.
-
 ---
 
 ## Prompt Caching
@@ -99,7 +72,7 @@ See the [shared tool use concepts](../shared/tool-use-concepts.md) for the tool
 
 ```ruby
 message = client.messages.create(
-  model: :"claude-opus-4-8",
+  model: :"claude-opus-5",
   max_tokens: 16000,
   system_: [
     { type: "text", text: long_system_prompt, cache_control: { type: "ephemeral" } }
@@ -120,11 +93,32 @@ When `stop_reason` is `:refusal`, the response includes structured `stop_details
 
 ```ruby
 if message.stop_reason == :refusal && message.stop_details
-  puts "Category: #{message.stop_details.category}"     # :cyber, :bio, or nil
+  puts "Category: #{message.stop_details.category}"     # e.g. :cyber, :bio, :reasoning_extraction, :frontier_llm, or nil — see docs for the full set
   puts "Explanation: #{message.stop_details.explanation}"
 end
 ```
 
+**Refusal fallbacks (Claude Fable 5) — opt in by default.** Fallbacks are opt-in: without them a refused request simply stops. New `claude-fable-5` code should include the server-side `fallbacks` parameter (beta header `server-side-fallback-2026-06-01`, `fallbacks: [{model: "claude-opus-4-8"}]` on the beta messages call) by default. The exact Ruby binding (and the client-side middleware for providers without server-side support) is not documented here — WebFetch the Ruby SDK repo's `examples/` from `shared/live-sources.md`; full semantics in `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason.
+
+---
+
+## Beta Features
+
+`betas:` is only valid on `client.beta.messages.create`, not the non-beta path.
+
+### Task budgets
+
+```ruby
+response = client.beta.messages.create(
+  model: :"claude-opus-5",
+  max_tokens: 16000,
+  output_config: { task_budget: { type: :tokens, total: 64_000 } },
+  tools: [...],
+  messages: [...],
+  betas: ["task-budgets-2026-03-13"]
+)
+```
+
 ---
 
 ## Error Type
@@ -134,7 +128,7 @@ end
 ```ruby
 begin
   client.messages.create(...)
-rescue Anthropic::APIStatusError => e
+rescue Anthropic::Errors::APIStatusError => e
   puts e.type  # :rate_limit_error, :overloaded_error, etc.
 end
 ```

skills/claude-api/ruby/claude-api/streaming.md

@@ -0,0 +1,16 @@
+# Streaming — Ruby
+
+## Streaming
+
+```ruby
+stream = client.messages.stream(
+  model: :"claude-opus-5",
+  max_tokens: 64000,
+  messages: [{ role: "user", content: "Write a haiku" }]
+)
+
+stream.text.each { |text| print(text) }
+```
+
+---
+

skills/claude-api/ruby/claude-api/tool-use.md

@@ -0,0 +1,41 @@
+# Tool Use — Ruby
+
+For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
+
+## Tool Use
+
+The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution.
+
+### Tool Runner (Beta)
+
+```ruby
+class GetWeatherInput < Anthropic::BaseModel
+  required :location, String, doc: "City and state, e.g. San Francisco, CA"
+end
+
+class GetWeather < Anthropic::BaseTool
+  doc "Get the current weather for a location"
+
+  input_schema GetWeatherInput
+
+  def call(input)
+    "The weather in #{input.location} is sunny and 72°F."
+  end
+end
+
+client.beta.messages.tool_runner(
+  model: :"claude-opus-5",
+  max_tokens: 16000,
+  tools: [GetWeather.new],
+  messages: [{ role: "user", content: "What's the weather in San Francisco?" }]
+).each_message do |message|
+  puts message.content
+end
+```
+
+### Manual Loop
+
+See the [shared tool use concepts](../../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern.
+
+---
+

skills/claude-api/ruby/managed-agents/README.md

@@ -2,7 +2,7 @@
 
 > **Bindings not shown here:** This README covers the most common managed-agents flows for Ruby. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Ruby SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
 
-> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta.agents.create` and pass it to every subsequent `client.beta.sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
+> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta.agents.create` and pass it to every subsequent `client.beta.sessions.create`; do not call `agents.create` in the request path. **Recommended:** define agents and environments as version-controlled YAML applied with the `ant` CLI — see `shared/anthropic-cli.md` (its live-docs URL is in `shared/live-sources.md`). The CLI owns the control plane (create/update); your code owns the data plane (sessions with the stored ID). The examples below show in-code creation for when you must provision programmatically; in production the create call belongs in setup, not in the request path.
 
 ## Installation
 
@@ -51,7 +51,7 @@ puts "Environment ID: #{environment.id}" # env_...
 # 1. Create the agent (reusable, versioned)
 agent = client.beta.agents.create(
   name: "Coding Assistant",
-  model: :"claude-opus-4-8",
+  model: :"claude-opus-5",
   system_: "You are a helpful coding assistant.",
   tools: [{type: "agent_toolset_20260401"}]
 )
@@ -63,6 +63,7 @@ session = client.beta.sessions.create(
   title: "Quickstart session"
 )
 puts "Session ID: #{session.id}"
+puts "Trace: https://platform.claude.com/workspaces/default/sessions/#{session.id}"  # swap 'default' for your workspace ID if the API key is not in the Default workspace
 ```
 
 ### Updating an Agent
@@ -229,7 +230,11 @@ client.beta.sessions.resources.delete(resource.id, session_id: session.id)
 
 ## List and Download Session Files
 
-> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Ruby in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic` Ruby gem repository for the file list/download bindings.
+```ruby
+files = client.beta.files.list(scope_id: "sesn_abc123", betas: ["managed-agents-2026-04-01"])
+content = client.beta.files.download(files.data[0].id)
+File.binwrite("output.txt", content.read)
+```
 
 ---
 
@@ -260,7 +265,7 @@ client.beta.sessions.delete(session.id)
 # Agent declares MCP server (no auth here — auth goes in a vault)
 agent = client.beta.agents.create(
   name: "GitHub Assistant",
-  model: :"claude-opus-4-8",
+  model: :"claude-opus-5",
   mcp_servers: [
     {
       type: "url",

skills/claude-api/shared/agent-design.md

@@ -90,8 +90,8 @@ Both patterns keep the fixed context small and load detail on demand.
 
 | Constraint (from `prompt-caching.md`) | Agent-specific workaround |
 | --- | --- |
-| Editing the system prompt mid-session invalidates the cache. | Append a `{"role": "system", ...}` message to `messages[]` instead (beta, on supporting models — see `prompt-caching.md` § Mid-conversation system messages). The cached prefix stays intact, and the model treats it as an operator-authority instruction rather than user text. On models that don't support it, fall back to a `<system-reminder>` text block in the user turn. |
-| Switching models mid-session invalidates the cache. | Spawn a **subagent** with the cheaper model for the sub-task; keep the main loop on one model. Claude Code's Explore subagents use Haiku this way. |
+| Editing the system prompt mid-session invalidates the cache. | Append a `{"role": "system", ...}` message to `messages[]` instead (no beta header; on supporting models — see `prompt-caching.md` § Mid-conversation system messages). The cached prefix stays intact, and the model treats it as an operator-authority instruction rather than user text. On models that don't support it, fall back to a `<system-reminder>` text block in the user turn. |
+| Switching models mid-session invalidates the cache. | Spawn a **subagent** with the cheaper model for the sub-task; keep the main loop on one model. |
 | Adding/removing tools mid-session invalidates the cache. | Use **tool search** for dynamic discovery — it appends tool schemas rather than swapping them, so the existing prefix is preserved. |
 
 For multi-turn breakpoint placement, use top-level auto-caching — see `prompt-caching.md` §Placement patterns.

skills/claude-api/shared/anthropic-cli.md

@@ -60,7 +60,7 @@ curl https://api.anthropic.com/v1/messages \
   -H "anthropic-version: 2023-06-01" \
   -H "anthropic-beta: oauth-2025-04-20" \
   -H "content-type: application/json" \
-  -d '{"model": "claude-opus-4-8", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'
+  -d '{"model": "claude-opus-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'
 
 # .env format — sets ANTHROPIC_AUTH_TOKEN (and ANTHROPIC_BASE_URL if the profile has one).
 # Output is bare KEY=value (no `export`), so use `set -a` to auto-export for child processes:
@@ -82,7 +82,7 @@ Beta resources (agents, sessions, environments, deployments, skills, vaults, mem
 
 ```sh
 ant models list
-ant messages create --model claude-opus-4-8 --max-tokens 1024 --message '{role: user, content: "Hello"}'
+ant messages create --model claude-opus-5 --max-tokens 1024 --message '{role: user, content: "Hello"}'
 ant beta:agents retrieve --agent-id agent_01...
 ant beta:sessions:events list --session-id session_01...
 ```
@@ -112,7 +112,7 @@ ant beta:agents list --transform '{id,name,model}' --format jsonl
 **Extract a scalar for shell use:** pair `--transform` with `-r` (`--raw-output` — prints strings unquoted, jq-style):
 
 ```sh
-AGENT_ID=$(ant beta:agents create --name "My Agent" --model '{id: claude-sonnet-4-6}' \
+AGENT_ID=$(ant beta:agents create --name "My Agent" --model '{id: claude-sonnet-5}' \
   --transform id -r)
 ```
 
@@ -123,7 +123,7 @@ AGENT_ID=$(ant beta:agents create --name "My Agent" --model '{id: claude-sonnet-
 ```sh
 ant beta:agents create \
   --name "Research Agent" \
-  --model '{id: claude-opus-4-8}' \
+  --model '{id: claude-opus-5}' \
   --tool '{type: agent_toolset_20260401}' \
   --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'
 ```
@@ -133,7 +133,7 @@ ant beta:agents create \
 ```sh
 ant beta:agents create <<'YAML'
 name: Research Agent
-model: claude-opus-4-8
+model: claude-opus-5
 system: |
   You are a research assistant. Cite sources for every claim.
 tools:
@@ -144,9 +144,9 @@ YAML
 **`@file` references** — inline a file's contents into any string-valued field. Inside structured flag values, quote the path. Binary files are auto-base64'd; force with `@file://` (text) or `@data://` (base64). Escape a literal leading `@` as `\@`.
 
 ```sh
-ant beta:agents create --name "Researcher" --model '{id: claude-sonnet-4-6}' --system @./prompts/researcher.txt
+ant beta:agents create --name "Researcher" --model '{id: claude-sonnet-5}' --system @./prompts/researcher.txt
 
-ant messages create --model claude-opus-4-8 --max-tokens 1024 \
+ant messages create --model claude-opus-5 --max-tokens 1024 \
   --message '{role: user, content: [
     {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},
     {type: text, text: "Extract the text from this scanned document."}
@@ -163,7 +163,7 @@ This is the recommended flow for defining agents and environments — check the
 ```yaml
 # summarizer.agent.yaml
 name: Summarizer
-model: claude-sonnet-4-6
+model: claude-sonnet-5
 system: |
   You are a helpful assistant that writes concise summaries.
 tools:

skills/claude-api/shared/claude-platform-on-aws.md

@@ -1,6 +1,6 @@
 # Claude Platform on AWS
 
-**Anthropic-operated** access to the Claude Developer Platform through AWS infrastructure — SigV4 authentication, AWS IAM access control, and AWS Marketplace billing. Because Anthropic operates it, **the API surface matches first-party with same-day parity**: Managed Agents, server-side tools, batches, Files, and every feature in this skill work the same way (**except self-hosted sandboxes** — `config:{type:"self_hosted"}` is not available here; use `cloud`). Model IDs are the bare first-party strings (`claude-opus-4-8`, `claude-sonnet-4-6`) — **no provider prefix**.
+**Anthropic-operated** access to the Claude Developer Platform through AWS infrastructure — SigV4 authentication, AWS IAM access control, and AWS Marketplace billing. Because Anthropic operates it, **the API surface matches first-party with same-day parity** — for per-feature exceptions, see `shared/platform-availability.md` (the single source of truth; do not rely on an inline exception list here). Model IDs are the bare first-party strings (`claude-opus-5`, `claude-sonnet-5`) — **no provider prefix**.
 
 > **Not the same as Amazon Bedrock.** Bedrock is partner-operated (AWS runs the service; release schedules vary, feature subset, `anthropic.`-prefixed model IDs). Claude Platform on AWS and Bedrock coexist; pick by whether you need AWS-native IAM/billing with full Anthropic API parity (this page) vs. Bedrock's own ecosystem.
 
@@ -25,7 +25,7 @@ from anthropic import AnthropicAWS
 
 client = AnthropicAWS()  # region + workspace_id from env; see below
 client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=1024,
     messages=[{"role": "user", "content": "Hello"}],
 )
@@ -55,5 +55,5 @@ The client resolves AWS credentials via the standard precedence chain: explicit
 ## What to tell users
 
 - Treat it as first-party: every section of this skill applies unchanged. Do **not** apply Bedrock's feature-availability mask.
-- Model IDs are bare (`claude-opus-4-8`). Do **not** add an `anthropic.` prefix.
+- Model IDs are bare (`claude-opus-5`). Do **not** add an `anthropic.` prefix.
 - A missing region or `workspace_id` throws at client-construction time (no request is sent). A **403** means the request reached the server — check for a **wrong** `workspace_id` or a missing IAM action on the principal. See the IAM actions reference in `shared/live-sources.md`.

skills/claude-api/shared/error-codes.md

@@ -82,7 +82,7 @@ This file documents HTTP error codes returned by the Claude API, their common ca
 - Using deprecated model ID
 - Invalid API endpoint
 
-**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-4-8`).
+**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-5`).
 
 ---
 
@@ -107,11 +107,12 @@ Some 400 errors are specifically related to parameter validation:
 - `budget_tokens` >= `max_tokens` in extended thinking
 - Invalid tool definition schema
 
-**Model-specific 400s on Fable 5 / Opus 4.8 / 4.7:**
+**Model-specific 400s on Claude Opus 5 / Fable 5 / Opus 4.8 / 4.7:**
 
 - `temperature`, `top_p`, `top_k` are removed — sending any of them returns 400. Delete the parameter; see `shared/model-migration.md` → Per-SDK Syntax Reference.
 - `thinking: {type: "enabled", budget_tokens: N}` is removed — sending it returns 400. Use `thinking: {type: "adaptive"}` instead.
-- **Fable 5 only:** an explicit `thinking: {type: "disabled"}` returns 400 (it is accepted on Opus 4.8/4.7). Omit the `thinking` param entirely instead.
+- **Claude Opus 5:** `thinking: {type: "disabled"}` returns 400 when `effort` is `xhigh` or `max` — it is accepted at `high` or below. Thinking is on by default, so omitting the param runs adaptive rather than disabling it.
+- **Fable 5 only:** an explicit `thinking: {type: "disabled"}` returns 400 at any effort (it is accepted on Opus 4.8/4.7). Omit the `thinking` param entirely instead.
 - **Fable 5 only:** if the organization is set to zero data retention (ZDR) — or any retention below the required 30 days — then **all** Fable 5 requests return `400 invalid_request_error`, even with a perfectly valid payload. Check the org's retention configuration before debugging the request body.
 
 **Common mistake with extended thinking on older models (Opus 4.6 and earlier):**
@@ -170,12 +171,12 @@ thinking: budget_tokens=10000, max_tokens=16000
 
 | Mistake                         | Error            | Fix                                                     |
 | ------------------------------- | ---------------- | ------------------------------------------------------- |
-| `temperature`/`top_p`/`top_k` on Fable 5 / Opus 4.8 / 4.7 | 400 | Remove the parameter (see `shared/model-migration.md`)  |
-| `budget_tokens` on Fable 5 / Opus 4.8 / 4.7 | 400  | Use `thinking: {type: "adaptive"}`                      |
+| `temperature`/`top_p`/`top_k` on Claude Opus 5 / Fable 5 / Opus 4.8 / 4.7 | 400 | Remove the parameter (see `shared/model-migration.md`)  |
+| `budget_tokens` on Claude Opus 5 / Fable 5 / Opus 4.8 / 4.7 | 400  | Use `thinking: {type: "adaptive"}`                      |
 | `thinking: {type: "disabled"}` on Fable 5 | 400    | Omit the `thinking` param entirely (accepted on Opus 4.8/4.7) |
 | Org set to ZDR / retention below 30 days (Fable 5) | 400 on every request | Fix the org's data-retention configuration — the payload isn't the problem |
 | `budget_tokens` >= `max_tokens` (older models) | 400 | Ensure `budget_tokens` < `max_tokens`                  |
-| Typo in model ID                | 404              | Use valid model ID like `claude-opus-4-8`               |
+| Typo in model ID                | 404              | Use valid model ID like `claude-opus-5`               |
 | First message is `assistant`    | 400              | First message must be `user`                            |
 | Consecutive same-role messages  | 400              | Alternate `user` and `assistant`                        |
 | API key in code                 | 401 (leaked key) | Use environment variable                                |
@@ -183,42 +184,65 @@ thinking: budget_tokens=10000, max_tokens=16000
 
 ## Typed Exceptions in SDKs
 
-**Always use the SDK's typed exception classes** instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class:
+**Always use the SDK's typed exception classes** instead of checking error messages with string matching. Each HTTP status code maps to a specific exception class per SDK.
 
-| HTTP Code | TypeScript Class                  | Python Class                      |
-| --------- | --------------------------------- | --------------------------------- |
-| 400       | `Anthropic.BadRequestError`       | `anthropic.BadRequestError`       |
-| 401       | `Anthropic.AuthenticationError`   | `anthropic.AuthenticationError`   |
-| 403       | `Anthropic.PermissionDeniedError` | `anthropic.PermissionDeniedError` |
-| 404       | `Anthropic.NotFoundError`         | `anthropic.NotFoundError`         |
-| 413       | `Anthropic.RequestTooLargeError`  | `anthropic.RequestTooLargeError`  |
-| 429       | `Anthropic.RateLimitError`        | `anthropic.RateLimitError`        |
-| 500+      | `Anthropic.InternalServerError`   | `anthropic.InternalServerError`   |
-| 529       | `Anthropic.OverloadedError`       | `anthropic.OverloadedError`       |
-| Any       | `Anthropic.APIError`              | `anthropic.APIError`              |
+### Exception class names by language
 
-```typescript
-// ✅ Correct: use typed exceptions
-try {
-  const response = await client.messages.create({...});
-} catch (error) {
-  if (error instanceof Anthropic.RateLimitError) {
-    // Handle rate limiting
-  } else if (error instanceof Anthropic.APIError) {
-    console.error(`API error ${error.status}:`, error.message);
-  }
-}
+| HTTP | Python (`anthropic.*`) / TypeScript (`Anthropic.*`) | Ruby (`Anthropic::Errors::*`) | Java (`com.anthropic.errors.*`) | C# | PHP (`Anthropic\Core\Exceptions\*`) |
+|---|---|---|---|---|---|
+| 400 | `BadRequestError` | `BadRequestError` | `BadRequestException` | `AnthropicBadRequestException` | `BadRequestException` |
+| 401 | `AuthenticationError` | `AuthenticationError` | `UnauthorizedException` | `AnthropicUnauthorizedException` | `AuthenticationException` |
+| 403 | `PermissionDeniedError` | `PermissionDeniedError` | `PermissionDeniedException` | `AnthropicForbiddenException` | `PermissionDeniedException` |
+| 404 | `NotFoundError` | `NotFoundError` | `NotFoundException` | `AnthropicNotFoundException` | `NotFoundException` |
+| 422 | `UnprocessableEntityError` | `UnprocessableEntityError` | `UnprocessableEntityException` | `AnthropicUnprocessableEntityException` | `UnprocessableEntityException` |
+| 429 | `RateLimitError` | `RateLimitError` | `RateLimitException` | `AnthropicRateLimitException` | `RateLimitException` |
+| ≥500 | `InternalServerError` | `InternalServerError` | `InternalServerException` | `Anthropic5xxException` | `InternalServerException` |
+| net | `APIConnectionError` | `APIConnectionError` | `AnthropicIoException` | `AnthropicIOException` | `APIConnectionException` |
+| base | `APIError` (both); `APIStatusError` (Python only) | `APIStatusError` / `APIError` | `AnthropicServiceException` | `AnthropicApiException` | `APIStatusException` / `APIException` |
 
-// ❌ Wrong: don't check error messages with string matching
-try {
-  const response = await client.messages.create({...});
-} catch (error) {
-  const msg = error instanceof Error ? error.message : String(error);
-  if (msg.includes("429") || msg.includes("rate_limit")) { ... }
-}
+The Ruby and PHP classes live in a dedicated errors namespace — write `Anthropic::Errors::RateLimitError` and `Anthropic\Core\Exceptions\RateLimitException` (not bare `Anthropic::RateLimitError`). All 4xx C# exceptions also inherit from `Anthropic4xxException`.
+
+### Catch most-specific first, in a chain
+
+Order `catch`/`except`/`rescue` clauses from the most specific subclass to the base class, with a separate clause for each category you handle differently — retryable (429, ≥500, network) vs. non-retryable (4xx). The SDK defines a distinct class per status for exactly this reason; a single broad catch-all discards that information.
+
+```python
+try:
+    msg = client.messages.create(...)
+except anthropic.NotFoundError as e:          # 404 — e.g. bad model ID
+    ...
+except anthropic.RateLimitError as e:         # 429 — back off and retry
+    ...
+except anthropic.APIStatusError as e:         # any other non-2xx HTTP response
+    print(e.status_code, e.message)
+except anthropic.APIConnectionError as e:     # network failure before a response
+    ...
 ```
 
-All exception classes extend `Anthropic.APIError`, which has a `status` property. Use `instanceof` checks from most specific to least specific (e.g., check `RateLimitError` before `APIError`).
+The same chain shape applies in every SDK: TypeScript `instanceof Anthropic.NotFoundError` → `RateLimitError` → `APIConnectionError` → `APIError` (check `APIConnectionError` before `APIError` — in the TypeScript SDK it's a subclass of `APIError`, unlike Python where it's a sibling); Ruby `rescue Anthropic::Errors::NotFoundError` → `…::RateLimitError` → `…::APIStatusError`; Java `catch (NotFoundException) … catch (RateLimitException) … catch (AnthropicServiceException)`; C# `catch (AnthropicNotFoundException) … catch (AnthropicRateLimitException) … catch (AnthropicApiException)`; PHP `catch (NotFoundException) … catch (RateLimitException) … catch (APIStatusException)`.
+
+### Go — `errors.As` then branch on status
+
+The Go SDK returns a single `*anthropic.Error` for all non-2xx responses. Unwrap it with `errors.As`, then branch on `StatusCode`:
+
+```go
+_, err := client.Messages.New(ctx, params)
+if err != nil {
+    var apierr *anthropic.Error
+    if errors.As(err, &apierr) {
+        switch apierr.StatusCode {
+        case 404:
+            // bad model ID / resource
+        case 429:
+            // back off and retry
+        default:
+            // other API error — apierr.StatusCode, apierr.RequestID
+        }
+    } else {
+        // transport-level error (*url.Error wrapping *net.OpError, etc.)
+    }
+}
+```
 
 ### Error `.type` Field
 

skills/claude-api/shared/live-sources.md

@@ -25,7 +25,7 @@ This file contains WebFetch URLs for fetching current information from platform.
 | Topic             | URL                                                                          | Extraction Prompt                                                                      |
 | ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | Extended Thinking | `https://platform.claude.com/docs/en/build-with-claude/extended-thinking.md` | "Extract extended thinking parameters, budget_tokens requirements, and usage examples" |
-| Adaptive Thinking | `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md` | "Extract adaptive thinking setup, effort levels, and Claude Opus 4.8 usage examples"         |
+| Adaptive Thinking | `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md` | "Extract adaptive thinking setup, effort levels, and Claude Opus 5 usage examples"         |
 | Effort Parameter  | `https://platform.claude.com/docs/en/build-with-claude/effort.md`            | "Extract effort levels, cost-quality tradeoffs, and interaction with thinking"        |
 | Tool Use          | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md`  | "Extract tool definition schema, tool_choice options, and handling tool results"       |
 | Streaming         | `https://platform.claude.com/docs/en/build-with-claude/streaming.md`         | "Extract streaming event types, SDK examples, and best practices"                      |
@@ -106,7 +106,7 @@ Use these when a managed-agents binding, behavior, or wire-level detail isn't co
 
 ### Anthropic CLI
 
-The `ant` CLI provides terminal access to the Claude API. Every API resource is exposed as a subcommand. It is one convenient way to create agents, environments, sessions, and other resources from version-controlled YAML, and to inspect responses interactively.
+The `ant` CLI provides terminal access to the Claude API. Every API resource is exposed as a subcommand. It is the recommended way to create agents and environments from version-controlled YAML (`ant beta:agents create < agent.yaml` — see `shared/anthropic-cli.md`), and also exposes sessions and every other API resource for scripting and interactive inspection.
 
 | Topic         | URL                                                     | Extraction Prompt                                                                                  |
 | ------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |

skills/claude-api/shared/managed-agents-api-reference.md

@@ -2,6 +2,8 @@
 
 All endpoints require `x-api-key` and `anthropic-version: 2023-06-01` headers. Managed Agents endpoints additionally require the `anthropic-beta` header.
 
+> Most users should define agents and environments as version-controlled YAML applied with the `ant` CLI — see `shared/anthropic-cli.md`. The endpoints below are the underlying API that the CLI and SDKs drive.
+
 ## Beta Headers
 
 ```
@@ -27,7 +29,7 @@ All resources are under the `beta` namespace. Python and TypeScript share identi
 | Session Threads | `sessions.threads.list` / `retrieve` / `archive`; `sessions.threads.events.list` / `stream` | `Sessions.Threads.List` / `Get` / `Archive`; `Sessions.Threads.Events.List` / `StreamEvents` |
 | Session Resources | `sessions.resources.add` / `retrieve` / `update` / `list` / `delete` | `Sessions.Resources.Add` / `Get` / `Update` / `List` / `Delete` |
 | Deployments | `deployments.create` / `pause` / `unpause` / `archive` / `run` | Not yet documented — WebFetch the SDK repo (`shared/live-sources.md`) |
-| Deployment Runs | `deployment_runs.list` (TS: `deploymentRuns.list`) | Not yet documented — WebFetch the SDK repo (`shared/live-sources.md`) |
+| Deployment Runs | `deployment_runs.list` / `retrieve` (TS: `deploymentRuns.*`) | Not yet documented — WebFetch the SDK repo (`shared/live-sources.md`) |
 | Vaults | `vaults.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Vaults.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
 | Credentials | `vaults.credentials.create` / `retrieve` / `update` / `list` / `delete` / `archive` / `mcp_oauth_validate` | `Vaults.Credentials.New` / `Get` / `Update` / `List` / `Delete` / `Archive` / `McpOauthValidate` |
 | Memory Stores | `memory_stores.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `MemoryStores.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
@@ -40,9 +42,9 @@ All resources are under the `beta` namespace. Python and TypeScript share identi
 - Go's event stream is `StreamEvents` (not `Stream`).
 - The self-hosted worker is **not** under `client.beta.*` — it's `EnvironmentWorker` from `anthropic.lib.environments` / `@anthropic-ai/sdk/helpers/beta/environments`; only `environments.work.poller/stats/stop` are client methods.
 
-**Agent shorthand:** `agent` on session create accepts either a bare string (`agent="agent_abc123"` — uses latest version) or the full reference object (`{type: "agent", id: "agent_abc123", version: 123}`).
+**Agent shorthand:** `agent` on session create accepts three forms — a bare string (`agent="agent_abc123"`, latest version), a pinned reference `{type: "agent", id, version}`, or `{type: "agent_with_overrides", id, version?, model?, system?, tools?, mcp_servers?, skills?}` to override those fields for this session only (see `shared/managed-agents-core.md` → Override agent configuration for a session).
 
-**Model shorthand:** `model` on agent create accepts either a bare string (`model="claude-opus-4-8"` — uses `standard` speed) or the full config object (`{id: "claude-opus-4-6", speed: "fast"}`). Note: `speed: "fast"` is only supported on Opus 4.6.
+**Model shorthand:** `model` on agent create accepts either a bare string (`model="claude-opus-5"` — uses `standard` speed) or the full config object, which takes `speed` and `effort` alongside `id`: `{id: "claude-opus-5", speed: "fast"}`, `{id: "claude-opus-5", effort: "high"}`. `effort` accepts a level string (`low`/`medium`/`high`/`xhigh`/`max`) or `{type: "<level>"}`, and is **agent-configuration only** — an `effort` inside a per-session `model` override is ignored. See `shared/managed-agents-core.md` → Effort on the agent model. Note: `speed: "fast"` is supported on Claude Opus 5 and Opus 4.8 — on the Claude API only, which includes Managed Agents but not Amazon Bedrock, Google Cloud, or Microsoft Foundry. Opus 4.7 fast mode has been removed; `speed: "fast"` on Opus 4.7 returns an error.
 
 ---
 
@@ -55,7 +57,7 @@ All resources are under the `beta` namespace. Python and TypeScript share identi
 | `GET` | `/v1/agents` | ListAgents | List agents |
 | `POST` | `/v1/agents` | CreateAgent | Create a saved agent configuration |
 | `GET` | `/v1/agents/{agent_id}` | GetAgent | Get agent details |
-| `POST` | `/v1/agents/{agent_id}` | UpdateAgent | Update agent configuration |
+| `POST` | `/v1/agents/{agent_id}` | UpdateAgent | Update agent configuration. `version` is **optional**: supply it (≥ 1) for optimistic concurrency — a mismatch returns 409 — or omit it for an unconditional last-write-wins update. |
 | `POST` | `/v1/agents/{agent_id}/archive` | ArchiveAgent | Archive an agent. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state. |
 | `GET` | `/v1/agents/{agent_id}/versions` | ListAgentVersions | List agent versions |
 
@@ -76,7 +78,7 @@ All resources are under the `beta` namespace. Python and TypeScript share identi
 | -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
 | `GET` | `/v1/sessions/{session_id}/events` | ListEvents | List events (polling, paginated) |
 | `POST` | `/v1/sessions/{session_id}/events` | SendEvents | Send events (user message, tool result) |
-| `GET` | `/v1/sessions/{session_id}/events/stream` | StreamEvents | Stream events via SSE |
+| `GET` | `/v1/sessions/{session_id}/events/stream` | StreamEvents | Stream events via SSE. Optional `event_deltas[]=agent.message` / `agent.thinking` opts in to live-preview `event_start`/`event_delta` events — see `shared/managed-agents-events.md` § Live previews. |
 
 ## Session Threads
 
@@ -134,6 +136,7 @@ Each trigger attempt (scheduled or manual) writes a `deployment_run` record (`dr
 | Method   | Path                                             | Operation        | Description                              |
 | -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
 | `GET`    | `/v1/deployment_runs?deployment_id=...`          | ListDeploymentRuns | List runs for a deployment (paginated; filter failures with `has_error=true`) |
+| `GET`    | `/v1/deployment_runs/{deployment_run_id}`        | GetDeploymentRun   | Retrieve a single run by ID (a `deployment_run.*` webhook event carries this as `data.id`) |
 
 ## Vaults
 
@@ -181,7 +184,7 @@ Individual text documents inside a store (≤ 100KB each). `create` creates at a
 
 | Method   | Path                                                              | Operation      | Description                              |
 | -------- | ----------------------------------------------------------------- | -------------- | ---------------------------------------- |
-| `GET`    | `/v1/memory_stores/{memory_store_id}/memories`                    | ListMemories   | Returns `Memory \| MemoryPrefix`; filter by `path_prefix`, `depth`, `order_by`/`order` |
+| `GET`    | `/v1/memory_stores/{memory_store_id}/memories`                    | ListMemories   | Returns `Memory \| MemoryPrefix`; filter by `path_prefix`, `depth` |
 | `POST`   | `/v1/memory_stores/{memory_store_id}/memories`                    | CreateMemory   | Create at `path` (SDK: `memories.create`); `409 memory_path_conflict_error` if occupied |
 | `GET`    | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`        | GetMemory      | Read one memory (defaults to `view="full"`) |
 | `PATCH`  | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`        | UpdateMemory   | Change `content`, `path`, or both by ID; optional `precondition` |
@@ -231,7 +234,7 @@ Immutable per-mutation snapshots (`memver_...`) — the audit and rollback surfa
 ```json
 {
   "name": "string (required, 1-256 chars)",
-  "model": "claude-opus-4-8 (required — bare string, or {id, speed} object)",
+  "model": "claude-opus-5 (required — bare string, or {id, speed?, effort?} object)",
   "description": "string (optional, up to 2048 chars)",
   "system": "string (optional, up to 100,000 chars)",
   "tools": [
@@ -280,6 +283,9 @@ Immutable per-mutation snapshots (`memver_...`) — the audit and rollback surfa
       "checkout": { "type": "branch", "name": "main" }
     }
   ],
+  "initial_events": [
+    { "type": "user.message", "content": [{ "type": "text", "text": "Review the auth module." }] }
+  ],
   "vault_ids": ["vlt_abc123 (optional — vault credentials: MCP auth + environment variables)"],
   "metadata": {
     "key": "value"
@@ -287,7 +293,9 @@ Immutable per-mutation snapshots (`memver_...`) — the audit and rollback surfa
 }
 ```
 
-> The `agent` field accepts only a string ID or `{type: "agent", id, version}` — `model`/`system`/`tools` live on the agent, not here.
+> The `agent` field accepts a string ID, `{type: "agent", id, version}`, or `{type: "agent_with_overrides", id, version?, ...}` for session-local overrides of `model`/`system`/`tools`/`mcp_servers`/`skills`. Outside the overrides form, those fields live on the agent, not here. An `effort` inside a `model` override is ignored — set it on the agent.
+>
+> **`initial_events`** (optional, max 50) sends events at creation and starts the agent loop in the same call. Only `user.message` and `user.define_outcome` are accepted — no `system.message`, and none of the tool-result kinds. Validation is all-or-nothing. See `shared/managed-agents-core.md` → Seeding a session with `initial_events`.
 >
 > **`checkout`** accepts `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Omit for the repo's default branch.
 
@@ -346,7 +354,7 @@ Immutable per-mutation snapshots (`memver_...`) — the audit and rollback surfa
 }
 ```
 
-> `system.message` events (update the system prompt between turns) use the same envelope with `type: "system.message"` — Claude Opus 4.8 only; see `shared/managed-agents-events.md` § Updating the system prompt mid-session.
+> `system.message` events (append system-level context for this turn and later ones) use the same envelope with `type: "system.message"` — supported on Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, and Claude Mythos 5, checked against the agent's *primary* model only; see `shared/managed-agents-events.md` § Adding system context mid-session.
 
 ### Define Outcome Event
 
@@ -407,6 +415,24 @@ Note that `409 Conflict` carries `error.type: "invalid_request_error"` (there is
 
 ---
 
+## Pagination
+
+Most Managed Agents list endpoints use the `page` / `next_page` cursor scheme:
+
+| Field | Where | Notes |
+|---|---|---|
+| `limit` | query | Max items per page |
+| `page` | query | Opaque cursor from a previous response — pass a `next_page` or `prev_page` value here |
+| `order` | query | `asc` / `desc` on endpoints that support sorting. A cursor encodes the `order` of the request that produced it — reusing it with a different `order` returns 400. Other params (filters, `limit`) can change between paginated requests. |
+| `next_page` | response | Cursor for the next page; `null` when there are no more results |
+| `prev_page` | response | Cursor for the previous page on endpoints that support backward pagination — currently **only `GET /v1/sessions`**. `null` on the first page. On endpoints that don't support it, the field is **absent** (not `null`). |
+
+Every SDK exposes an auto-paginating iterator that follows `next_page`. In Python and TypeScript, iterate the list result directly; the other SDKs expose the iterator via a separate method (iterating the plain list result returns one page). SDK auto-pagination is **forward-only** — to go back a page, read `prev_page` from the response and pass it back as the `page` parameter yourself.
+
+> ⚠️ Some endpoints use a **different** cursor scheme: Message Batches, Files, Models, and several Admin API endpoints take `after_id`/`before_id` and return `has_more`/`first_id`/`last_id` instead of `page`/`next_page`. Some `page`-scheme endpoints (e.g. `GET /v1/skills`) also return a `has_more` boolean alongside `next_page`. Check the endpoint's reference page for its exact pagination fields.
+
+---
+
 ## Rate Limits
 
 Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your [Messages API token limits](https://platform.claude.com/docs/en/api/rate-limits). Model inference inside a session still draws from your organization's standard ITPM/OTPM limits.

skills/claude-api/shared/managed-agents-client-patterns.md

@@ -2,7 +2,7 @@
 
 Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples.
 
-Code samples are TypeScript — Python and cURL follow the same shape; see `python/managed-agents/README.md` and `curl/managed-agents.md` for equivalents.
+Code samples are TypeScript — other languages follow the same shape; see `{lang}/managed-agents/README.md` (cURL and C#: `curl/managed-agents.md`) for equivalents.
 
 ---
 
@@ -39,7 +39,9 @@ for await (const event of stream) {
 
 ## 2. `processed_at` — queued vs processed
 
-Every event on the stream carries `processed_at` (ISO 8601). For client-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`) it's `null` when the event has been queued but not yet picked up by the agent, and populated once the agent processes it. The same event appears on the stream twice — once with `processed_at: null`, once with a timestamp.
+Every event on the stream carries `processed_at` (ISO 8601), set when the event finishes processing. For client-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`) it's `null` while the event is queued behind earlier ones, and populated once the agent processes it — so the same event appears on the stream twice, once with `null` and once with a timestamp.
+
+**Three event types skip the queued phase:** `user.define_outcome`, `user.custom_tool_result`, and `user.tool_result` are processed on receipt and echoed back with `processed_at` already populated. A pending → acknowledged UI that assumes "first sighting is always `null`" will never clear for these — treat a populated `processed_at` on first sighting as immediately acknowledged.
 
 ```ts
 for await (const event of stream) {
@@ -198,7 +200,11 @@ for await (const event of stream) {
   if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') {
     const result = await linear.request(event.input.query, event.input.vars) // host's key
     await client.beta.sessions.events.send(session.id, {
-      events: [{ type: 'user.custom_tool_result', tool_use_id: event.id, result }],
+      events: [{
+        type: 'user.custom_tool_result',
+        custom_tool_use_id: event.id,
+        content: [{ type: 'text', text: JSON.stringify(result) }],
+      }],
     })
   }
 }

skills/claude-api/shared/managed-agents-core.md

@@ -41,17 +41,19 @@ rescheduling → running ↔ idle → terminated
 | `idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. |
 | `running` | Session has starting running, and the Agent is actively doing work. |
 | `rescheduling` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
-| `terminated` | Session has terminated, entering an irreversible and unusable state.  |
+| `terminated` | Session has ended and is in an irreversible, unusable state — **either on completion or because of an unrecoverable error**. Terminated does not by itself mean failure; fetch the session to tell the two apart. |
 
 - Events can be sent when the session is `running` or `idle`. Messages are queued and processed in order.
 - The agent transitions `idle → running` when it receives a new event, then back to `idle` when done.
 - Errors surface as `session.error` events in the stream, not as a status value.
 
+Every session has a live trace view in the Anthropic Console at `https://platform.claude.com/workspaces/{workspace}/sessions/{session_id}`. Print this URL immediately after creating a session so the user can watch tool calls and messages stream in real time. **`{workspace}` is the workspace the API key belongs to** — use `default` only when that's the org's Default workspace. The session response does **not** include a workspace field and the Console has no workspace-agnostic session route, so for non-default workspaces substitute the workspace's ID (visible in the Console URL bar, or expose it as a config value alongside the API key). A `default` link to a session that lives in another workspace lands on a **"Session not found"** page — the **Search workspaces** button there will locate it, but it is not an automatic redirect.
+
 ### Built-in session features
 
 - **Context compaction** — if you approach max context, the API automatically condenses session history to keep the interaction going
 - **Prompt caching** — historical repeated tokens are cached, reducing processing time and cost
-- **Extended thinking** — on by default, returned as `agent.thinking` events
+- **Extended thinking** — on by default; `agent.thinking` events signal thinking progress and carry no thinking content
 
 ### Session operations
 
@@ -106,7 +108,7 @@ Key fields returned by the API:
 const agent = await client.beta.agents.create(
   {
     name: "Coding Assistant",
-    model: "claude-opus-4-8",
+    model: "claude-opus-5",
     system: "You are a helpful coding agent.",
     tools: [{ type: "agent_toolset_20260401"}],
   },
@@ -122,25 +124,48 @@ const session = await client.beta.sessions.create(
 );
 ```
 
-> 💡 **Watch it live in Console.** While developing, print a link so you can click through to the session UI instead of parsing the event stream: `https://platform.claude.com/workspaces/{workspace}/sessions/{session.id}`. Use `default` for the workspace slug unless you created the session in a non-default workspace; the sessions list for your workspace is at `https://platform.claude.com/workspaces/default/sessions`. Include this `print`/`console.log` in code you generate for users who are iterating locally.
+> 💡 **Watch it live in Console.** While developing, print a link so you can click through to the session UI instead of parsing the event stream: `https://platform.claude.com/workspaces/{workspace}/sessions/{session.id}`. Use `default` for `{workspace}` only when the API key belongs to the org's Default workspace; otherwise substitute the workspace's ID (the session response does not carry it — read it from the Console URL bar or make it a config value). Include this `print`/`console.log` in code you generate for users who are iterating locally.
 
 **Session creation parameters:**
 
 | Field           | Type     | Required | Description                                    |
 | --------------- | -------- | -------- | ---------------------------------------------- |
-| `agent`         | string or object | **Yes** | String shorthand `"agent_abc123"` (latest version) or `{type: "agent", id, version}` |
+| `agent`         | string or object | **Yes** | Three forms: string shorthand `"agent_abc123"` (latest version); pinned `{type: "agent", id, version}`; or `{type: "agent_with_overrides", id, version?, ...}` to override `model`/`system`/`tools`/`mcp_servers`/`skills` for this session only — see § Override agent configuration for a session |
 | `environment_id`| string   | **Yes**  | Environment ID                                 |
 | `title`         | string   | No       | Human-readable name (appears in logs/dashboards) |
 | `resources`     | array    | No       | Files, GitHub repos, or memory stores, attached to the container at startup. Memory stores are session-create-only (not addable via `resources.add()`). |
+| `initial_events`| array    | No       | Events to send at creation, processed in order — collapses create + first send into one call. See § Seeding a session with `initial_events` below. |
 | `vault_ids`     | array    | No       | Vault IDs (`vlt_*`) — MCP credentials with auto-refresh + `environment_variable` secrets substituted at egress. See `shared/managed-agents-tools.md` → Vaults. |
 | `metadata`      | object   | No       | User-provided key-value pairs                  |
 
+#### Seeding a session with `initial_events`
+
+Creating a session without `initial_events` registers the session in `idle` and starts no work; the sandbox is provisioned when the session first needs it. Passing a **non-empty** `initial_events` array starts the agent loop in the same call — the session is **created directly in `running`**, never passing through `idle`. A client that waits for an `idle → running` transition to know work began will wait forever; check `status` on the create response instead.
+
+```python
+session = client.beta.sessions.create(
+    agent=AGENT_ID,
+    environment_id=ENVIRONMENT_ID,
+    initial_events=[
+        {"type": "user.message", "content": [{"type": "text", "text": "Review the auth module."}]},
+    ],
+)
+```
+
+- **Only `user.message` and `user.define_outcome` are accepted**, max **50** events. The tool-result kinds (`user.tool_confirmation`, `user.tool_result`, `user.custom_tool_result`) are rejected because no agent turn exists yet, and `user.interrupt` because there is no turn to stop. Unlike a scheduled deployment's `initial_events`, a session's does **not** accept `system.message`.
+- Each event is validated and persisted before the create response returns, in list order, with a server-assigned ID — exactly as if you had posted it to the send-events endpoint immediately after creation. Per-event content rules are the same as on that endpoint.
+- **The events are not echoed on the create response.** Read them back with `sessions.events.list(session.id)` if you need their server-assigned IDs.
+- **Validation is all-or-nothing:** if any event fails, the whole request is rejected and no session is created. An empty list is equivalent to omitting the field.
+- Rejections: more than one `user.define_outcome` → 400; a `user.define_outcome` without a `rubric` → 400; more than 100 file-sourced `document` content blocks across the whole list → 400; a request body over 32 MB → 413.
+
+An outcome-driven session is therefore a single call — pass one `user.define_outcome` in `initial_events` instead of creating the session and then sending the event (see `shared/managed-agents-outcomes.md`).
+
 **Agent configuration fields** (passed to `agents.create()`, not `sessions.create()`):
 
 | Field         | Type     | Required | Description                                    |
 | ------------- | -------- | -------- | ---------------------------------------------- |
 | `name`        | string   | **Yes**  | Human-readable name (1-256 chars)              |
-| `model`       | string or object | **Yes** | Claude model ID (bare string, or `{id, speed}` object). All Claude 4.5+ models supported. |
+| `model`       | string or object | **Yes** | Claude model ID (bare string, or an object taking `id`, `speed`, and `effort`). All Claude 4.5+ models supported. See § Effort on the agent model below. |
 | `system`      | string   | No       | System prompt — defines the agent's behavior (up to 100K chars) |
 | `tools`       | array    | No       | Encompasses three kinds: (1) pre-built Claude Agent tools (`agent_toolset_20260401`), (2) MCP tools (`mcp_toolset`), and (3) custom client-side tools. Max 128. |
 | `mcp_servers` | array    | No       | MCP server connections — standardized third-party capabilities (e.g. GitHub, Asana). Max 20, unique names. See `shared/managed-agents-tools.md` → MCP Servers. |
@@ -162,7 +187,7 @@ The API is **flat** — `model`, `system`, `tools` etc. are top-level fields, no
 | Field              | Type     | Required | Description                                        |
 | ------------------ | -------- | -------- | -------------------------------------------------- |
 | `name`             | string   | Yes      | Human-readable name                                |
-| `model`            | string   | Yes      | Claude model ID                                    |
+| `model`            | string or object | Yes | Claude model ID — bare string, or `{id, speed?, effort?}` |
 | `system`           | string   | No       | System prompt                                      |
 | `tools`            | array    | No       | Agent toolset / MCP toolset / custom tools         |
 | `mcp_servers`      | array    | No       | MCP server connections                             |
@@ -187,10 +212,27 @@ The agent is a **persistent resource**, not a per-run parameter. The intended pa
 
 > **Recommended — define agents and environments as YAML + apply via the `ant` CLI.** The split is **CLI for the control plane, SDK for the data plane**: agents and environments are relatively static resources you manage with `ant` (version-controlled YAML, applied from CI); sessions are dynamic and driven by your application through the SDK. See `shared/anthropic-cli.md` → *Version-controlled Managed Agents resources* for the `ant beta:agents create < agent.yaml` / `update --version N` flow. The SDK `agents.create()` call shown elsewhere in this doc is the in-code equivalent — use it when you need to provision programmatically, but prefer the YAML flow for anything a human maintains.
 
+### Effort on the agent model
+
+Pass `model` as an object to set the effort level: `{"id": "claude-opus-5", "effort": "high"}`. `effort` accepts a level string (`low`, `medium`, `high`, `xhigh`, `max`) or an object such as `{"type": "high"}`. The create/update response echoes it in object form and fills in omitted `model` fields with their defaults.
+
+> ⚠️ **Effort is agent configuration only.** An `effort` set inside a per-session `model` override is **not applied** — the session runs at the agent's effort. To change effort you must update the agent (or point the session at a different agent). This is the one field where the override form silently does nothing rather than erroring.
+
+The same object form carries `speed` for fast mode: `{"id": "claude-opus-5", "speed": "fast"}`.
+
 ### Versioning
 
 Each `POST /v1/agents/{id}` (update) creates a new immutable version (numeric timestamp, e.g. `1772585501101368014`). The agent's history is append-only — you can't edit a past version.
 
+**`version` on update is optional.** Supply it for optimistic concurrency, or omit it to apply the update unconditionally:
+
+| `version` | Behavior | Fits |
+|---|---|---|
+| Supplied (must be ≥ 1) | 409 if it doesn't match the agent's current version — **even when the fields you send already equal the stored values**. Re-read and retry. | Interactive callers; the recommended default |
+| Omitted | Applies unconditionally. The most recent update silently replaces any concurrent one, with no error to either caller. | Declarative apply loops — e.g. a CI job syncing checked-in agent definitions, where the loop owns the agent |
+
+**Update semantics.** Omitted fields are preserved. Scalar fields (`model`, `system`, `name`, `description`) are replaced; `system` and `description` can be cleared with `null`, while `model` and `name` cannot. Array fields (`tools`, `mcp_servers`, `skills`) are replaced wholesale — `null` or `[]` clears them. **`effort` is the exception inside a `model` object you supply:** if the model `id` is unchanged, omitting `effort` leaves the stored level alone; if you change the `id`, an omitted `effort` resets to the new model's default.
+
 **Why version:**
 - **Reproducibility** — pin a session to a known-good config: `{type: "agent", id, version: 3}`
 - **Safe iteration** — update the agent without breaking sessions already running on the old version
@@ -232,10 +274,35 @@ session = client.beta.sessions.create(
 )
 ```
 
+### Override agent configuration for a session
+
+The third `agent` form, `agent_with_overrides`, replaces parts of the agent's configuration for **a single session** — try a different model or grant an extra tool without versioning the agent. Pass `id` (and optionally `version`; omitted = latest, same default as the other two forms) plus any of `model`, `system`, `tools`, `mcp_servers`, `skills`:
+
+```python
+session = client.beta.sessions.create(
+    agent={
+        "type": "agent_with_overrides",
+        "id": agent.id,
+        "model": "claude-opus-5",   # replace the agent's model for this session
+        "system": None,           # clear the system prompt for this session
+    },
+    environment_id=environment_id,
+)
+```
+
+Each overridable field follows tri-state rules:
+- **Omit** → the session inherits the value from the referenced agent version.
+- **`null` (or `[]` for list fields)** → the session runs with that field cleared. Applies in full to `system` and `skills`. Three exceptions: `model` is never clearable (`model: null` → 400 `agent_model_required`); clearing `tools` returns 400 when the session's effective `skills` is non-empty (skills require the `read` tool); and clearing `mcp_servers` returns 400 when the effective `tools` still contains an `mcp_toolset` referencing one of the agent's servers — override `tools` in the same request to drop those entries, then clear `mcp_servers`.
+- **A value** → replaces the agent's value **in full**. Overrides never merge — a `tools` override must list every tool the session should have. One exception: an `effort` level inside a `model` override is **not applied** (set it on the agent instead — see § Effort on the agent model).
+
+Overrides are session-local: they do **not** modify the agent resource or create a new agent version. The response's `agent` object reflects the post-override configuration, while its `id` and `version` still identify the base agent — so you can trace a session back to its base. In multiagent sessions, overrides apply to the coordinator and its `{type: "self"}` copies; roster agents referenced by ID always use their own as-created configuration (see `shared/managed-agents-multiagent.md`).
+
 ### Updating the agent configuration mid-session
 
 `sessions.update()` can change `agent.tools`, `agent.mcp_servers` (including permission policies), and `vault_ids` on an **existing** session. This is a **session-local override** — it does not create a new agent version and does not propagate back to the agent object. The provided arrays are **full replacements**; to append one tool, `GET` the session, modify, and `POST` back. The session must be `idle` — interrupt first if running.
 
+Only `tools` and `mcp_servers` can change after a session is created — to run with a `model`, `system`, or `skills` other than the agent's values, use `agent_with_overrides` at create time (above). The agent's configured `system` field is fixed for the session's lifetime; you can still **append system-level context between turns** by sending a `system.message` event (see `shared/managed-agents-events.md` § Adding system context mid-session).
+
 ```python
 client.beta.sessions.update(
     session.id,

skills/claude-api/shared/managed-agents-environments.md

@@ -61,7 +61,7 @@ To run tool execution in **your own infrastructure** instead of Anthropic's, set
 
 ## Resources
 
-Attach files, GitHub repositories, and memory stores to a session. **Session creation blocks until all resources are mounted** — the container won't go `running` until every file and repo is in place. Max **999 file resources** per session. Multiple GitHub repositories per session are supported. For `type: "memory_store"` resources (persistent cross-session memory — max 8 per session), see `shared/managed-agents-memory.md`.
+Attach files, GitHub repositories, and memory stores to a session. Resources are resolved during session creation, so a bad `file_id` or an unreachable repo surfaces on the create call rather than mid-run. Creating a session does **not** by itself start work or provision the sandbox — without `initial_events` the session is only registered, and the sandbox comes up when the session first needs it (see `shared/managed-agents-core.md` → Seeding a session with `initial_events`). Max **999 file resources** per session. Multiple GitHub repositories per session are supported. For `type: "memory_store"` resources (persistent cross-session memory — max 8 per session), see `shared/managed-agents-memory.md`.
 
 ### File Uploads (input — host → agent)
 
@@ -143,7 +143,7 @@ Repositories are attached for the lifetime of the session — to change which re
 const agent = await client.beta.agents.create(
   {
     name: 'GitHub Agent',
-    model: 'claude-opus-4-8',
+    model: 'claude-opus-5',
     mcp_servers: [
       { type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/' },
     ],
@@ -177,7 +177,7 @@ import os
 
 agent = client.beta.agents.create(
     name="GitHub Agent",
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     mcp_servers=[{
         "type": "url",
         "name": "github",

skills/claude-api/shared/managed-agents-events.md

@@ -13,11 +13,11 @@ Send events to a session via `POST /v1/sessions/{id}/events`.
 | `user.tool_confirmation`  | Approve/deny a tool call (when `always_ask` policy) |
 | `user.custom_tool_result` | Provide result for a custom tool call |
 | `user.define_outcome`     | Start a rubric-graded iterate loop — see `shared/managed-agents-outcomes.md` |
-| `system.message`          | Update the agent's system prompt between turns — **Claude Opus 4.8 only**; see § Updating the system prompt mid-session |
+| `system.message`          | Append privileged system-level context for this turn and every turn after it; see § Adding system context mid-session |
 
-#### Updating the system prompt mid-session (`system.message`)
+#### Adding system context mid-session (`system.message`)
 
-Unlike the `system` field on the agent definition (fixed at session creation), a `system.message` event changes the system prompt **as the session progresses** — a different persona, revised constraints, or runtime-fetched context that should shape behavior going forward:
+The `system` field on the agent definition sets the top-level system prompt and is fixed for the session's lifetime. A `system.message` event **appends** to the session's system context as a `role: "system"` turn — it does not replace that prompt. The content applies to the accompanying turn and all subsequent turns. Use it for a different persona, revised constraints, or runtime-fetched context that should shape behavior going forward:
 
 ```python
 client.beta.sessions.events.send(
@@ -35,8 +35,8 @@ client.beta.sessions.events.send(
 
 Constraints:
 
-- **Claude Opus 4.8 only.** If any model configured on the agent does not support mid-conversation system injection, the event is rejected with a `model_does_not_support_mid_conversation_system` validation error.
-- **Cannot be sent while the session is idle with `stop_reason: requires_action`** (blocked on `user.custom_tool_result` / `user.tool_confirmation`).
+- **Model-gated: Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, and Claude Mythos 5.** Only the agent's **primary** model is checked — `system.message` lands on the primary thread only, so subagent models are not considered. On an unsupported primary model the event is rejected with a `model_does_not_support_mid_conversation_system` validation error.
+- **While the session is idle with `stop_reason: requires_action`** (blocked on `user.custom_tool_result` / `user.tool_confirmation`), a `system.message` is accepted **only when it trails a tool result event in the same request**. Sent on its own — or alongside a `user.message` — it is rejected until the pending tool events are resolved.
 - `content` accepts 1–1000 text items.
 
 ### Receiving Events
@@ -47,11 +47,11 @@ Three methods:
 2. **Polling**: `GET /v1/sessions/{id}/events` — paginated event list (query params: `limit` default 1000, `page`). **Returns immediately** — this is a plain paginated GET, not a long-poll.
 3. **Webhooks**: Anthropic POSTs session state transitions to your HTTPS endpoint — thin payloads (IDs only), HMAC-signed, Console-registered. See `shared/managed-agents-webhooks.md`.
 
-All received events carry `id`, `type`, and `processed_at` (ISO 8601; `null` if not yet processed by the agent).
+All **persisted** events carry `id`, `type`, and `processed_at` (ISO 8601), set when the event finishes processing. On events you send, `processed_at` is `null` while the event is still queued behind earlier ones — **except** `user.define_outcome`, `user.custom_tool_result`, and `user.tool_result`, which are processed on receipt and echoed back with `processed_at` already populated. The stream-only `event_start` / `event_delta` preview events (see § Live previews) carry only the `id` of the event they preview.
 
 > ⚠️ **Robust polling (raw HTTP).** If you bypass the SDK and roll your own poll loop, don't rely on `requests` or `httpx` timeouts as wall-clock caps — they're **per-chunk** read timeouts, reset every time a byte arrives. A trickling response (heartbeats, a wedged chunked-encoding body, a misbehaving proxy) can keep the call blocked indefinitely even with `timeout=(5, 60)` or `httpx.Timeout(120)`. Neither library has a "total wall-clock" timeout built in. For a hard deadline: track `time.monotonic()` at the loop level and break/cancel if a single request exceeds your budget (e.g. via a watchdog thread, or `asyncio.wait_for()` around async httpx). **Prefer the SDK** — `client.beta.sessions.events.stream()` and `client.beta.sessions.events.list()` handle timeout + retry sanely.
 >
-> If `GET /v1/sessions/{id}/events` (paginated) ever hangs after headers, you've likely hit `GET /v1/sessions/{id}/events` by mistake or a server-side stall — report it; don't treat it as a client-config problem.
+> If `GET /v1/sessions/{id}/events` (paginated) ever hangs after headers, you've likely hit `GET /v1/sessions/{id}/events/stream` by mistake or a server-side stall — report it; don't treat it as a client-config problem.
 
 ### Event Types (Received)
 
@@ -60,7 +60,7 @@ Event types use dot notation, grouped by namespace:
 | Event Type | Description |
 | --- | --- |
 | `agent.message` | Agent text output |
-| `agent.thinking` | Extended thinking blocks |
+| `agent.thinking` | Progress signal that the agent is thinking — it does **not** carry the thinking content |
 | `agent.tool_use` | Agent used a built-in tool (`agent_toolset_20260401`) |
 | `agent.tool_result` | Result from a built-in tool |
 | `agent.mcp_tool_use` | Agent used an MCP tool |
@@ -70,7 +70,7 @@ Event types use dot notation, grouped by namespace:
 | `session.status_idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. |
 | `session.status_running` | Session has starting running, and the Agent is actively doing work. |
 | `session.status_rescheduled` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
-| `session.status_terminated` | Session has terminated, entering an irreversible and unusable state.  |
+| `session.status_terminated` | Session ended and is irreversibly unusable — **on completion or on error**, not error-only. |
 | `session.error` | Error occurred during processing |
 | `span.model_request_start` | Model inference started |
 | `span.model_request_end` | Model inference completed |
@@ -81,6 +81,52 @@ Event types use dot notation, grouped by namespace:
 
 The stream also echoes back user-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`, `user.define_outcome`).
 
+Stream-only delta preview events (`event_start`, `event_delta`) are the one exception to the `{domain}.{action}` naming convention — see § Live previews below; they never appear in `GET /v1/sessions/{id}/events`.
+
+---
+
+## Live previews
+
+By default, assistant text reaches the stream as buffered `agent.message` events — emitted only after the model request that produced them finishes. **Live previews** let you render that text incrementally while the model is still generating. The buffered `agent.message` is always the authoritative record; a client that ignores previews still receives a complete, correct stream. The wire format is **not** Messages-API streaming: the delta type is `content_delta`, not `content_block_delta`, so Messages-API accumulator code does not carry over unchanged.
+
+**Opt in per stream connection** by adding the `event_deltas[]` query parameter, repeated once per event type to preview. Accepted values: `agent.message`, `agent.thinking` — any other value returns a 400, as does a request with more than 100 values. **Both stream endpoints accept it:** the session-level stream (`GET /v1/sessions/{id}/events/stream`) and each session thread's own stream (`GET /v1/sessions/{sid}/threads/{tid}/stream`). In a shell, quote the URL or percent-encode the brackets as `%5B%5D` — bare `[]` is a glob pattern.
+
+**Previews are thread-scoped.** A connection previews only the thread it is reading. A child thread's previews are delivered on that child's stream and are *never* cross-posted to the session-level stream, whose previews stay scoped to the primary thread. To watch a subagent's text as the model generates it, open that subagent's thread stream — see `shared/managed-agents-multiagent.md`. Run one accumulator instance per connection.
+
+```python
+stream = client.beta.sessions.events.stream(
+    session_id=session.id,
+    event_deltas=["agent.message"],
+)
+```
+
+When a previewed event begins, the stream emits an `event_start` carrying the upcoming event's `type` and `id`; for `agent.message` it's followed by `event_delta` events carrying incremental text:
+
+```json
+{"type": "event_start", "event": {"type": "agent.message", "id": "sevt_01abc..."}}
+{"type": "event_delta", "event_id": "sevt_01abc...", "delta": {"type": "content_delta", "index": 0, "content": {"type": "text", "text": "Here is the summary"}}}
+```
+
+`event_start` and `event_delta` have no `id` or `processed_at` of their own — the only identifier they carry is the `id` of the event they preview. For `agent.thinking`, **only** the `event_start` is emitted (a "thinking has started" signal) — no deltas follow, and the buffered `agent.thinking` that concludes the preview carries no thinking content either. It is a progress signal, not a content carrier; there is nothing to read out of it.
+
+**Accumulate-and-reconcile pattern.** Treat the preview as a scratch buffer keyed by `(event_id, index)`. On `event_start`, create an empty entry for the announced `id`. On each `event_delta`, append `delta.content.text` to `(event_id, delta.index)` and render the running text. When the buffered `agent.message` arrives, match it by `id`, **discard the accumulated preview**, and render the message's content instead. The identifiers always line up: `event_start.event.id`, every `event_delta.event_id`, and the buffered event's `id` are the same value. On a normal turn the order is fixed: `session.status_running` → `span.model_request_start` → `event_start` → `event_delta`* → buffered `agent.message` → `span.model_request_end`. If the turn errors or is interrupted the buffered event may never arrive, but `span.model_request_end` still does — close any unreconciled preview when you see it. Python/TypeScript/Go SDKs ship an accumulator helper that implements this; in other SDKs apply the manual pattern to the generated event types.
+
+**Two guarantees the pattern relies on:** concatenating a preview's deltas in arrival order, keyed by `(event_id, index)`, yields a *prefix* of `content[index].text` in the buffered event (a prefix, not necessarily the whole text — deltas may be shed under load); and a connection emits at most one `event_start` per `event_id`, with the buffered event as the last thing that connection delivers for that `id`.
+
+**Limitations:**
+- **Best effort** — under load the server may shed deltas for an event; you receive a contiguous prefix and then no further deltas for that event. The buffered `agent.message` still arrives complete. Never treat an accumulated preview as final.
+- **No replay on reconnect** — deltas are delivered only to the connection that opted in, while it's open; this holds for the session-level stream and each thread stream alike. A connection opened after a model request started receives no deltas for that in-flight event. After a drop, follow the consolidation pattern in § Reconnecting after a dropped stream — the history fetch returns any buffered events emitted during the gap; missed deltas cannot be re-requested.
+- **One thread, text only** — previews cover assistant text on the thread the connection is reading. Tool use, tool results, MCP results, and activity on any *other* thread are never previewed on that connection.
+- **Never persisted** — `event_start` / `event_delta` exist only on the live SSE stream, never in `GET /v1/sessions/{id}/events` or any thread's event history.
+
+**Troubleshooting:**
+
+| You see | What it means |
+| --- | --- |
+| Buffered events but no `event_start` / `event_delta` | This connection didn't opt in (`event_deltas[]` is per connection, not per session), or the turn ran on a different thread. List `GET /v1/sessions/{sid}/threads` to find which one ran. |
+| 404 on the stream URL | Wrong path or ID, or the request carries no managed-agents beta header — the thread endpoints are beta-gated, so without it they don't exist. The thread path is `/threads/{tid}/stream`, **not** `/threads/{tid}/events/stream` (which doesn't exist) and not `/events/stream` (session level only). |
+| 400 naming `event_deltas` | Only `agent.message` and `agent.thinking` are accepted, max 100 values. |
+
 ---
 
 ## Steering Patterns
@@ -148,16 +194,20 @@ Events can be sent up to the Session at any time. There is no need to wait on a
 
 ### Interrupt
 
-An `interrupt` event **jumps the queue** (ahead of any pending user messages) and forces the session into `idle`. Use this for "stop" / "nevermind" / "cancel" commands:
+A `user.interrupt` event **jumps the queue** (ahead of any pending user messages) and forces the session into `idle`. Use this for "stop" / "nevermind" / "cancel" commands:
 
 ```ts
 await client.beta.sessions.events.send(sessionId, {
-  events: [{ type: 'interrupt' }],
+  events: [{ type: 'user.interrupt' }],
 });
 ```
 
 The agent stops mid-task. It does not see the interrupt as a message — it just halts. Send a follow-up `user` event to explain what to do instead. If an outcome is active, the interrupt also marks `span.outcome_evaluation_end.result: "interrupted"` (see `shared/managed-agents-outcomes.md`).
 
+**The interrupted turn ends with `stop_reason: end_turn`** — the same value a turn that finishes on its own carries. There is no interruption-specific stop reason, so a drain loop can't distinguish the two from `stop_reason` alone; track that you sent the interrupt.
+
+**In a multiagent session, omitting `session_thread_id` interrupts every non-archived thread, including the primary** — it is not primary-only. Pass `session_thread_id` to stop one thread. See `shared/managed-agents-multiagent.md`.
+
 > **Note**: Interrupt events may have empty IDs in the current implementation. When troubleshooting, use the `processed_at` timestamp along with surrounding event IDs.
 
 ### Event payloads

skills/claude-api/shared/managed-agents-memory.md

@@ -6,6 +6,8 @@ Sessions are ephemeral by default — when one ends, anything the agent learned
 
 Every mutation to a memory produces an immutable **memory version** (`memver_...`), giving you an audit trail and point-in-time rollback/redact.
 
+> ⚠️ **Never store credentials, API keys, or tokens in memory stores.** Memories persist across sessions and are returned verbatim into future contexts — a key written once is replayed into every later session that mounts the store. Use vault `environment_variable` credentials instead (`shared/managed-agents-tools.md` → Vaults). If a secret has already been written, delete the memory and redact the affected versions (see "Redact a version" below).
+
 ## Object model
 
 | Object | ID prefix | Scope | Notes |
@@ -82,7 +84,7 @@ Use these for review workflows, correcting bad memories, or seeding stores out-o
 
 ### List
 
-Returns `Memory | MemoryPrefix` entries — a `MemoryPrefix` (`type: "memory_prefix"`, just a `path`) is a directory-like node when listing hierarchically. Use `path_prefix` to scope (include a trailing slash: `"/notes/"` matches `/notes/a.md` but not `/notes_backup/old.md`) and `depth` to bound the tree walk. `order_by` / `order` sort the result. Pass `view="full"` to include `content` in each item; the default `"basic"` returns metadata only.
+Returns `Memory | MemoryPrefix` entries — a `MemoryPrefix` (`type: "memory_prefix"`, just a `path`) is a directory-like node when listing hierarchically. Use `path_prefix` to scope (include a trailing slash: `"/notes/"` matches `/notes/a.md` but not `/notes_backup/old.md`) and `depth` to bound the tree walk. Pass `view="full"` to include `content` in each item; the default `"basic"` returns metadata only.
 
 ```python
 for m in client.beta.memory_stores.memories.list(store.id, path_prefix="/"):

skills/claude-api/shared/managed-agents-multiagent.md

@@ -13,7 +13,7 @@ The SDK sets the `managed-agents-2026-04-01` beta header automatically on all `c
 ```python
 orchestrator = client.beta.agents.create(
     name="Engineering Lead",
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     system="You coordinate engineering work. Delegate code review to the reviewer and test writing to the test agent.",
     tools=[{"type": "agent_toolset_20260401"}],
     multiagent={
@@ -35,7 +35,9 @@ session = client.beta.sessions.create(agent=orchestrator.id, environment_id=env.
 | Agent reference | `{type: "agent", id, version?}` | Omit `version` to pin the latest at coordinator save time. |
 | Self | `{type: "self"}` | The coordinator can spawn copies of itself. |
 
-Up to **20 unique agents** in the roster; the coordinator may spawn **multiple copies** of each. **One level of delegation only** — depth > 1 is ignored.
+If the session was created with `agent_with_overrides` (see `shared/managed-agents-core.md` → Override agent configuration for a session), those overrides apply to the **coordinator and its `self` copies**. Roster agents referenced by ID always use their own as-created configuration — overrides do not propagate to them.
+
+Up to **20 unique agents** in the roster; the coordinator may spawn **multiple copies** of each. **One level of delegation only** — and it is enforced rather than silently flattened: rostering an agent that itself carries a `multiagent.agents` roster fails the create or update with a validation error.
 
 ---
 
@@ -64,8 +66,24 @@ Each `SessionThread` carries `id`, `status` (`running` | `idle` | `rescheduling`
 | `session.thread_status_idle` | `session_thread_id`, `agent_name`, **`stop_reason`** | Thread is awaiting input. Inspect `stop_reason` (same shape as `session.status_idle.stop_reason`). |
 | `session.thread_status_rescheduled` | `session_thread_id`, `agent_name` | Thread is rescheduling after a retryable error. |
 | `session.thread_status_terminated` | `session_thread_id`, `agent_name` | Thread was archived or hit a terminal error. |
-| `agent.thread_message_sent` | `to_session_thread_id`, `to_agent_name`, `content` | Coordinator sent a follow-up to another thread. |
-| `agent.thread_message_received` | `from_session_thread_id`, `from_agent_name`, `content` | An agent delivered its result to the coordinator. |
+| `agent.thread_message_sent` | `to_session_thread_id`, `to_agent_name`, `content` | *This* thread sent a message to another thread. On the primary stream: the coordinator sent a task or follow-up to an agent. |
+| `agent.thread_message_received` | `from_session_thread_id`, `from_agent_name`, `content` | A message arrived on *this* thread from another. On the primary stream: an agent sent a report or question to the coordinator. |
+
+> **Direction is relative to the thread whose stream carries the event**, not to the coordinator. The same delegated task is an `agent.thread_message_sent` on the primary stream and an `agent.thread_message_received` on the child's own stream. Reading `_received` as "a subagent finished" is wrong once you're reading a child stream.
+
+---
+
+## Previewing a subagent's text
+
+Each thread's stream accepts the same `event_deltas[]` parameter as the session-level stream, so you can watch a subagent's text as the model generates it:
+
+```
+GET /v1/sessions/{sid}/threads/{tid}/stream?event_deltas%5B%5D=agent.message
+```
+
+**Previews are thread-scoped.** A child's previews are delivered only on that child's stream and never cross-posted to the session-level stream, whose previews stay scoped to the primary thread. So watching a subagent live means opening its thread stream — the session stream will not show it, no matter what you pass.
+
+> ⚠️ **Only plain assistant text previews.** A subagent's *reply to its coordinator* rides `agent.thread_message_sent` and is never previewed. A worker that does nothing but report back therefore streams no deltas at all, even with a correct opt-in on the right thread. To get a live preview out of a subagent, its prompt has to make it write the answer as a plain assistant message in its own thread first, and only then report to the coordinator. Run one accumulator per connection, and exit the read loop on `session.thread_status_idle`. Opt-in, accumulate, and reconcile details: `shared/managed-agents-events.md` → Live previews.
 
 ---
 
@@ -90,10 +108,18 @@ The same pattern applies to `user.custom_tool_result`.
 
 ---
 
+## Interrupting and archiving threads
+
+- **`user.interrupt` without `session_thread_id` interrupts every non-archived thread in the session, including the primary** — it is not a primary-only stop. Pass `session_thread_id` to target one thread.
+- **Against a child thread blocked on `requires_action`**, the interrupt closes each pending tool call with an *error* tool result (`"Tool execution was interrupted before completion. Please retry."`) and re-emits `session.thread_status_idle` with `stop_reason: end_turn` directly — the model is not sampled. Against a thread already `idle`, the interrupt is a no-op.
+- **Archive requires the thread to be idle, and `requires_action` counts as idle** — a thread parked on a pending tool call can be archived directly. Only a *running* thread must be interrupted first.
+
+---
+
 ## Pitfalls
 
 - **Don't put the roster on `sessions.create()` or in `tools[]`.** `multiagent` is a top-level agent field; update the coordinator, then start a session that references it.
 - **Don't assume shared context.** Threads share the filesystem but not conversation history or tools. If the coordinator needs a subagent to act on something, it must say so in the delegated message (or write it to disk).
-- **Depth > 1 is ignored.** A subagent's own `multiagent` roster (if any) doesn't cascade — only the session's coordinator delegates.
+- **Depth > 1 is a validation error.** Rostering an agent that itself carries a `multiagent.agents` roster fails the create or update — only the session's coordinator delegates.
 
 For per-language bindings beyond Python, WebFetch `https://platform.claude.com/docs/en/managed-agents/multi-agent.md` (see `shared/live-sources.md`).

skills/claude-api/shared/managed-agents-onboarding.md

@@ -2,143 +2,81 @@
 
 > **Invoked via `/claude-api managed-agents-onboard`?** You're in the right place. Run the interview below — don't summarize it back to the user, ask the questions.
 
-Use this when a user wants to set up a Managed Agent from scratch: **branch on know-vs-explore → configure the template → set up the session → pre-flight viability check → emit working code.** The pre-flight check (§3) is not optional — a setup missing a tool, credential, or data access it needs will fail mid-run, and the gap is usually visible at setup time.
+Claude Managed Agents is a hosted agent: Anthropic runs the agent loop and provisions a sandboxed container per session where the agent's tools execute (or your own worker, with a `self_hosted` environment — see `shared/managed-agents-self-hosted-sandboxes.md`). You supply an **agent config** (tools, skills, model, system prompt — reusable, versioned) and an **environment config** (the sandbox — reusable across agents). Each run is a **session**.
 
-> Read `shared/managed-agents-core.md` alongside this — it has full detail for each knob. This doc is the interview script, not the reference.
+The flow is four beats — **describe → agent → environment → session** — the same arc as the Console quickstart, and the same philosophy: **value before credentials**. The user goes from idea to a runnable session before any auth ask; each credential is *flagged* at the moment the design makes it relevant (§2) and *collected* once, at session setup (§4), where it binds (`sessions.create()`) and gets exercised (smoke-test). Read `shared/managed-agents-core.md` alongside this — it has full detail for each knob; this doc is the interview script.
 
 ---
 
-Claude Managed Agents is a hosted agent: Anthropic runs the agent loop on its orchestration layer and provisions a sandboxed container per session where the agent's tools execute (or, with a `self_hosted` environment, your own worker runs the tools — see `shared/managed-agents-self-hosted-sandboxes.md`). You supply the agent config and the environment config; the harness — event stream, sandbox orchestration, prompt caching, context compaction, and extended thinking — is handled for you.
+## 1. Describe the task
 
-**What you supply:**
-- **An agent config** — tools, skills, model, system prompt. Reusable and versioned.
-- **An environment config** — the sandbox your agent's tools execute in (`cloud`: networking, packages; or `self_hosted`: your own infra). Reusable across agents.
+**Open with a one-breath signpost and a single open prompt — don't guess, don't questionnaire.** In your own words:
 
-Each run of the agent is a **session**.
+> Managed Agents is hosted — Anthropic runs the agent loop, the sandbox, and the infrastructure; you just define the agent. We'll do this in three moves: the agent, the environment it runs in, then a live test session. So: describe the agent you want — what should it do, and what kicks it off (a person, an event, a schedule)?
 
----
+Let them answer in full before configuring anything.
 
-## 1. Know or explore?
+## 2. Configure the agent — propose, don't interrogate
 
-Ask the user:
+Their description does the interview's work. Draft the agent config from it and **present it as a proposal with your suggestions inline** — the user reacts to a concrete config instead of answering a question list. At most one batched follow-up for true gaps. Suggest where the description gives you an opening:
 
-> Do you already know the agent you want to build, or would you like to explore some common patterns first?
+- **Tools** — enable the full prebuilt toolset by default (`agent_toolset_20260401`: `bash`, `read`, `write`, `edit`, `glob`, `grep`, `web_fetch`, `web_search`). **Suggest MCP servers** for any third-party service the job names (GitHub, Linear, Slack, …) — and flag the credential each one implies as you suggest it ("Linear MCP → you'll need a Linear API token at kickoff"), so §4's auth step is a formality, not a surprise. Collection itself waits for §4. Custom tools only if the user's own app must answer calls (name, description, input schema — their handler code is theirs; don't generate it).
+- **Skills** — **suggest** prebuilt `xlsx`/`docx`/`pptx`/`pdf` when the job produces those artifacts; custom by `skill_id` (max 20 total per agent, prebuilt + custom combined).
+- **Outcome** — if the description implies checkable "done" criteria (or you can elicit them in the follow-up: not "a good report" but "a CSV with a numeric `price` column per SKU"), **suggest an Outcome kickoff** — the harness grades and iterates against a rubric (`shared/managed-agents-outcomes.md`).
+- **On-hand resources** — repos on disk (`github_repository`: URL, optional `mount_path`/`checkout`; token comes in §4), files to seed (Files API upload → `{type: "file", file_id, mount_path}`; read-only), if the job references them.
+- **Model** — default `claude-opus-5`; `claude-fable-5` for the hardest long-horizon work (`shared/model-migration.md` → Migrating to Claude Fable 5).
 
-### Explore path — show the patterns
+> ‼️ **PR creation needs the GitHub MCP server too** — a `github_repository` mount is filesystem-only. Edit in the mount → push branch via `bash` → open the PR via the MCP `create_pull_request` tool.
 
-Four shapes, same runtime code path (`sessions.create()` → `sessions.events.send()` → stream). Only the trigger and sink differ.
+Full detail per knob: `shared/managed-agents-tools.md` (toolset, MCP, custom tools, skills), `shared/managed-agents-environments.md` (repos, files).
 
-| Pattern | Trigger | Example |
-|---|---|---|
-| Event-triggered | Webhook | GitHub PR push → CMA (GitHub tool) → Slack |
-| Scheduled | Cron | Daily brief: browser + GitHub + Jira → CMA → Slack |
-| Fire-and-forget PR | Human | Slack slash-command → CMA (GitHub tool) → PR passing CI |
-| Research + dashboard | Human | Topic → CMA (web search + `frontend-design` skill) → HTML dashboard |
+## 3. Environment
 
-Ask which shape fits, then continue with the Know path using it as the reference.
+Usually zero or one question:
 
-### Know path — configure template
+- **Reuse or create?** Environments are shared across agents — check for an existing one first.
+- **Networking** — default unrestricted egress. Switch to `limited` only if the user wants egress control — then set `allow_mcp_servers: true` or list every MCP server domain in `allowed_hosts`, or those tools fail silently.
+- **Suggest `self_hosted`** when the signals are there: tools must run on their own infra, secrets can't leave it, or they need binaries/data the cloud container won't have (`shared/managed-agents-self-hosted-sandboxes.md`; not available on Claude Platform on AWS). Otherwise `cloud` — don't raise it unprompted for simple jobs.
 
-Three rounds. Batch the questions in each round; don't ask them one at a time.
+## 4. Session — auth, then test run
 
-**Round A — Tools.** Start here; it's the most concrete part. Three types; ask which the user wants (any combination):
+**Auth happens here — collect the credentials flagged in §2, now that the config is settled:** a vault (existing or `vaults.create()`) + `vaults.credentials.create()` for each MCP server declared in §2, `environment_variable` credentials for API keys the job uses (substituted at egress; the sandbox sees a placeholder), and the `authorization_token` for each repo mount. Credentials are write-only; MCP credentials match servers by URL and auto-refresh. See `shared/managed-agents-tools.md` → Vaults.
 
-| Type | What it is | How to guide |
-|---|---|---|
-| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Ready-to-use: `bash`, `read`, `write`, `edit`, `glob`, `grep`, `web_fetch`, `web_search`. Enable all at once, or individually via `enabled: true/false`. | Recommend enabling the full toolset. List the 8 tools so the user knows what they're getting. Full detail: `shared/managed-agents-tools.md` → Agent Toolset. |
-| **MCP tools** | Third-party integrations (GitHub, Linear, Asana, etc.) via `mcp_toolset`. Credentials live in a vault, not inline. | Ask which services. For each, walk through MCP server URL + vault credentials. Full detail: `shared/managed-agents-tools.md` → MCP Servers + Vaults. |
-| **Custom tools** | The user's own app handles these tool calls — agent fires `agent.custom_tool_use`, the app sends a result message back. | Ask for each tool: name, description, input schema. The app code that handles the event is *their* code — don't generate it. Full detail: `shared/managed-agents-tools.md` → Custom Tools. |
+**Silent viability gate — run this yourself before emitting anything; surface only the gaps.** Walk the job clause by clause: every verb maps to an enabled tool or MCP server ("open a PR" → GitHub MCP, not just the mount); every MCP server and repo mount has its credential from the auth step; every external host is reachable under the networking choice; every file/repo/dataset the job references is mounted; "done" is checkable. If something's missing, say so and resolve it — don't emit a config you already know is under-resourced.
 
-**Round B — Skills, files, and repos.** What the agent has on hand when it starts.
+**Kickoff — pick one, never both:**
+- `user.message` — conversational.
+- `user.define_outcome` + rubric — when §2 settled on an Outcome; the harness iterates and grades until the rubric passes.
+- **Scheduled shape?** Skip per-session kickoff entirely — create a **deployment** (`deployments.create()` with `schedule` + `initial_events`); each firing creates the session autonomously. See `shared/managed-agents-scheduled-deployments.md`.
 
-*Skills* — two types; both work the same way — Claude auto-uses them when relevant. Max 20 per agent.
-- [ ] **Pre-built Agent Skills**: `xlsx`, `docx`, `pptx`, `pdf`. Reference by name.
-- [ ] **Custom Skills**: skills uploaded to the user's org via the Skills API. Reference by `skill_id` + optional `version`. If the skill doesn't exist yet, walk the user through `POST /v1/skills` + `POST /v1/skills/{id}/versions` (beta header `skills-2025-10-02`). Full detail: `shared/managed-agents-tools.md` → Skills + Skills API.
+Mechanics to bake into the runtime code: session creation resolves resources (a bad mount surfaces there, before tokens) but does not itself provision the sandbox; open the event stream *before* sending the kickoff; break on `session.status_terminated`, or `session.status_idle` with a terminal `stop_reason` — anything except `requires_action` (`shared/managed-agents-client-patterns.md` Pattern 5); usage lands on `span.model_request_end`; artifacts land in `/mnt/session/outputs/` (`files.list({scope_id: session.id, ...})`).
 
-*GitHub repositories* — any repos the agent needs on-disk? For each:
-- [ ] Repo URL (`https://github.com/org/repo`)
-- [ ] `authorization_token` (PAT or GitHub App token scoped to the repo)
-- [ ] Optional `mount_path` (defaults to `/workspace/<repo-name>`) and `checkout` (branch or SHA)
+## 5. Integrate — emit the code
 
-Emit as `resources: [{type: "github_repository", url, authorization_token, ...}]`. Full detail: `shared/managed-agents-environments.md` → GitHub Repositories.
+Go straight from the last answer to the code — no preamble, no lecture about setup-vs-runtime; the two-block structure shows it. Generate **two clearly-separated blocks**:
 
-> ‼️ **PR creation needs the GitHub MCP server too.** `github_repository` gives filesystem access only — to open PRs, also attach the GitHub MCP server in Round A and credential it via a vault. The workflow is: edit files in the mounted repo → push branch via `bash` → create PR via the MCP `create_pull_request` tool.
+**Block 1 — Setup (run once, store the IDs).** Prefer **YAML files + `ant` CLI** — agents and environments are version-controlled definitions users should check in and apply from CI:
 
-*Files* — any local files to seed the session with? For each:
-- [ ] Upload via the Files API → persist `file_id`
-- [ ] Choose a `mount_path` — absolute, e.g. `/workspace/data.csv` (parents auto-created; files mount read-only)
-
-Emit as `resources: [{type: "file", file_id, mount_path}]`. Max 999 file resources. Agent working directory defaults to `/workspace`. Full detail: `shared/managed-agents-environments.md` → Files API.
-
-**Round C — Identity, success criteria, environment:**
-- [ ] Name?
-- [ ] Job (one or two sentences — becomes the system prompt)?
-- [ ] **What does "done" look like?** Push for concrete, checkable success criteria — not "a good report" but "a CSV with a numeric `price` column per SKU." Explicit criteria give the agent a clear target and let you verify the result; vague ones leave it guessing what "done" means. If they're gradeable, plan to wire an **Outcome** in §2 so the harness grades-and-revises against them. See `shared/managed-agents-outcomes.md`.
-- [ ] Networking: unrestricted internet from the container, or lock egress to specific hosts? (If locked, MCP server domains must be in `allowed_hosts` or tools silently fail.)
-- [ ] Model? (default `claude-opus-4-8`)
-
----
-
-## 2. Set up the session
-
-Per-run. Points at the agent + environment, attaches credentials, kicks off.
-
-**Vault credentials** (if the agent declared MCP servers, or the job needs an API key for a CLI/SDK/direct API call):
-- [ ] Existing vault, or create one? (`client.beta.vaults.create()` + `vaults.credentials.create()`)
-
-Credentials are write-only. MCP credentials are matched to MCP servers by URL and auto-refreshed; `environment_variable` credentials are substituted into outbound requests at egress (the sandbox sees only a placeholder). See `shared/managed-agents-tools.md` → Vaults.
-
-**Kickoff — pick one:**
-- [ ] **Conversational:** a first `user.message` to the agent.
-- [ ] **Outcome-graded** (recommended when §Round C produced checkable criteria): send a `user.define_outcome` with a rubric *instead of* a `user.message` — the harness iterates and grades against the rubric until satisfied. Don't send both. See `shared/managed-agents-outcomes.md`.
-
-Session creation blocks until all resources mount. Open the event stream before sending the kickoff. Stream is SSE; break on `session.status_terminated`, or on `session.status_idle` with a terminal `stop_reason` — i.e. anything except `requires_action`, which fires transiently while the session waits on a tool confirmation or custom-tool result (see `shared/managed-agents-client-patterns.md` Pattern 5). Usage lands on `span.model_request_end`. Agent-written artifacts end up in `/mnt/session/outputs/` — download via `files.list({scope_id: session.id, betas: ["managed-agents-2026-04-01"]})`.
-
-**Console escape hatch.** In the runtime block you emit, print the session's Console URL right after `sessions.create()` so the user can watch it in the UI while iterating: `print(f"Watch in Console: https://platform.claude.com/workspaces/default/sessions/{session.id}")` (swap `default` for the user's workspace slug if they named one).
-
----
-
-## 3. Pre-flight viability check — reconcile the job against the resources
-
-**Do this before emitting any code.** A common, avoidable failure is an under-resourced run: the ask is clear, but the agent is missing a tool, a credential, data access, or the context to act. The agent discovers the gap a few turns in, flails, and gives up — burning the budget to produce nothing. The gap is usually visible at setup time. Catch it here, not after the session fails.
-
-Walk the stated job clause by clause. For each action the agent must take, confirm a resource covers it — and name the gap out loud if one doesn't:
-
-| Gap class | Check | If missing |
-|---|---|---|
-| **Tool / integration** (most catchable upfront — config is statically inspectable) | Every verb in the job maps to an enabled tool or MCP server. "Triage tickets" → a ticketing MCP server; "open a PR" → GitHub MCP server (a `github_repository` mount alone can't open PRs); "search the web" → `web_search` enabled in the toolset. | Add the tool/MCP server in §Round A, or cut the ask from the job. |
-| **Credential / access** | Every MCP server has a vault credential attached (§2). Every external host the job touches is reachable — networking `unrestricted`, or the host is in `allowed_hosts`. | Create/attach the vault; widen `allowed_hosts`. These don't fail until runtime — the smoke-test in §4 is how you surface them cheaply. |
-| **Data** | Every file, dataset, or repo the job references is mounted as a `resource` (file, `github_repository`, or memory store). | Upload + mount it in §Round B, or tell the agent where to fetch it from. |
-| **Prompt quality / criteria** | The job is specific enough to act on, and "done" is checkable (§Round C). | Tighten the job; wire an Outcome. |
-
-State any unmet gaps to the user and resolve them before generating code. Don't emit a config you already know is under-resourced — an agent can't complete a task it lacks the tools, credentials, or data for.
-
----
-
-## 4. Emit the code
-
-Go straight from the last interview answer to the code — no preamble about the setup-vs-runtime split, no "the critical thing to internalize…", no lecture about `agents.create()` being one-time. The two-block structure below already shows that; don't narrate it. Generate **two clearly-separated blocks**:
-
-**Block 1 — Setup (run once, store the IDs).** Prefer emitting this as **YAML files + `ant` CLI commands** — agents and environments are version-controlled definitions, and the CLI flow is what users should check into their repo and run from CI. Fall back to SDK code only if the user explicitly wants setup in-language or the `ant` CLI is unavailable.
-
-Emit:
-1. `<name>.agent.yaml` with everything from §Round A–C (flat: `name`, `model`, `system`, `tools`, `mcp_servers`, `skills`)
-2. `<name>.environment.yaml` with §Round C networking
-3. The apply commands:
-   ```sh
+1. `<name>.agent.yaml` (flat: `name`, `model`, `system`, `tools`, `mcp_servers`, `skills`) and `<name>.environment.yaml`
+2. ```sh
    AGENT_ID=$(ant beta:agents create < <name>.agent.yaml --transform id -r)
    ENV_ID=$(ant beta:environments create < <name>.environment.yaml --transform id -r)
    # CI sync: ant beta:agents update --agent-id "$AGENT_ID" --version N < <name>.agent.yaml
    ```
 
-See `shared/anthropic-cli.md` for the full CLI reference. If emitting SDK code instead, label it `# ONE-TIME SETUP — run once, save the IDs to config/.env` and call `environments.create()` → `agents.create()`.
+SDK fallback if the user asks — and **required on Claude Platform on AWS**, where auth is SigV4 and the `ant` CLI has no SigV4 mode (use the platform client from `shared/claude-platform-on-aws.md`): label it `# ONE-TIME SETUP — run once, save the IDs` and call `environments.create()` → `agents.create()`.
 
-**Block 2 — Runtime (run on every invocation).** This is SDK code in the detected language (Python/TS/cURL — see SKILL.md → Language Detection). The runtime path needs to react programmatically to events (tool confirmations, custom tool results, reconnect), which is SDK territory — don't emit shell loops here.
-1. Load `env_id` + `agent_id` from config/env
-2. `sessions.create(agent=AGENT_ID, environment_id=ENV_ID, resources=[...], vault_ids=[...])` — this blocks until resources mount, so a bad file/repo mount surfaces *here*, before any tokens are spent.
-3. **Smoke-test first when the job depends on MCP servers, credentials, or reachable hosts.** Credential and MCP-connectivity failures don't surface at `sessions.create()` — only when the agent first tries to use them. Send one cheap probe turn ("Confirm you can reach <service> and list 1–2 items; don't start the task yet"), check it succeeded, *then* send the real kickoff. A few hundred tokens here beats a runaway session that flails on a missing credential and gives up. Skip for agents with no external dependencies.
-4. Open stream, `events.send()` the kickoff (a `user.message`, or a `user.define_outcome` if §2 chose the outcome-graded path), loop until `session.status_terminated` or `session.status_idle && stop_reason.type !== 'requires_action'` (see `shared/managed-agents-client-patterns.md` Pattern 5 for the full gate — do not break on bare `session.status_idle`)
+> ⚠️ **Deployments are newer than the rest of the MA surface.** Before emitting `ant beta:deployments …` or `client.beta.deployments` / `client.beta.deployment_runs` calls, verify the user's installed CLI/SDK exposes them (`ant beta:deployments --help`; `hasattr(client.beta, "deployments")`). If not, emit raw HTTP against `POST /v1/deployments` with the `managed-agents-2026-04-01` beta header (plus `oauth-2025-04-20` when authenticating with a Bearer token from `ant auth print-credentials`), and leave an upgrade note marking what simplifies to SDK calls.
 
-> ⚠️ **Never emit `agents.create()` and `sessions.create()` in the same unguarded block.** That teaches the user to create a new agent on every run — the #1 anti-pattern. If they need a single script, wrap agent creation in `if not os.getenv("AGENT_ID"):`.
+**Scheduled shape? The deployment is setup, not runtime.** Create it in Block 1, after the agent/environment IDs exist (`deployments.create()` with `schedule` + `initial_events`). Block 2 is then **not** a session loop — there is no per-run kickoff to send. Emit instead: a manual-run trigger (`POST /v1/deployments/{id}/run`) so the user can test now rather than wait for the first firing — the manual run doubles as the smoke test — plus a fetch helper (latest `deployment_runs` entry → `session_id` → Console URL + `files.list(scope_id=session_id)` for the artifacts).
 
-Pull exact syntax from `python/managed-agents/README.md`, `typescript/managed-agents/README.md`, or `curl/managed-agents.md`. Don't invent field names.
+**Block 2 — Runtime (every invocation; conversational and Outcome shapes).** SDK code in the detected language (Python/TS/cURL — SKILL.md → Language Detection); don't emit shell loops here:
+
+1. Load `agent_id` + `env_id` from config/env
+2. `sessions.create(agent=AGENT_ID, environment_id=ENV_ID, resources=[...], vault_ids=[...])`, then print the Console URL so the user can watch live: `https://platform.claude.com/workspaces/default/sessions/{session.id}` (swap `default` for their workspace slug)
+3. **Smoke-test when the job depends on MCP servers, credentials, or locked-down hosts** — those failures don't surface at `sessions.create()`, only on first use. One cheap probe turn ("Confirm you can reach <service> and list 1–2 items; don't start the task"), verify, then send the real kickoff. Skip when there are no external dependencies.
+4. Open stream → send the §4 kickoff → loop with the terminal gate from §4.
+
+> ⚠️ **Never emit `agents.create()` and `sessions.create()` in the same unguarded block** — that teaches creating a new agent per run, the #1 anti-pattern. Single-script requests: wrap creation in `if not os.getenv("AGENT_ID"):`.
+
+Pull exact syntax from `{lang}/managed-agents/README.md` for your detected language (cURL and C#: use `curl/managed-agents.md` as the wire-level reference). Don't invent field names.

skills/claude-api/shared/managed-agents-outcomes.md

@@ -10,6 +10,8 @@ The SDK sets the `managed-agents-2026-04-01` beta header automatically on all `c
 
 Outcomes are not a field on `sessions.create()`. You create a normal session, then send a `user.define_outcome` event. The agent starts working on receipt — **do not also send a `user.message`** to kick it off.
 
+You can collapse both calls into one by passing a single `user.define_outcome` in the session's `initial_events` array — same event, same rules, one round trip (see `shared/managed-agents-core.md` → Seeding a session with `initial_events`). More than one `user.define_outcome` in that array, or one without a `rubric`, rejects the whole create with a 400.
+
 ```python
 session = client.beta.sessions.create(
     agent=AGENT_ID,
@@ -62,7 +64,7 @@ These appear on the standard event stream (`sessions.events.stream` / `.list`) a
 | `needs_revision` | Agent starts another iteration. |
 | `max_iterations_reached` | No further grader cycles. Agent may run one final revision, then session → `idle`. |
 | `failed` | Session → `idle`. Rubric fundamentally doesn't match the task (e.g. description and rubric contradict). |
-| `interrupted` | Only emitted if `_start` had already fired before a `user.interrupt` arrived. |
+| `interrupted` | Emitted whenever a `user.interrupt` arrives while an outcome is active — **even if evaluation hadn't started**. In that case `outcome_evaluation_start_id` is an empty string rather than an event ID, so don't use it as a lookup key without checking. |
 
 ```json
 {

skills/claude-api/shared/managed-agents-overview.md

@@ -15,7 +15,7 @@ Every session references a pre-created `/v1/agents` object. Create the agent onc
 
 If you're about to write `sessions.create()` with `model`, `system`, or `tools` on the session body — **stop**. Those fields live on `agents.create()`. The session takes a *pointer* only.
 
-**When generating code, separate setup from runtime.** `agents.create()` belongs in a setup script (or a guarded `if agent_id is None:` block), not at the top of the hot path. If the user's code calls `agents.create()` on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: create once → persist the ID (config file, env var, secrets manager) → every run loads the ID and calls `sessions.create()`.
+**When generating code, separate setup from runtime.** `agents.create()` belongs in a setup script (or a guarded `if agent_id is None:` block), not at the top of the hot path. If the user's code calls `agents.create()` on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: define the agent as a version-controlled YAML manifest, apply it once with `ant beta:agents create < agent.yaml` (or a guarded setup script — see `shared/anthropic-cli.md`), persist the returned ID (config file, env var, secrets manager), and have every run load the ID and call `sessions.create()`.
 
 **To change the agent's behavior, use `POST /v1/agents/{id}` — don't create a new one.** Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via `{type: "agent", id, version}`). See `shared/managed-agents-core.md` → Agents → Versioning. To change `tools`/`mcp_servers`/`vault_ids` on **one running session** without touching the agent object, use `sessions.update()` — see `shared/managed-agents-core.md` → Updating the agent configuration mid-session.
 
@@ -29,7 +29,7 @@ Managed Agents is in beta. The SDK sets required beta headers automatically:
 | `skills-2025-10-02`            | Skills API (for managing custom skill definitions)   |
 | `files-api-2025-04-14`         | Files API for file uploads                           |
 
-**Which beta header goes where:** The SDK sets `managed-agents-2026-04-01` automatically on `client.beta.{agents,environments,sessions,vaults,memory_stores,deployments,deployment_runs}.*` calls, and `files-api-2025-04-14` / `skills-2025-10-02` automatically on `client.beta.files.*` / `client.beta.skills.*` calls. You do NOT need to add the Skills or Files beta header when calling Managed Agents endpoints. **Exception — session-scoped file listing:** `client.beta.files.list({scope_id: session.id})` is a Files endpoint that takes a Managed Agents parameter, so it needs **both** headers. Pass `betas: ["managed-agents-2026-04-01"]` explicitly on that call (the SDK adds the Files header; you add the Managed Agents one). See `shared/managed-agents-environments.md` → Session outputs.
+**Which beta header goes where:** The SDK sets `managed-agents-2026-04-01` automatically on `client.beta.{agents,environments,sessions,vaults,memory_stores,deployments,deployment_runs}.*` calls, and `files-api-2025-04-14` / `skills-2025-10-02` automatically on `client.beta.files.*` / `client.beta.skills.*` calls. You do NOT need to add the Skills or Files beta header when calling Managed Agents endpoints. On raw HTTP the Managed Agents header **grants Files API access on its own**, so uploading a file for use as a session resource does not need `files-api-2025-04-14` alongside it. (Direct Skills API calls over cURL do still need `skills-2025-10-02`; the `ant` CLI and the SDKs send it for you.) **Exception — session-scoped file listing:** `client.beta.files.list({scope_id: session.id})` is a Files endpoint that takes a Managed Agents parameter, so it needs **both** headers. Pass `betas: ["managed-agents-2026-04-01"]` explicitly on that call (the SDK adds the Files header; you add the Managed Agents one). See `shared/managed-agents-environments.md` → Session outputs.
 
 
 ## Reading Guide
@@ -41,7 +41,7 @@ Managed Agents is in beta. The SDK sets required beta headers automatically:
 | See the full endpoint reference        | `shared/managed-agents-api-reference.md`                |
 | **Create an agent** (required first step) | `shared/managed-agents-core.md` (Agents section) + language file |
 | Update/version an agent                | `shared/managed-agents-core.md` (Agents → Versioning) — update, don't re-create |
-| Create a session                       | `shared/managed-agents-core.md` + `{lang}/managed-agents/README.md` |
+| Create a session                       | `shared/managed-agents-core.md` + `{lang}/managed-agents/README.md` (cURL/C#: `curl/managed-agents.md`) |
 | Configure tools and permissions        | `shared/managed-agents-tools.md`                        |
 | Set up MCP servers                     | `shared/managed-agents-tools.md` (MCP Servers section)  |
 | Stream events / handle tool_use        | `shared/managed-agents-events.md` + language file       |
@@ -65,7 +65,7 @@ Managed Agents is in beta. The SDK sets required beta headers automatically:
 - **Reconcile resources before the first run** — a session with a clear ask but a missing tool, credential, data mount, or context will discover the gap mid-run, then flail and give up. Before creating the session, check that every action in the task maps to a configured tool/MCP server, every MCP server has a vault credential, and every referenced file/host is mounted/reachable. When helping a user set one up, run the reconciliation in `shared/managed-agents-onboarding.md` → §3 Pre-flight viability check.
 - **Stream to get events** — `GET /v1/sessions/{id}/events/stream` is the primary way to receive agent output in real-time.
 - **SSE stream has no replay — reconnect with consolidation** — if the stream drops while a `agent.tool_use`, `agent.mcp_tool_use`, or `agent.custom_tool_use` is pending resolution (`user.tool_confirmation` for the first two, `user.custom_tool_result` for the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream with `GET /v1/sessions/{id}/events/stream` , fetch `GET /v1/sessions/{id}/events`, dedupe by event ID, then proceed. See `shared/managed-agents-events.md` → Reconnecting after a dropped stream.
-- **Don't trust HTTP-library timeouts as wall-clock caps** — `requests` `timeout=(c, r)` and `httpx.Timeout(n)` are *per-chunk* read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track `time.monotonic()` at the loop level and bail explicitly. Prefer the SDK's `sessions.events.stream()` / `session.events.list()` over hand-rolled HTTP. See `shared/managed-agents-events.md` → Receiving Events.
+- **Don't trust HTTP-library timeouts as wall-clock caps** — `requests` `timeout=(c, r)` and `httpx.Timeout(n)` are *per-chunk* read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track `time.monotonic()` at the loop level and bail explicitly. Prefer the SDK's `sessions.events.stream()` / `sessions.events.list()` over hand-rolled HTTP. See `shared/managed-agents-events.md` → Receiving Events.
 - **Messages queue** — you can send events while the session is `running` or `idle`; they're processed in order. No need to wait for a response before sending the next message.
 - **Environment `config.type` is `"cloud"` or `"self_hosted"`** — `cloud` runs the container on Anthropic's infrastructure; `self_hosted` moves tool execution to your own (see `shared/managed-agents-self-hosted-sandboxes.md`).
 - **Archive is permanent on every resource** — archiving an agent, environment, session, vault, credential, or memory store makes it read-only with no unarchive. For agents, environments, and memory stores specifically, archived resources cannot be referenced by new sessions (existing sessions continue). Do not call `.archive()` on a production agent, environment, or memory store as cleanup — **always confirm with the user before archiving**.

skills/claude-api/shared/managed-agents-scheduled-deployments.md

@@ -9,7 +9,7 @@ Requires the `managed-agents-2026-04-01` beta header (the SDK sets it automatica
 A deployment bundles everything a session needs (agent, environment, optional files / GitHub / memory stores / vaults) plus a `schedule` and the `initial_events` that kick off each run:
 
 - `agent` and `environment_id` are required — same shapes as `sessions.create` (see `shared/managed-agents-core.md`).
-- `initial_events` must contain the starting `user.message`.
+- `initial_events` must contain at least one starting event — a `user.message` **or** a `user.define_outcome`. (A deployment's `initial_events` also accepts `system.message`, which a session's does not.)
 - `schedule` takes a cron `expression` and an IANA `timezone`. Minute-level granularity is the maximum.
 
 ```bash
@@ -71,7 +71,7 @@ The response is a deployment object (`depl_` ID prefix). Check `schedule.upcomin
 }
 ```
 
-Deployments may apply up to **10 seconds of jitter** to distribute load. Maximum **1000 scheduled deployments per organization** (contact Anthropic support for more).
+`upcoming_runs_at` reflects the exact configured schedule, but **execution is jittered to distribute load: up to 15% of the interval between runs, floored at 5 seconds and capped at 9 minutes.** An hourly deployment can therefore fire up to 9 minutes late; don't build a downstream deadline that assumes the listed timestamp. Maximum **1000 scheduled deployments per organization** (contact Anthropic support for more).
 
 ### Cron and timezone semantics
 
@@ -104,7 +104,7 @@ for await (const run of client.beta.deploymentRuns.list({
 }
 ```
 
-Raw HTTP: `GET /v1/deployment_runs?deployment_id=...&has_error=true`.
+Raw HTTP: `GET /v1/deployment_runs?deployment_id=...&has_error=true`. To retrieve a single run by ID, `GET /v1/deployment_runs/{deployment_run_id}` (SDK: `client.beta.deployment_runs.retrieve(run_id)`) — a `deployment_run.*` webhook event carries the run ID as its `data.id`.
 
 A failed run looks like:
 
@@ -123,6 +123,8 @@ A failed run looks like:
 
 Error types include `environment_archived`, `agent_archived`, `vault_not_found`, `session_rate_limited`, and `service_unavailable`.
 
+The outcome of each **scheduled** run (started/succeeded/failed) and each deployment lifecycle change (created/updated/paused/unpaused/archived/deleted) is also delivered as a webhook event — see `shared/managed-agents-webhooks.md` for the `deployment.*` and `deployment_run.*` event types — so you can react without polling. Manual runs do **not** emit `deployment_run.*` webhook events.
+
 ## Lifecycle: pause / unpause / archive
 
 | Operation | SDK | Effect |
@@ -137,7 +139,7 @@ Raw HTTP: `POST /v1/deployments/{deployment_id}/pause` (likewise `/unpause`, `/a
 
 - **Rate-limited:** recorded immediately as a `session_rate_limited` run, **no retry** — the schedule simply tries again at the next occurrence. (Rate limits on API calls *inside* a session are handled by the session itself.)
 - **Other failed runs** (e.g. `environment_archived`, `vault_not_found`, `service_unavailable`): the run records the `error.type` — monitor runs and fix the referenced resource, or pause the deployment.
-- **Agent archived or deleted:** the deployment is automatically **archived** (terminal) and no further sessions are created.
+- **Agent archived:** the deployment is automatically **archived** (terminal) in the same operation. **Agent deleted:** the next scheduled trigger detects the missing agent and archives the deployment then. Either way no deployment run is recorded, and no further sessions are created.
 
 ## Manual runs
 

skills/claude-api/shared/managed-agents-tools.md

@@ -70,7 +70,7 @@ Control when server-executed tools (agent toolset + MCP) run automatically vs wa
 | Policy | Behavior |
 |---|---|
 | `always_allow` | Tool executes automatically (default) |
-| `always_ask` | Session emits `session.status_idle` and pauses until you send a `tool_confirmation` event |
+| `always_ask` | Session emits `session.status_idle` and pauses until you send a `user.tool_confirmation` event |
 
 ```json
 {
@@ -88,8 +88,8 @@ Control when server-executed tools (agent toolset + MCP) run automatically vs wa
 **Responding to `always_ask`:** Send a `user.tool_confirmation` event with `tool_use_id` from the triggering `agent_tool_use`/`mcp_tool_use` event:
 
 ```json
-{ "type": "tool_confirmation", "tool_use_id": "sevt_abc123", "result": "allow" }
-{ "type": "tool_confirmation", "tool_use_id": "sevt_def456", "result": "deny", "message": "Read .env.example instead" }
+{ "type": "user.tool_confirmation", "tool_use_id": "sevt_abc123", "result": "allow" }
+{ "type": "user.tool_confirmation", "tool_use_id": "sevt_def456", "result": "deny", "message": "Read .env.example instead" }
 ```
 
 The optional `message` on a deny is delivered to the agent so it can adjust its approach.
@@ -184,7 +184,7 @@ This keeps secrets out of reusable agent definitions. Each vault credential is t
 
 > 💡 **Changing tools/MCP servers on a running session:** `sessions.update()` can replace `agent.tools`, `agent.mcp_servers`, and `vault_ids` while the session is `idle` — a session-local override that doesn't touch the agent object. See `shared/managed-agents-core.md` → Updating the agent configuration mid-session.
 
-**Large MCP tool outputs.** If an MCP tool returns more than **100K tokens**, the output is automatically offloaded to a file in the sandbox — the agent receives a truncated preview plus the file path and can `read` the full content. No configuration required.
+**Large tool outputs.** If a tool returns more than **100,000 characters (roughly 25,000 tokens)**, the output is automatically offloaded to a file in the sandbox — the agent receives a truncated preview plus the file path and can `read` the full content. No configuration required. The threshold is in *characters*, not tokens, and applies to built-in agent tools as well as MCP tools.
 
 **Invalid vault credentials don't block session creation.** If a vault credential is invalid for a declared MCP server, the session still creates successfully; a `session.error` event describes the MCP auth failure, and auth retries on the next `session.status_idle` → `session.status_running` transition.
 
@@ -194,7 +194,7 @@ This keeps secrets out of reusable agent definitions. Each vault credential is t
 
 **Vaults** store credentials that Anthropic manages on your behalf. Two credential categories:
 
-- **MCP credentials** (`mcp_oauth`, `static_bearer`) — keyed by `mcp_server_url`. When the agent connects to a server at that URL, the token is injected automatically. `mcp_oauth` tokens are auto-refreshed via the standard OAuth 2.0 `refresh_token` grant. This is the only way to authenticate MCP servers.
+- **MCP credentials** (`mcp_oauth`, `static_bearer`) — keyed by `mcp_server_url`. When the agent connects to a server at that URL, the token is injected automatically. **Matching is normalized, not byte-exact:** scheme and host are lowercased, and default ports and trailing slashes are stripped, so host casing, an explicit default port, or a trailing slash won't break the match. A different path, subdomain, or *non-default* port will. If nothing matches, the connection is attempted unauthenticated. `mcp_oauth` tokens are auto-refreshed via the standard OAuth 2.0 `refresh_token` grant. This is the only way to authenticate MCP servers.
 - **Environment variables** (`environment_variable`) — keyed by `secret_name` (the env var name). The sandbox sees only an **opaque placeholder**; the real secret is substituted into the outbound request **at egress**. Use this for any service that authenticates through an environment variable: CLIs (`aws`, `gcloud`, `stripe`), SDKs, or direct `curl` calls from the `bash` tool.
 
 Secret fields you supply (`token`, `access_token`, `refresh_token`, `client_secret`, `secret_value`) are write-only — never returned in API responses.
@@ -205,7 +205,7 @@ Vaults store credentials; those credentials **never enter the sandbox**. This is
 
 - **MCP tool calls** are routed through an Anthropic-side proxy that fetches the credential from the vault and adds it to the outbound request.
 - **Git operations on attached GitHub repositories** (`git pull`, `git push`, GitHub REST calls) are routed through a git proxy that injects the `github_repository` resource's `authorization_token` the same way.
-- **Environment-variable credentials** appear in the sandbox as an opaque placeholder; the real value replaces the placeholder at egress, on requests to the credential's allowed hosts only.
+- **Environment-variable credentials** appear in the sandbox as an opaque placeholder; the real value replaces the placeholder at egress, on requests to the credential's allowed hosts only. Substitution covers request **headers and body only** — a secret embedded in the **URL path** is never substituted, so path-secret endpoints (e.g. Slack incoming-webhook URLs) can't be vaulted; use header-based auth instead (for Slack: a bot token in `Authorization` via `chat.postMessage`).
 
 **When vault credentials don't fit** (e.g. self-hosted sandboxes — `environment_variable` is not yet supported there), **register a custom tool:** the agent emits `agent.custom_tool_use`, your orchestrator (which already holds the credential) executes the call and returns `user.custom_tool_result` over the same authenticated event stream. No public endpoint is exposed; the sandbox never sees the secret. See `shared/managed-agents-client-patterns.md` → Pattern 9.
 
@@ -271,6 +271,17 @@ Omit `refresh` entirely if you only have an access token with no refresh capabil
 
 `networking.allowed_hosts` controls which outbound hosts the secret can be substituted for — `{"type": "limited", "allowed_hosts": [...]}` or `{"type": "unrestricted"}` if you can't enumerate the domains in advance. Limiting is strongly recommended: it prevents the key from ever being sent to unauthorized hosts.
 
+**`injection_location`** (optional, sibling of `networking`) controls **where** in the outbound request the secret is substituted — `{header: bool, body: bool}`. The two are independent: `allowed_hosts` scopes *which hosts* a substituted request can target; `injection_location` scopes *which parts of the request* the secret is substituted into across all of those hosts. Most services read an API key from a request header, so `{"header": true}` is the narrower configuration — request bodies are often assembled from content the agent is working with, making the body the broader exposure surface. A placeholder in a disabled location is **neither substituted nor stripped** — the literal opaque placeholder string is sent to the third party in that location.
+
+| Operation | `injection_location` semantics |
+|---|---|
+| Create credential | Omit the field entirely → both locations enabled. Provide the object → any field you omit defaults to `false` (`{"header": true}` creates a header-only credential). |
+| Update credential | Fields **merge individually** — `{"body": false}` disables body substitution and leaves `header` unchanged. For a running session, the update takes effect on the session's next operation. |
+
+A credential must have at least one location enabled; a create or update that would disable both returns 400, as does explicit `null` for the object or either field (omit instead). The response always returns both fields with their resolved values.
+
+> ⚠️ **Credentials created in the Console are header-only by default** — unlike the API, where omitting the field enables both. If your client sends the secret in the request body (a form-encoded token request, for example), the placeholder passes through literally and the service rejects it with its own authentication error. Tick body injection in the Console form, or `POST` the credential with `{"injection_location": {"body": true}}`.
+
 > ⚠️ **Two networking layers, both required.** `networking.allowed_hosts` on the credential controls which requests *use the secret*, not which requests are *allowed*. The agent must also be able to reach the domain at the **environment level** (`unrestricted`, or the host listed in the environment's `allowed_hosts` — see `shared/managed-agents-environments.md`). A domain missing from either layer means the secret-substituted request fails.
 
 > ⚠️ **Client-side validation caveat.** Substitution happens at egress, not inside the sandbox — clients that validate the credential *format* locally before making a network request (e.g. a CLI that checks the key starts with `sk-`) will see the opaque placeholder and may fail at startup. If a client rejects the credential before any network call, that's why.
@@ -282,7 +293,7 @@ Omit `refresh` entirely if you only have an access token with no refresh capabil
 **Constraints (all credential types):**
 
 - **Unique key per vault.** `mcp_server_url` (MCP credentials) and `secret_name` (environment-variable credentials) must be unique among active credentials in a vault; duplicates return a 409.
-- **Keys are immutable.** Secret values and `display_name` can be updated (rotation); to change `mcp_server_url`, `secret_name`, `token_endpoint`, or `client_id`, archive the credential and create a new one. Archiving purges the secret and frees the key for a replacement.
+- **Keys are immutable.** Secret values, `display_name`, and (on environment-variable credentials) `injection_location` can be updated; to change `mcp_server_url`, `secret_name`, `token_endpoint`, or `client_id`, archive the credential and create a new one. Archiving purges the secret and frees the key for a replacement.
 - **Maximum 20 credentials per vault.**
 - Credentials are stored as provided and **not validated until session runtime** — an invalid credential surfaces as an authentication or downstream error during the session, which is emitted but does not block the session from continuing.
 
@@ -311,7 +322,7 @@ Skills are attached to the **agent** definition via `agents.create()`:
 const agent = await client.beta.agents.create(
   {
     name: "Financial Agent",
-    model: "claude-opus-4-8",
+    model: "claude-opus-5",
     system: "You are a financial analysis agent.",
     skills: [
       { type: "anthropic", skill_id: "xlsx" },
@@ -326,7 +337,7 @@ Python:
 ```python
 agent = client.beta.agents.create(
     name="Financial Agent",
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     system="You are a financial analysis agent.",
     skills=[
         {"type": "anthropic", "skill_id": "xlsx"},
@@ -341,7 +352,9 @@ agent = client.beta.agents.create(
 |---|---|---|
 | `type` | `"anthropic"` | `"custom"` |
 | `skill_id` | Skill name (e.g. `"xlsx"`, `"docx"`, `"pptx"`, `"pdf"`) | Skill ID from Skills API (e.g. `"skill_abc123"`) |
-| `version` | — | `"latest"` or a specific version number |
+| `version` | `"latest"` or a specific version number | `"latest"` or a specific version number |
+
+`version` is optional on **both** kinds and defaults to `"latest"` — it is not custom-skill-only.
 
 ### Skills API
 

skills/claude-api/shared/managed-agents-webhooks.md

@@ -13,14 +13,14 @@ Console → **Manage → Webhooks**. There is no programmatic endpoint-managemen
 | Field | Constraint |
 |---|---|
 | URL | HTTPS on port 443, publicly resolvable hostname |
-| Event types | Subscribe per `data.type` — you only receive subscribed types (plus test events) |
+| Event types | Subscribe per `data.type` — an endpoint receives only the types it is subscribed to |
 | Signing secret | `whsec_`-prefixed, 32 bytes, **shown once at creation** — store it |
 
 ---
 
 ## Verify the signature
 
-Every delivery is HMAC-signed. **Use the SDK's `client.beta.webhooks.unwrap()`** — it verifies the signature, rejects payloads more than ~5 minutes old, and returns the parsed event. It reads the `whsec_` secret from `ANTHROPIC_WEBHOOK_SIGNING_KEY`.
+Every delivery carries the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. **Use the SDK's `client.beta.webhooks.unwrap()`** — it verifies the signature, rejects payloads more than ~5 minutes old, and returns the parsed event. It reads the `whsec_` secret from `ANTHROPIC_WEBHOOK_SIGNING_KEY`. Pass the headers through untouched; don't hand-roll verification against a single `X-Webhook-Signature` header, which is not the wire format.
 
 ```python
 import anthropic
@@ -63,7 +63,7 @@ Pass the **raw request body** to `unwrap()` — frameworks that re-serialize JSO
 ```json
 {
   "type": "event",
-  "id": "event_01ABC...",
+  "id": "whe_9d5c1f7e...",
   "created_at": "2026-03-18T14:05:22Z",
   "data": {
     "type": "session.status_idled",
@@ -74,7 +74,9 @@ Pass the **raw request body** to `unwrap()` — frameworks that re-serialize JSO
 }
 ```
 
-Switch on `data.type`, fetch the resource by `data.id`, return any **2xx** to acknowledge. `created_at` is when the *state transition* happened, not when the webhook fired.
+Switch on `data.type`, fetch the resource by `data.id`, return any **2xx** to acknowledge. `created_at` is when the *event occurred*, not when the delivery was attempted — the `webhook-timestamp` header is the clock for the attempt (see Delivery behavior).
+
+The top-level `id` is the same value as the `webhook-id` header, and it is per *event*, not per delivery — every retry carries it unchanged. Dedupe on it.
 
 ---
 
@@ -85,17 +87,43 @@ Switch on `data.type`, fetch the resource by `data.id`, return any **2xx** to ac
 | `session.status_scheduled` | Session created and ready to accept events |
 | `session.status_run_started` | Agent execution kicked off (every transition to `running`) |
 | `session.status_idled` | Agent awaiting input (tool approval, custom tool result, or next message) |
-| `session.status_terminated` | Session hit a terminal error |
+| `session.status_rescheduled` | A transient error occurred; the session is retrying automatically |
+| `session.status_terminated` | Session ended — **on completion or on error**, not error-only |
 | `session.thread_created` | Multiagent: coordinator opened a new subagent thread |
 | `session.thread_idled` | Multiagent: a subagent thread is waiting for input |
+| `session.thread_terminated` | A thread ended — child completed its work, or the thread was archived. **Child threads only**; the primary thread's end surfaces as `session.status_terminated` |
 | `session.outcome_evaluation_ended` | Outcome grader finished one iteration |
+| `session.updated` | Session properties changed (name, configuration) |
+| `session.deleted` | Session permanently deleted — no object left to fetch; treat the event itself as final |
 | `vault.archived` | Vault was archived |
 | `vault.created` | Vault was created |
-| `vault.deleted` | Vault was deleted |
-| `vault_credential.archived` | Vault credential was archived |
+| `vault.deleted` | Vault was deleted — a `vault_credential.deleted` also fires per underlying credential. No object left to fetch; treat the event itself as final |
+| `vault_credential.archived` | Credential archived, directly or via vault archival |
 | `vault_credential.created` | Vault credential was created |
-| `vault_credential.deleted` | Vault credential was deleted |
+| `vault_credential.deleted` | Credential deleted, directly or via vault deletion. No object left to fetch; treat the event itself as final |
 | `vault_credential.refresh_failed` | MCP OAuth vault credential failed to refresh |
+| `agent.created` | Agent created |
+| `agent.updated` | A new agent version was published. Updates that do not create a new version do **not** fire this. |
+| `agent.archived` | Agent archived |
+| `agent.deleted` | Agent permanently deleted — no object left to fetch; treat the event itself as final |
+| `deployment.created` | Scheduled deployment created |
+| `deployment.updated` | Deployment properties changed (e.g. schedule edited) |
+| `deployment.paused` | Deployment paused — by request, or automatically when a scheduled run fails with a **non-recoverable** error (archived agent, missing environment). Recoverable failures, including rate limits, do **not** auto-pause. |
+| `deployment.unpaused` | Deployment unpaused; schedule resumes |
+| `deployment.archived` | Deployment archived — directly, or as a result of agent archival/deletion |
+| `deployment.deleted` | Deployment permanently deleted — no object left to fetch; treat the event itself as final |
+| `deployment_run.started` | A **scheduled** run started. Manual runs do **not** emit `deployment_run.*` events. |
+| `deployment_run.succeeded` | Scheduled run created its session. Same `data.id` (the run ID) as the run's `.started` event — fetch the deployment run for its `session_id`, then subscribe to the session events to follow the work. |
+| `deployment_run.failed` | Scheduled run did not create a session. Same `data.id` as the run's `.started` event — fetch the deployment run for `error.type` / `error.message`. |
+| `environment.created` | Environment created |
+| `environment.updated` | Environment updated with at least one changed field. A no-op update emits nothing. |
+| `environment.archived` | Environment archived. Re-archiving an already-archived environment emits nothing. |
+| `environment.deleted` | Environment deleted, including delete of an already-archived one. No object left to fetch; treat the event itself as final |
+| `memory_store.created` | Memory store created — by you, or by an Anthropic-operated process that clones one of your stores |
+| `memory_store.archived` | Memory store archived. Re-archiving an already-archived store emits nothing. |
+| `memory_store.deleted` | Memory store deleted, including delete of an already-archived one. Cascades to its memories and versions **without** per-memory events — this single event is the signal. No object left to fetch; treat it as final |
+
+> **There is deliberately no `memory_store.updated`.** Individual memories and memory versions emit no webhook events at all, and neither do an environment's self-hosted work items. If you need per-memory change tracking, poll the memory-versions endpoints (`shared/managed-agents-memory.md`).
 
 > These are **webhook** `data.type` values — a separate namespace from SSE event types (`session.status_idle`, `span.outcome_evaluation_end`, etc. in `shared/managed-agents-events.md`). Don't reuse SSE constants in webhook handlers.
 
@@ -103,8 +131,13 @@ Switch on `data.type`, fetch the resource by `data.id`, return any **2xx** to ac
 
 ## Delivery behavior & pitfalls
 
-- **No ordering guarantee.** `session.status_idled` may arrive before `session.outcome_evaluation_ended` even if the evaluation finished first. Sort by envelope `created_at` if order matters.
-- **Retries carry the same `event.id`.** At least one retry on non-2xx. Dedupe on `event.id`.
-- **3xx is failure.** Redirects are not followed — update the URL in Console if your endpoint moves.
-- **Auto-disable** after ~20 consecutive failed deliveries, or immediately if the hostname resolves to a private IP or returns a redirect. Re-enable manually in Console.
+- **Duplicates.** An endpoint can receive the same event more than once; every attempt carries the same top-level `event.id` (= the `webhook-id` header). Dedupe on it.
+- **Subscription scope.** An event reaches only endpoints subscribed to its type **at the moment it is emitted**. An event emitted while nothing was subscribed is never delivered, and subscribing later does not backfill — subscribe before you need the type.
+- **No ordering guarantee.** Events are not delivered in occurrence order: `session.status_idled` may arrive before `session.outcome_evaluation_ended`, and a `.deleted` can arrive before the `.archived` for the same resource. **Drive state from the resource you fetch, not from arrival order.**
+- **Retries: up to three attempts** per endpoint per event, with jittered exponential backoff between 5 and 120 seconds. A response that triggers auto-disable is never retried. **After the last attempt fails the event is dropped** — not queued, and with no signal that it was lost. Webhooks are not a durable log: if you must observe every transition, reconcile by listing or fetching the resource.
+- **`webhook-timestamp` is re-stamped on every attempt**, so retries don't fail the SDK's five-minute freshness check. It times the *delivery attempt*; use the payload's `created_at` for when the event occurred.
+- **Auto-disable — three triggers**, each setting `disabled_reason`, all reversible from Console (events emitted while disabled are **not** replayed):
+  - A `3xx` response. Redirects are never followed; disables immediately, on the first attempt. Reason: `auto-disabled: endpoint URL returned a redirect (3xx)`.
+  - The URL resolves to a non-public IP at connect time. Disables immediately. Reason: `auto-disabled: endpoint URL resolved to an invalid address`.
+  - Continuous failure for a sustained period. Reason: `auto-disabled after sustained delivery failures`. **The trigger is duration, not a delivery count** — a single `2xx` resets the window, so one flaky event can't disable the endpoint.
 - **Thin payload is intentional.** Don't expect `stop_reason`, `outcome_evaluations`, credential secrets, etc. on the webhook body — fetch the resource.

skills/claude-api/shared/model-migration.md

@@ -19,7 +19,11 @@ For the latest, authoritative version (with code samples in every supported lang
 | Opus 4.7 Migration Checklist | The required vs optional items for 4.7, tagged `[BLOCKS]` / `[TUNE]` |
 | Migrating to Opus 4.8 | Migrating to Opus 4.8 (no new breaking changes; mid-session system prompts; behavioral re-tuning) |
 | Opus 4.8 Migration Checklist | The required vs optional items for 4.8, tagged `[BLOCKS]` / `[TUNE]` |
-| Migrating to Claude Fable 5 | Migrating to Claude Fable 5 or Claude Mythos 5 (always-on protected thinking, new tokenizer, refusal handling, data retention, behavioral shifts + prompting guidance) |
+| Migrating to Claude Opus 5 | Migrating Opus 4.8 → Claude Opus 5 (thinking-disabled effort-gated; mid-conversation tool changes; per-turn effort and task budget; verbosity, over-verification, and scope re-tuning) |
+| Claude Opus 5 Migration Checklist | The required vs optional items for Claude Opus 5, tagged `[BLOCKS]` / `[TUNE]` |
+| Migrating to Claude Sonnet 5 | Migrating Sonnet 4.6 → Claude Sonnet 5 (adaptive thinking on by default; non-default sampling params 400; new tokenizer; `xhigh` effort for coding/agentic; high-res vision; behavioral re-tuning) |
+| Claude Sonnet 5 Migration Checklist | The required vs optional items, tagged `[BLOCKS]` / `[TUNE]` |
+| Migrating to Claude Fable 5 | Migrating to Claude Fable 5 or Claude Mythos 5 (always-on thinking, raw chain of thought never returned, refusal handling, data retention, behavioral shifts + prompting guidance) |
 | Claude Fable 5 Migration Checklist | The required vs optional items for Claude Fable 5, tagged `[BLOCKS]` / `[TUNE]` |
 | Verify the Migration | After edits — runtime spot-check |
 
@@ -69,7 +73,7 @@ Not every file that contains the old model ID is a **caller** of the API. Before
 | 1 | **Calls the API/SDK** | `client.messages.create(model=…)`, `anthropic.Anthropic()`, request payloads | Swap the model ID **and** apply the breaking-change checklist for the target version (below). |
 | 2 | **Defines or serves the model** | Model registries, OpenAPI specs, routing/queue configs, model-policy enums, generated catalogs | The old entry **stays** (the model is still served). Ask whether to (a) add the new model alongside, (b) leave alone, or (c) retire the old model — never blind-replace. **If you can't ask, default to (a): add the new model alongside and flag it** — replacing would de-register a model that's still in production. |
 | 3 | **References the ID as an opaque string** | UI fallback constants, capability-gate substring checks, generic test fixtures, label parsers, env defaults | Usually swap the string and verify any parser/regex/substring match handles the new ID — but check the sub-cases below first. |
-| 4 | **Suffixed variant ID** | `claude-<model>-<suffix>` like `-fast`, `-1024k`, `-200k`, `[1m]`, dated snapshots | These are deployment/routing identifiers, not the public model ID. **Do not assume a new-model equivalent exists.** Verify in the registry first; if absent, leave the string alone and flag it. |
+| 4 | **Suffixed variant ID** | `claude-<model>-<suffix>` like `-fast`, `-1024k`, `-200k`, `[1m]`, dated snapshots | These are deployment/routing identifiers, not the public model ID. **Do not assume a new-model equivalent exists.** Verify in the registry first; if absent, leave the string alone and flag it. **Exception: `-fast` strings (e.g. `claude-opus-4-6-fast`) are handled by the Fast Mode section below**, which rewrites them to Opus 4.8 plus `speed="fast"` and the `fast-mode-2026-02-01` beta rather than leaving them in place. |
 
 **Bucket 3 sub-cases — before swapping a string reference, check:**
 
@@ -167,7 +171,7 @@ If you're applying several prompt-tuning edits at once, offer them as a short li
    - `thinking: {type: "enabled", budget_tokens: N}` → migrate to adaptive thinking on Opus 4.6 / Sonnet 4.6 (still functional but deprecated)
    - Assistant-turn prefills (`messages` ending with `role: "assistant"`) → must change on Opus 4.6 / Sonnet 4.6 (returns 400)
    - `output_format` parameter on `messages.create()` → must change on all models (deprecated API-wide)
-   - `max_tokens > ~16000` → must stream on any model (above ~16K risks SDK HTTP timeouts). When streaming, Sonnet 4.6 / Haiku 4.5 cap at 64K and Opus 4.6 caps at 128K
+   - `max_tokens > ~16000` → must stream on any model (above ~16K risks SDK HTTP timeouts). When streaming, every current model reaches 128K except Haiku 4.5, which caps at 64K
    - Beta headers `effort-2025-11-24`, `fine-grained-tool-streaming-2025-05-14`, `interleaved-thinking-2025-05-14` → GA on 4.6, remove them and switch from `client.beta.messages.create` to `client.messages.create`
    - Moving Sonnet 4.5 → Sonnet 4.6 with no `effort` set → 4.6 defaults to `high`, which may change your latency/cost profile
    - System prompts with `CRITICAL`, `MUST`, `If in doubt, use X` language → likely to overtrigger on 4.6 (see Prompt-Behavior Changes)
@@ -181,10 +185,12 @@ If you're applying several prompt-tuning edits at once, offer them as a short li
 | If you're on…                         | Migrate to         | Why                                               |
 | ------------------------------------- | ------------------ | ------------------------------------------------- |
 | Claude Mythos Preview (`claude-mythos-preview`) | `claude-mythos-5` (Project Glasswing successor) or `claude-fable-5` (GA) | Same tokenizer family — mostly a model-ID swap; remove `thinking` config and prefill; see Migrating to Claude Fable 5 |
-| Opus 4.7                              | `claude-opus-4-8`  | Most capable Opus-tier model; same API surface as 4.7 (no new breaking changes) — mostly prompt re-tuning; see Migrating to Opus 4.8 |
-| Opus 4.6                              | `claude-opus-4-8`  | Apply the Opus 4.7 breaking changes, then the 4.8 re-tuning |
-| Opus 4.0 / 4.1 / 4.5 / Opus 3         | `claude-opus-4-8`  | Apply 4.6 → 4.7 → 4.8 in order (adaptive thinking, drop sampling params, then re-tune) |
-| Sonnet 4.0 / 4.5 / 3.7 / 3.5          | `claude-sonnet-4-6`| Best speed / intelligence balance; adaptive thinking; 64K output |
+| Opus 4.8                              | `claude-opus-5` | The current Opus. Two breaking changes (thinking on by default; disabling thinking capped at `high` effort) plus prompt re-tuning — see Migrating to Claude Opus 5 |
+| Opus 4.7                              | `claude-opus-5` | Apply the Opus 4.8 section (prompt re-tuning, no new breaking changes), then the Claude Opus 5 section |
+| Opus 4.6                              | `claude-opus-5` | Apply the Opus 4.7 breaking changes, then 4.8 re-tuning, then the Claude Opus 5 section |
+| Opus 4.0 / 4.1 / 4.5 / Opus 3         | `claude-opus-5` | Apply 4.6 → 4.7 → 4.8 → Claude Opus 5 in order (adaptive thinking, drop sampling params, then re-tune) |
+| Sonnet 4.6                            | `claude-sonnet-5` | Near-Opus quality on agentic and coding work at Sonnet cost; adaptive thinking on by default; see Migrating to Claude Sonnet 5 |
+| Sonnet 4.0 / 4.5 / 3.7 / 3.5          | `claude-sonnet-5` | Apply the Sonnet 4.6 changes first, then the Claude Sonnet 5 section |
 | Haiku 3 / 3.5                         | `claude-haiku-4-5` | Fastest and most cost-effective                   |
 
 Default to the latest Opus for the caller's tier unless they explicitly chose otherwise. The Opus migrations layer: if you're on Opus 4.6 or older, apply each version's section in order up to your target (e.g. 4.5 → 4.8 means the 4.6, 4.7, and 4.8 sections in sequence). A 4.7 → 4.8 move has no new breaking changes — see Migrating to Opus 4.8 below.
@@ -197,13 +203,13 @@ These models return 404 — update immediately:
 
 | Retired model                 | Retired       | Drop-in replacement  |
 | ----------------------------- | ------------- | -------------------- |
-| `claude-3-7-sonnet-20250219`  | Feb 19, 2026  | `claude-sonnet-4-6`  |
+| `claude-3-7-sonnet-20250219`  | Feb 19, 2026  | `claude-sonnet-5` |
 | `claude-3-5-haiku-20241022`   | Feb 19, 2026  | `claude-haiku-4-5`   |
 | `claude-3-opus-20240229`      | Jan 5, 2026   | `claude-opus-4-8`    |
-| `claude-3-5-sonnet-20241022`  | Oct 28, 2025  | `claude-sonnet-4-6`  |
-| `claude-3-5-sonnet-20240620`  | Oct 28, 2025  | `claude-sonnet-4-6`  |
-| `claude-3-sonnet-20240229`    | Jul 21, 2025  | `claude-sonnet-4-6`  |
-| `claude-2.1`, `claude-2.0`    | Jul 21, 2025  | `claude-sonnet-4-6`  |
+| `claude-3-5-sonnet-20241022`  | Oct 28, 2025  | `claude-sonnet-5` |
+| `claude-3-5-sonnet-20240620`  | Oct 28, 2025  | `claude-sonnet-5` |
+| `claude-3-sonnet-20240229`    | Jul 21, 2025  | `claude-sonnet-5` |
+| `claude-2.1`, `claude-2.0`    | Jul 21, 2025  | `claude-sonnet-5` |
 
 ## Deprecated Models (retiring soon)
 
@@ -211,7 +217,7 @@ These models return 404 — update immediately:
 | ----------------------------- | ------------- | -------------------- |
 | `claude-3-haiku-20240307`     | Apr 19, 2026  | `claude-haiku-4-5`   |
 | `claude-opus-4-20250514`      | June 15, 2026 | `claude-opus-4-8`    |
-| `claude-sonnet-4-20250514`    | June 15, 2026 | `claude-sonnet-4-6`  |
+| `claude-sonnet-4-20250514`    | June 15, 2026 | `claude-sonnet-5` |
 
 ---
 
@@ -227,7 +233,7 @@ Sonnet 4.5 had no `effort` parameter; Sonnet 4.6 defaults to `high`. If you just
 | ------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
 | Chat, classification, content generation          | `low`          | With `thinking: {"type": "disabled"}` you'll see similar or better performance vs. Sonnet 4.5 no-thinking |
 | Most applications (balanced)                      | `medium`       | The default sweet spot for quality vs. cost                                                              |
-| Agentic coding, tool-heavy workflows              | `medium`       | Pair with adaptive thinking and a generous `max_tokens` (up to 64K with streaming — Sonnet 4.6's ceiling) |
+| Agentic coding, tool-heavy workflows              | `medium`       | Pair with adaptive thinking and a generous `max_tokens` (up to 128K with streaming — Sonnet 4.6's ceiling) |
 | Autonomous multi-step agents, long-horizon loops  | `high`         | Scale down to `medium` if latency/tokens become a concern                                                 |
 | Computer-use agents                               | `high` + adaptive | Sonnet 4.6's best computer-use accuracy is on adaptive + high                                          |
 
@@ -285,11 +291,11 @@ client.messages.create(
 )
 ```
 
-If the user asks for a "thinking budget" on 4.6, the preferred answer is `effort` — use `low`, `medium`, `high`, or `max` (Opus-tier only — not Sonnet or Haiku) rather than a token count.
+If the user asks for a "thinking budget" on 4.6, the preferred answer is `effort` — use `low`, `medium`, `high`, or `max` rather than a token count.
 
 **2. Effort parameter (Opus 4.5, Opus 4.6, Sonnet 4.6 only).**
 
-Controls thinking depth and overall token spend. Goes inside `output_config`, not top-level. Default is `high`. `max` is Opus-tier only (Opus 4.6 and later — not Sonnet or Haiku). Errors on Sonnet 4.5 and Haiku 4.5.
+Controls thinking depth and overall token spend. Goes inside `output_config`, not top-level. Default is `high`. `max` is supported on Fable 5, Opus 4.6 and later, Sonnet 5, and Sonnet 4.6 — it errors on Sonnet 4.5 and Haiku 4.5.
 
 ```python
 output_config={"effort": "medium"}  # often the best cost / quality balance
@@ -326,9 +332,9 @@ response = client.messages.create(
 )
 ```
 
-**4. Stream for `max_tokens > ~16K` (all models); Opus 4.6 alone reaches 128K.**
+**4. Stream for `max_tokens > ~16K` (all models); only Haiku 4.5 caps lower, at 64K.**
 
-Non-streaming requests hit SDK HTTP timeouts at high `max_tokens`, regardless of model — stream for anything above ~16K output. The streamable ceiling differs by model: Sonnet 4.6 and Haiku 4.5 cap at 64K, and Opus 4.6 alone goes up to 128K.
+Non-streaming requests hit SDK HTTP timeouts at high `max_tokens`, regardless of model — stream for anything above ~16K output. The streamable ceiling is 128K for every current model except Haiku 4.5, which caps at 64K.
 
 ```python
 with client.messages.stream(model="claude-opus-4-6", max_tokens=64000, ...) as stream:
@@ -403,7 +409,7 @@ Legacy tool versions are not supported on 4+. **Both the `type` and the `name` f
 | Old                                               | New                                                     |
 | ------------------------------------------------- | ------------------------------------------------------- |
 | `text_editor_20250124` + `str_replace_editor`     | `text_editor_20250728` + `str_replace_based_edit_tool`  |
-| `code_execution_*` (earlier versions)             | `code_execution_20250825`                               |
+| `code_execution_*` (earlier versions)             | `code_execution_20260521`                               |
 | `undo_edit` command                               | *(no longer supported — delete call sites)*             |
 
 ```python
@@ -479,16 +485,18 @@ If the model is now overtriggering a tool or skill, the fix is almost always to
 
 | Old string (migration source)  | New string         |
 | ------------------------------ | ------------------ |
-| `claude-opus-4-7`              | `claude-opus-4-8`  |
-| `claude-opus-4-6`              | `claude-opus-4-8`  |
-| `claude-opus-4-5`              | `claude-opus-4-8`  |
-| `claude-opus-4-1`              | `claude-opus-4-8`  |
-| `claude-opus-4-0`              | `claude-opus-4-8`  |
+| `claude-opus-4-8`              | `claude-opus-5`     |
+| `claude-opus-4-7`              | `claude-opus-5`     |
+| `claude-opus-4-6`              | `claude-opus-5`     |
+| `claude-opus-4-5`              | `claude-opus-5`     |
+| `claude-opus-4-1`              | `claude-opus-5`     |
+| `claude-opus-4-0`              | `claude-opus-5`     |
 | `claude-mythos-preview`        | `claude-mythos-5` (Project Glasswing) or `claude-fable-5` |
-| `claude-sonnet-4-5`            | `claude-sonnet-4-6`|
-| `claude-sonnet-4-0`            | `claude-sonnet-4-6`|
+| `claude-sonnet-4-6`            | `claude-sonnet-5`|
+| `claude-sonnet-4-5`            | `claude-sonnet-5`|
+| `claude-sonnet-4-0`            | `claude-sonnet-5`|
 
-Older aliases (`claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5`, `claude-sonnet-4-5`, etc.) are still active and can be pinned if you need time before upgrading — see `shared/models.md` for the full legacy list.
+Older aliases (`claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5`, `claude-sonnet-4-6`, `claude-sonnet-4-5`, etc.) are still active and can be pinned if you need time before upgrading — see `shared/models.md` for the full legacy list.
 
 ### Amazon Bedrock model IDs
 
@@ -497,12 +505,14 @@ If the code uses the `AnthropicBedrockMantle` client (Python `anthropic[bedrock]
 | First-party ID | Bedrock ID |
 |---|---|
 | `claude-opus-4-8` | `anthropic.claude-opus-4-8` |
+| `claude-opus-5` | `anthropic.claude-opus-5` |
 | `claude-opus-4-7` | `anthropic.claude-opus-4-7` |
+| `claude-sonnet-5` | `anthropic.claude-sonnet-5` |
 | `claude-haiku-4-5` | `anthropic.claude-haiku-4-5` |
 
 When migrating a Bedrock file, apply the same rename-table row as first-party, then keep/add the `anthropic.` prefix. Do **not** generate a first-party `claude-*` ID for a Bedrock client — it will 400.
 
-**Skip for Bedrock:** the `code_execution_*` tool-version checklist item and the **Task Budgets** section — both are first-party-only features (Bedrock does not support server-side Anthropic tools or the `task-budgets-2026-03-13` beta). Everything else in this guide — `effort`, adaptive/extended thinking, `output_config.format`, `thinking.display`, fine-grained tool streaming, token counting — is available on Bedrock.
+**Skip for Bedrock:** the `code_execution_*` tool-version checklist item and the **Task Budgets** section — neither is available on Bedrock (see `shared/platform-availability.md` for the per-feature table). Everything else in this guide — `effort`, adaptive/extended thinking, `output_config.format`, `thinking.display`, fine-grained tool streaming, token counting — is available on Bedrock.
 
 > **Out of scope:** the legacy Amazon Bedrock integration (`InvokeModel` / `Converse` APIs with ARN-versioned IDs like `anthropic.claude-3-5-sonnet-20241022-v2:0`) uses a different request shape and model-ID format. This guide does not cover it; WebFetch the Bedrock page in `shared/live-sources.md` if the user is migrating between the two Bedrock integrations.
 
@@ -533,7 +543,7 @@ For each file that calls `messages.create()` / equivalent SDK method:
 - [ ] **[BLOCKS]** Remove either `temperature` or `top_p` (passing both 400s on Claude 4+)
 - [ ] **[BLOCKS]** Update text-editor tool `type` to `text_editor_20250728`
 - [ ] **[BLOCKS]** Update text-editor tool `name` to `str_replace_based_edit_tool` — **changing only the `type` and keeping `name: "str_replace_editor"` returns a 400**
-- [ ] **[BLOCKS]** Update code-execution tool to `code_execution_20250825`
+- [ ] **[BLOCKS]** Update code-execution tool to `code_execution_20260521`
 - [ ] **[BLOCKS]** Delete any `undo_edit` command call sites
 - [ ] **[TUNE]** Add handling for `stop_reason == "refusal"`
 - [ ] **[TUNE]** Add handling for `stop_reason == "model_context_window_exceeded"` (4.5+)
@@ -681,18 +691,22 @@ Beyond resolution, Opus 4.7 also improves on low-level perception (pointing, mea
 
 Requests that involve prohibited or high-risk topics may lead to refusals.
 
-### Fast Mode: not available on Opus 4.7
+### Fast Mode: Claude Opus 5 / Opus 4.8 only
 
-Opus 4.7 does not have a Fast Mode variant. **Opus 4.6 Fast remains supported**. Only surface this if the caller's code actually uses a Fast Mode model string (e.g. `claude-opus-4-6-fast`); if the word "fast" does not appear in the code, say nothing about Fast Mode.
+Fast mode is available on Claude Opus 5 and Opus 4.8. Only surface this if the caller's code actually uses fast mode (e.g. `model="claude-opus-4-6-fast"`, or `speed="fast"` on an unsupported model); if the word "fast" does not appear in the code, say nothing about Fast Mode.
 
-When you see `model="claude-opus-4-6-fast"` (or similar), **the migration edit is**:
+When you see `model="claude-opus-4-6-fast"` (or any retired `-fast` model string), **the migration edit is** to move the fast-mode traffic onto Claude Opus 5, the current fast-capable default (Opus 4.8 also works if the caller is staying on that tier):
 
 ```python
-# Opus 4.7 has no Fast Mode — keeping on 4.6 Fast (caller's choice to switch to standard Opus 4.7).
-model="claude-opus-4-6-fast",
+# Request fast mode on Claude Opus 5.
+client.beta.messages.create(
+    model="claude-opus-5", max_tokens=4096,
+    speed="fast", betas=["fast-mode-2026-02-01"],
+    messages=[...],
+)
 ```
 
-That is: leave the model string **unchanged**, add the comment above it, and tell the user their two options — (a) stay on Opus 4.6 Fast, which remains supported, or (b) move latency-tolerant traffic to standard Opus 4.7 for the intelligence gain. Do **not** rewrite the model string to `claude-opus-4-7` yourself; that silently trades latency for intelligence, which is the caller's decision.
+That is: switch the model to Claude Opus 5 (or Opus 4.8) and request fast mode the supported way, using the beta `client.beta.messages.…` endpoint, the `fast-mode-2026-02-01` beta flag, and `speed="fast"` as a top-level request parameter (per-language form in SKILL.md § Fast Mode). Opus 4.7 fast mode has also been removed, so do not land on Opus 4.7 either. Do **not** leave the code on a retired `-fast` model string — the failure mode differs by version: `claude-opus-4-6-fast` is retired and the API **silently falls back** to standard Opus 4.6 (no error — the caller loses fast-mode speed without noticing); `claude-opus-4-7-fast` and `speed="fast"` on Opus 4.7 instead return an **API error** (hard failure — requests break outright rather than degrading). Either way, migrate to Opus 4.8 fast mode now.
 
 ### Behavioral shifts (prompt-tunable)
 
@@ -822,7 +836,7 @@ messages=[
 ]
 ```
 
-Phrase these as **context, not commands**. State the fact and let Claude act on it; avoid override-style language ("ignore what the user said", "regardless of the user's request", "disregard the previous instruction"). Claude is trained to protect users from instructions that appear to work against them, and that protection applies to the system role too. This is a beta (`anthropic-beta: mid-conversation-system-2026-04-07`) and is available from Opus 4.7 onward, not 4.8-exclusive. For cache-placement details and the older-model `<system-reminder>` fallback, see `shared/prompt-caching.md` and `shared/agent-design.md`.
+Phrase these as **context, not commands**. State the fact and let Claude act on it; avoid override-style language ("ignore what the user said", "regardless of the user's request", "disregard the previous instruction"). Claude is trained to protect users from instructions that appear to work against them, and that protection applies to the system role too. No beta header is required; available on Claude Opus 4.8. For cache-placement details and the older-model `<system-reminder>` fallback, see `shared/prompt-caching.md` and `shared/agent-design.md`.
 
 ### Capability improvements
 
@@ -882,7 +896,400 @@ For a caller **already on Opus 4.7**, only the first item is required; everythin
 - [ ] **[TUNE]** Writing voice: re-evaluate style prompts added to counter 4.7's directness — 4.8 is warmer and less hedged by default; re-baseline before keeping them
 - [ ] **[TUNE]** Code-review harnesses: keep the report-everything-filter-downstream pattern (4.8 follows "only high-severity" / "be conservative" filters literally, which can depress measured recall)
 - [ ] **[TUNE]** Thinking-disabled paths: add a final-answer-only instruction if reasoning leaks into the visible response
-- [ ] **[TUNE]** Consider mid-session system messages (`role:"system"` in `messages`, beta `mid-conversation-system-2026-04-07`) for context the app learns mid-session, instead of rebuilding the top-level system prompt and invalidating the cache
+- [ ] **[TUNE]** Consider mid-session system messages (`role:"system"` in `messages`; no beta header) for context the app learns mid-session, instead of rebuilding the top-level system prompt and invalidating the cache
+
+---
+
+## Migrating to Claude Opus 5
+
+> **Model ID `claude-opus-5` is authoritative as written here.** When the user asks to migrate to Claude Opus 5, write `model="claude-opus-5"` exactly. Do **not** WebFetch to verify — this guide is the source of truth for migration target IDs. The corresponding entry exists in `shared/models.md`.
+
+Claude Opus 5 is the successor to Claude Opus 4.8 in the Opus line, and is strongest on long-horizon agentic work and coding. It is layered on top of the Opus 4.8 migration above; if the caller is coming from Opus 4.7 or older, apply those sections first. Like Claude Fable 5, it ships with **elevated cybersecurity safeguards, and its safety classifiers can decline a request**: you get a normal HTTP 200 with `stop_reason: "refusal"` and a `stop_details` category, not an error. Benign security and life-sciences work occasionally trips them, so **check `stop_reason` before reading `response.content`** — code that indexes `content[0]` unconditionally breaks on a refusal. Cyber-category refusals route to Opus 4.8 as the recommended fallback, so a fallback strategy genuinely recovers the request rather than just relabelling the failure. The full refusal semantics (pre-output vs mid-stream billing, retry strategies, fallback credit) are in the Claude Fable 5 section below and apply here unchanged.
+
+Existing prompts and evals should carry over with strong out-of-the-box performance. **It is a drop-in upgrade at Opus 4.8's pricing** — $5 per million input tokens, $25 per million output — with the same feature set: 1M context (default, no beta header), 128K max output, adaptive thinking, prompt caching, batch processing, the Files API, PDF support, vision, and the full server-side and client-side tool set. `claude-opus-5` is a fixed ID with no date suffix, same scheme as `claude-opus-4-8`.
+
+The migration is **the model-ID swap plus prompt re-tuning**, with two breaking changes covered below.
+
+**Availability at launch:** Claude API (`claude-opus-5`), Amazon Bedrock (`anthropic.claude-opus-5`), Google Cloud (`claude-opus-5`), and Microsoft Foundry. Opus 4.8 stays available on all four.
+
+**Rate limits are a separate bucket.** Opus 4.8/4.7/4.6/4.5 share one combined Opus limit; Claude Opus 5 does **not** draw from it. Shifting traffic over neither frees headroom on the old bucket nor inherits it — check your tier's Claude Opus 5 limits before moving volume.
+
+**TL;DR for someone already on Claude Opus 4.8:** swap the model ID. Then re-tune: Claude Opus 5 writes longer user-facing responses and longer files on disk (add explicit conciseness and deliverable-length instructions — `effort` does not reliably shorten visible output), verifies its own work without being told (**delete** your verification instructions and harness verification steps), and can expand task scope (add a scope-discipline instruction). Run a fresh effort sweep — `low` and `medium` are unusually strong here and are the primary cost/latency lever.
+
+### Breaking change 1: thinking is on by default
+
+A request that omits the `thinking` parameter **thinks** on Claude Opus 5, unlike Claude Opus 4.8 and Opus 4.7 where omitting it meant no thinking. `thinking: {type: "adaptive"}` remains valid and is equivalent to the default — the wire value didn't change, the default did.
+
+This is a silent cost and truncation change, not just a behavior one: **`max_tokens` is a hard cap on thinking *plus* response text.** A workload that ran without thinking on Opus 4.8 and sized `max_tokens` tightly around its answer can now truncate mid-response. Revisit `max_tokens` on every route that never set `thinking`. To keep the old behavior, pass `thinking: {type: "disabled"}` — subject to the effort cap below.
+
+Raw thinking tokens are **never returned** on Claude Opus 5; `display` defaults to `"omitted"`, and `display: "summarized"` gets you a summary. This also means a fallback model cannot read Claude Opus 5's thinking.
+
+### Breaking change 2: disabling thinking is capped at `high` effort
+
+Disabling thinking is available only at effort **`high` or lower**; `thinking: {type: "disabled"}` combined with `xhigh` or `max` returns a 400. Opus 4.8 accepts that combination, so audit any route that disables thinking before migrating.
+
+**The check is per request.** Effort and thinking are validated independently on every call, so a later request that raises effort to `xhigh` while thinking is still disabled is rejected even though earlier requests in the same conversation succeeded.
+
+```python
+# 400 on Claude Opus 5 — disabled thinking above `high`
+client.messages.create(
+    model="claude-opus-5",
+    max_tokens=4096,
+    thinking={"type": "disabled"},
+    output_config={"effort": "xhigh"},
+    messages=[...],
+)
+```
+
+**Migrating:** either enable thinking at `xhigh`/`max`, or lower effort to `high` or below. Given how well Claude Opus 5 performs at `low` and `medium`, a latency-sensitive route that previously ran `xhigh` + disabled thinking is usually better served by `medium` with thinking on than by keeping the disabled path.
+
+Everything else from the Opus 4.7/4.8 request surface is unchanged: `budget_tokens` still 400s (use `output_config.effort`), sampling parameters (`temperature`, `top_p`, `top_k`) are still rejected, last-assistant-turn prefills still 400, and `thinking.display` still defaults to `"omitted"`.
+
+### Two failure modes when thinking is disabled
+
+**Are you affected?** Only if you explicitly set `thinking: {type: "disabled"}`. Thinking is on by default on Claude Opus 5 (see Breaking change 1 above), so an unmodified request never hits either of these — but code carrying a disabled-thinking setting forward from Opus 4.8, where it was the default behaviour, does.
+
+Both are specific to `thinking: {type: "disabled"}` on Claude Opus 5, and for both the **primary recommendation is the same: turn thinking back on and use a lower `effort` to control cost and verbosity instead.** Disabling thinking is the more expensive lever in every sense — it is what triggers these, and `low`/`medium` effort already gets you most of the token and latency saving (see § Effort below).
+
+**1. Tool calls can arrive as plain text.** The model occasionally writes a tool call into its user-facing text rather than emitting a structured `tool_use` block. **The turn completes normally and the call never runs** — there is no error and no `tool_use` block to catch, so a harness sees a successful turn that silently did nothing. Worse in an agentic loop: the bogus text stays in conversation history and skews later turns. Most common on tool-heavy workloads such as search.
+
+**2. `<thinking>` tags can leak into the visible response.** The model may emit `<thinking>` or other internal XML in its user-facing output.
+
+If you cannot enable thinking, one instruction covers both failure modes — give the model explicit permission to talk before a tool call (the tool-as-text failure appears to come from suppressing the preamble it wants to write), and forbid internal tags generically:
+
+> *"When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response."*
+
+Two counterintuitive rules for that instruction:
+
+- **Delete any instruction telling the model not to think or not to reason.** That kind of rule *increases* tag leakage rather than suppressing it.
+- **Do not name thinking tags in the prompt.** Calling out `<thinking>` by name is measurably less effective than the generic "internal or system XML tags" wording above.
+
+### New API features
+
+Two additions, each behind its own beta header. Both are optional — a migrated request works without them.
+
+**1. `fallbacks: "default"` — recommended for every caller.** Claude Opus 5's safety classifiers can decline a request; the `fallbacks` parameter re-runs a declined request on another model server-side instead of returning the refusal to you. Previously you named the substitute yourself (`"fallbacks": [{"model": "claude-opus-4-8"}]`). The new `"default"` mode picks Anthropic's recommended fallback automatically, routed **by refusal category** — cyber-category refusals go to Claude Opus 4.8.
+
+```http
+POST /v1/messages
+anthropic-beta: server-side-fallback-2026-07-01
+
+{"model": "claude-opus-5", "fallbacks": "default", "max_tokens": 1024,
+ "messages": [{"role": "user", "content": "Say OK."}]}
+```
+
+**Prefer `"default"` over pinning a model.** Different fallback models carry different classifiers, so the right substitute depends on *why* the request was declined — and `"default"` removes the migration you would otherwise owe when a pinned fallback model is deprecated. Note the header is `server-side-fallback-2026-07-01`, distinct from the `-2026-06-01` header that gates the array form; the array form's semantics (content blocks, `usage.iterations`, sticky routing) are unchanged and documented in the Claude Fable 5 refusal section below.
+
+**2. Mid-conversation tool changes (beta `mid-conversation-tool-changes-2026-07-01`).** Change a conversation's tool set between turns without invalidating the prompt cache. Previously `tools` was fixed for the conversation's lifetime and any edit re-billed the whole prefix. Append a `{"role": "system", "content": [...]}` message carrying a `tool_addition` or `tool_removal` block:
+
+```python
+messages = [
+    {"role": "user", "content": "What tools do you have for weather in Paris?"},
+    {"role": "system", "content": [
+        {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "get_forecast"}},
+    ]},
+]
+```
+
+The added tool must already be declared in `tools[]` with `"defer_loading": True` — declared up front, but not loaded into context until a `tool_addition` surfaces it. A `tool_removal` block must sit either immediately before an assistant message or at the end of `messages`. To *change* a tool's definition, remove the old one on one request, then send the updated entry in `tools[]` on the next. See `shared/tool-use-concepts.md` § Mid-conversation tool changes.
+
+> ⚠️ Earlier previews of this feature used a different beta header and different block shapes. Both are deprecated — if the code you're migrating carries anything other than `mid-conversation-tool-changes-2026-07-01` with `tool_addition` / `tool_removal` / `tool_reference`, update the header and the shapes together.
+
+
+> **SDK typings lag these blocks.** Pass them as plain dicts in Python (the SDK forwards unknown keys unchanged) or add a `@ts-expect-error` in TypeScript until the types catch up. `extra_body` / `extra_headers` work on `.stream()` exactly as on `.create()`.
+
+### Capability improvements
+
+**Agentic coding.** Claude Opus 5 is a workhorse for agentic coding and is strongest on *difficult* tasks — multi-file features, larger refactors, end-to-end feature work. It completes tasks rather than leaving stubs or placeholders. The gap over prior models is smaller on easy single-turn edits, so evaluate it on the hard end of your workload. To get the most out of it, give the complete task specification up front and let it run; longer autonomous sessions with more parallel agents show the strongest results, short interactive edits the least.
+
+**Code review and bug-finding.** High precision *and* high recall — a high rate of real bugs per pass, with the extra findings mostly real rather than false positives. It stays accurate at lower effort, which makes a cheap fast pass at review time plus a thorough pass later a practical pattern.
+
+**Effort: the full ladder, and where to start.** Claude Opus 5 supports all five levels — `low`, `medium`, `high`, `xhigh`, `max` — with no beta header. The API default is `high`.
+
+- **Start at `high` (the API default), then sweep down.** `low` and `medium` are unusually effective on this model — strong quality at a fraction of the tokens and latency on many workloads — so treat them as the primary cost/latency lever and reserve `high` and above for tasks where your evals show a quality difference. Effort defaults carried over from a prior model are usually not the right setting here; run a fresh sweep.
+- **`xhigh` and `max` are for measured wins, not a starting point.** `max` is the top tier for the deepest reasoning and worth testing where capability matters more than spend, but it can show diminishing returns and overthink simpler tasks.
+
+At `xhigh` or `max`, **set a large `max_tokens`** so the model has room to think and act across tool calls and subagents. Start at 64K and tune.
+
+**Lower prompt-cache minimum.** The minimum cacheable prompt is **512 tokens** on Claude Opus 5, down from 1024 on Opus 4.8. Prompts previously too short to cache now create entries with no code change — worth re-checking any prompt you'd written off as uncacheable. See `shared/prompt-caching.md`.
+
+**Fast mode.** `speed: "fast"` (beta header `fast-mode-2026-02-01`) is supported on Claude Opus 5, priced at $10 / $50 per MTok. It is a research preview on the **Claude API only** — including Managed Agents — and is **not** available on Amazon Bedrock, Google Cloud, or Microsoft Foundry. Fast mode draws on dedicated rate limits separate from the standard Opus pools.
+
+**Vision — give it tools, not more thinking.** Stronger on chart, document, and diagram understanding, and on UI and frontend visual replication. The highest-leverage change is **giving it tools to iteratively analyze, crop, and visually verify its own work**: on this model tool use is a markedly more cost-effective lever than raising thinking alone. Claude Opus 5 sits in the high-resolution tier alongside Opus 4.8 — 2576 px on the long edge, up to 4784 visual tokens per image — so coordinates map 1:1 to pixels and no scale-factor math is needed. Any prompt-side workaround you added for a prior model's vision limitations should be re-validated; several are now counterproductive.
+
+**Long context.** 1M-token context window as both the default *and* the maximum. Instruction following, tool calling, and reasoning stay strong across the full window.
+
+**Office and document tasks.** Generates and edits complex multi-sheet Excel files with non-trivial formulas, and visually strong PowerPoint decks that follow slide-design best practices. It can be prompted to adhere to a specific style or template when one is required.
+
+**Multi-agent coordination.** Coordinates teams of subagents well — few cases of agents overwriting each other's work, and effective use of writer-verifier patterns. Workloads that benefit from multi-agent patterns are good fits. **Cost-sensitive workloads should cap multi-agent usage** — see the delegation section below, because this model reaches for subagents more readily than its predecessors.
+
+### Behavioral shifts (prompt-tunable)
+
+**Longer user-facing responses.** Default response text is longer than on prior models. **`effort` is not the lever here** — changing it may move thinking volume without reliably changing visible output length. Prompting is: in testing, a short conciseness instruction cut user-facing response length by ~20%.
+
+> *"Keep responses focused, brief, and concise to avoid overwhelming the person. Disclaimers and caveats are brief, with most of the response on the main answer; when asked to explain something, give a high-level summary unless an in-depth one is specifically requested."*
+
+For a long system prompt, pair that with a one-line reminder near the end:
+
+> ```
+> <tone_preference>
+> Keep outputs reasonably concise.
+> </tone_preference>
+> ```
+
+**More narration in agentic sessions** (the lever runs both ways — the same explicit-description technique tunes narration *up* or restyles it, if your product wants more). Claude Opus 5 narrates what it is about to do, and its per-message output in agentic sessions is longer than prior models'. It responds well to explicit guidance on *how* to communicate during a task rather than just *how much*. For coding agents, this block calibrates it:
+
+> ```
+> # Communicating with the user
+> Your text output is what the user reads between tool calls; they usually can't see your thinking or the raw tool results. Write it for a teammate who stepped away and is catching up, not for a log file: they don't know the codenames or shorthand you created along the way, and they didn't watch your process unfold. Before your first tool call, say in a sentence what you're about to do; while working, give brief updates when you find something load-bearing or change direction.
+>
+> Lead with the outcome. Your first sentence after finishing should answer "what happened" or "what did you find" — the thing the user would ask for if they said "just give me the TLDR." Supporting detail and reasoning should come after, for readers who want them.
+>
+> Being readable and being concise are different things, and readable matters more. If the user has to reread your summary or ask you to explain, any time saved by brevity is gone. The way to keep output short is to be selective about what you include (drop details that don't change what the reader would do next), not to compress the writing into fragments, abbreviations, arrow chains like `A → B → fails`, or jargon. What you do include, write in complete sentences with the technical terms spelled out. Don't make the reader cross-reference labels or numbering you invented earlier; say what you mean in place.
+>
+> Match the response to the question: a simple question should be answered with a direct answer in prose, not headers and sections. Use tables only for short enumerable facts, with explanations in the surrounding prose rather than the cells. Calibrate to the user — a bit tighter for an expert, more explanatory for someone newer.
+>
+> Write code that reads like the surrounding code: match its comment density, naming, and idiom.
+>
+> Only write a code comment to state a constraint the code itself can't show — never to say where it came from, what the next line does, or why your change is correct; that's you talking to the reviewer, not the next reader, and it's noise the moment the PR merges.
+> ```
+
+**Longer written deliverables.** Separate from conversational verbosity: files Claude Opus 5 writes to disk — reports, Markdown documents, summaries — are often longer than on prior models. If your product ships Claude-authored documents, calibrate length explicitly:
+
+> *"Match the length of written deliverables (especially Markdown files) to what the task needs: cover the substance, but do not pad documents with filler sections, redundant summaries, or boilerplate."*
+
+**Self-check instructions are the same trap.** Beyond harness scaffolding, per-prompt re-check phrasing — *"double-check your answer"*, *"re-verify before responding"* — triggers the same extra work. Note this **inverts a standard prompting best practice**: "ask Claude to self-check" is generally sound advice and is wrong here, so a prompt library that applies it uniformly needs a carve-out for this model rather than a global rule.
+
+**Over-verification — delete your verification scaffolding.** Claude Opus 5 verifies its own work without being asked. Instructions that *tell* it to verify ("include a final verification step for virtually any non-trivial task", "use a subagent to verify") now cause over-verification. **Removing them reduces over-verification with no capability regression** — this is a delete, not a rewrite. The same applies to harness-level scaffolding: separate verification steps carried over from prior models are likely redundant now.
+
+**Task scope expansion.** It can add steps the user didn't request, or apply its own judgment about what the task should be without making that clear. In testing, this instruction reduced scope changes to nearly zero without producing excessive clarifying questions:
+
+> *"Deliver what the user asked for, at the scope they intended. Interpret ambiguity the way a careful colleague would: make routine judgment calls yourself, and check in only when different readings would lead to materially different work. If you conclude the ask is mistaken or a better approach exists, say so in a sentence and keep going with the task as asked — don't quietly narrow, widen, or transform it. Finish the whole task, not just the easy part of it - only report completion when it's fully done. If you genuinely can't complete something, do the rest and state plainly what's missing and why. Stop short of actions or changes that are clearly beyond what the user's ask implies."*
+
+The revised wording adds a **finish-the-whole-task** clause — report completion only when the work is actually done, and if something genuinely can't be finished, do the rest and say plainly what is missing. That covers premature "done" claims, which scope-discipline wording alone did not.
+
+**Delegates to subagents more readily — the opposite of Opus 4.8.** This is a direction change worth flagging: Opus 4.8 *under*-reached for subagents and needed prompting to delegate. Claude Opus 5 reaches for them freely, which multiplies cost and latency — each subagent re-establishes context, re-explores, reports back, and then the coordinator re-reads the report. If your harness supports subagents, **any "delegate more" guidance you added for Opus 4.8 should come out**, and you likely want an explicit cap. A deterministic ceiling on spawn count is the reliable lever; this block reduces delegation and token spend:
+
+> ```
+> ## Delegating to subagents
+> Subagents multiply cost and time: each one re-establishes context, re-explores, and reports back, and you then re-read its report. Delegate rarely and only when the payoff clearly exceeds that overhead.
+>
+> Do use subagents for:
+> - Large tasks that are genuinely independent and parallelizable. For example, wide multi-file investigations.
+>
+> Do NOT use subagents for:
+> - Work you could finish yourself in a handful of tool calls. For example: a few file reads, a handful of edits, a simple search task, relatively simple verification.
+> - Review, verification, or to double check your work. Verification belongs in your main agent loop.
+>
+> Use of parallel or multiple subagents:
+> - Do not use multiple subagents on a single small task. Parallel subagents are for genuinely independent, sizeable tracks (unrelated modules, a wide multi-file investigation), not for splitting one modest job into pieces.
+> - If the task can be completed with one subagent, choose one subagent over multiple subagents. Keep spawn counts low.
+> - Never use more than 20 parallel agents unless the user explicitly requests it.
+>
+> When delegating to subagents:
+> - Brief the subagent precisely the first time. Avoid launching, waiting, and re-briefing.
+> - If you delegate, commit to the delegation. Never redo the subagent's work and do not re-derive its findings once it reports back.
+> - If you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.
+> ```
+
+Note the interaction with over-verification below: "do not use subagents to verify" and "delete your verification scaffolding" are the same underlying fix seen from two angles.
+
+**Narrates self-corrections more than prior models.** It flags and explains its own earlier mistakes at length, which reads as thrash in a user-facing product. Scope corrections to the ones that actually change the user's outcome:
+
+> ```
+> # Corrections
+> Avoid unnecessary or excessive self-correction. Only correct an earlier statement in your user-facing text when the error would change the user's code, conclusions, or decisions. State corrections plainly and concisely, and continue the task; combine multiple corrections rather than enumerating them all. For slips that change nothing for the user, simply make the correction and move on - no need to note it explicitly. Don't add apologies or preambles, don't be overly self-critical, and don't ruminate or give a detailed account of the mistake or tally past errors. Sometimes, other agents will report incorrect or misleading results - don't always take them at face value immediately. If other agents correct your statements and they are right, then simply update your approach without narrating too much about the correction to the user. This instruction does not apply to thinking blocks.
+>
+> A follow-up question about your earlier work is not, by itself, a signal that you got something wrong — answer what was asked. A statement that was accurate needs no correction: don't re-audit how you phrased it, how you verified it, or limits you already stated. When the user does point to a real error, correct it plainly as above.
+> ```
+
+The second paragraph matters as much as the first: a plain follow-up question can otherwise trigger a re-audit of work that was correct.
+
+**Time to first token (TTFT).** Claude Opus 5 sometimes thinks before its first visible block, which raises TTFT — a problem for user-facing chat and voice, where the pause reads as latency. This one-line instruction reduces pre-first-block thinking significantly:
+
+> *"Latency-sensitive; begin your visible answer immediately."*
+
+Apply it only where first-token latency is user-visible; on background and agentic routes the pre-answer thinking is usually worth keeping.
+
+**Severity filters still depress measured recall.** Unchanged from 4.7/4.8: if a review harness says "only report high-severity issues" or "be conservative", Claude Opus 5 follows it literally. Ask it to report everything with confidence and severity, and filter in a separate pass — see the **Code review** guidance in the Opus 4.7 section for the recommended prompt.
+
+### Claude Opus 5 Migration Checklist
+
+**`[BLOCKS]`** items cause a 400 error if missed; **`[TUNE]`** items are quality/cost adjustments — surface them to the user as recommendations.
+
+- [ ] **[BLOCKS]** Update the `model=` string to `claude-opus-5`
+- [ ] **[BLOCKS]** Any route combining `thinking: {type: "disabled"}` with `effort` of `xhigh` or `max`: enable thinking, or lower effort to `high` or below. Validated per request, so audit every call site, not just the first
+- [ ] **[BLOCKS]** Every route that never set `thinking`: it now thinks, and `max_tokens` caps thinking + response text together. Raise `max_tokens` or pass `thinking: {type: "disabled"}` at effort `high` or below — otherwise responses truncate mid-answer
+- [ ] **[BLOCKS]** *(only if coming from Opus 4.7 or earlier)* Apply the **Migrating to Opus 4.7** breaking changes first — `budget_tokens` → adaptive thinking, strip `temperature`/`top_p`/`top_k`, remove last-assistant-turn prefills
+- [ ] **[TUNE]** Effort: start at `high` (the API default) and sweep down — `low`/`medium` are unusually strong on this model and are the primary cost/latency lever; reserve `xhigh`/`max` for tasks where you've measured a quality difference. Prior-model defaults rarely transfer. At `xhigh`/`max`, set `max_tokens` to at least 64K
+- [ ] **[TUNE]** Re-check prompts you'd written off as uncacheable — the minimum drops to 512 tokens (from 1024 on Opus 4.8)
+- [ ] **[TUNE]** Rate limits: Claude Opus 5 is a separate bucket from the combined Opus 4.x pool — confirm your tier's limits before shifting volume
+- [ ] **[TUNE]** Fast mode (`speed: "fast"`, `fast-mode-2026-02-01`, $10/$50) is Claude-API-only — drop it on Bedrock, Google Cloud, and Foundry routes
+- [ ] **[TUNE]** Verbosity: add a conciseness instruction (and a `<tone_preference>` tag for long system prompts). Do **not** try to shorten output by lowering `effort` — it doesn't reliably work
+- [ ] **[TUNE]** Agentic sessions: add a "Communicating with the user" block to calibrate inter-tool-call narration
+- [ ] **[TUNE]** Claude-authored files: add a deliverable-length instruction
+- [ ] **[TUNE]** **Delete** verification instructions from prompts and verification steps from the harness — including per-prompt *"double-check your answer"* phrasing, which inverts the usual self-check best practice on this model
+- [ ] **[TUNE]** Add the scope-discipline instruction if the model expands task scope
+- [ ] **[TUNE]** Vision pipelines: re-validate prompt-side workarounds written for a prior model's vision limitations
+- [ ] **[TUNE]** Consider mid-conversation tool changes (`mid-conversation-tool-changes-2026-07-01`) — changes the tool set between turns without invalidating the prompt cache. Note per-turn `effort` / `task_budget` are **not** in this launch; both stay request-level
+- [ ] **[TUNE]** Subagent-capable harnesses: this model delegates *more* readily than Opus 4.8 — remove any "delegate more" guidance you added for 4.8 and add an explicit cap
+- [ ] **[TUNE]** User-facing products: add the corrections instruction if self-correction narration reads as thrash
+- [ ] **[TUNE]** TTFT-sensitive routes (chat, voice): add *"Latency-sensitive; begin your visible answer immediately"* to reduce pre-first-block thinking; skip on background/agentic routes
+- [ ] **[TUNE]** Any route running `thinking: {type: "disabled"}`: prefer turning thinking on at `low`/`medium` effort. Disabled thinking can emit tool calls as plain text (the call silently never runs) and leak `<thinking>` tags into output. If you must stay thinking-off, delete any don't-think/don't-reason rule and add the combined *"When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response"* — do not name `<thinking>` tags in the prompt
+- [ ] **[TUNE]** Vision pipelines: give it crop/analyze/verify tools — cheaper and more effective than raising thinking
+- [ ] **[TUNE]** Handle `stop_reason: "refusal"` before reading `content`, and opt into `fallbacks: "default"` (`server-side-fallback-2026-07-01`) rather than pinning a model — cyber-category refusals route to Claude Opus 4.8
+- [ ] **[TUNE]** Long-horizon / agentic work: give the complete task spec up front in one turn rather than building it up across interactive turns
+
+---
+
+## Migrating to Claude Sonnet 5
+
+> **Model ID `claude-sonnet-5` is authoritative as written here.** When the user asks to migrate to Claude Sonnet 5, write `model="claude-sonnet-5"` exactly. Do **not** WebFetch to verify — this guide is the source of truth for migration target IDs. The corresponding entry exists in `shared/models.md`.
+
+Claude Sonnet 5 substantially improves on Sonnet 4.6 for coding and agentic work, reaching what was previously Opus-tier quality on many tasks. Its API surface aligns with Opus 4.7/4.8: manual extended thinking is removed (adaptive or disabled only, adaptive is the default), and non-default sampling parameters are rejected. This section is layered on top of the Sonnet 4.6 migration above — if the caller is jumping from Sonnet 4.5 or older, apply the 4.6 changes first, then this one.
+
+**TL;DR for someone already on Sonnet 4.6:** swap the model ID to `claude-sonnet-5`. Replace any remaining `thinking: {type: "enabled", budget_tokens: N}` with `thinking: {type: "adaptive"}` (the transitional escape hatch is gone — it now 400s), and note that omitting `thinking` now runs adaptive (4.6 ran thinking-off). Strip non-default `temperature`/`top_p`/`top_k`. Re-run `count_tokens()` against `claude-sonnet-5` — the new tokenizer produces ~30% more tokens for the same text, so token-budgeted limits and cost baselines shift even though per-token pricing is unchanged. `effort` defaults to `high`, the same as Sonnet 4.6 — raise to `xhigh` for the hardest coding and agentic tasks (Claude Sonnet 5 supports the full `low`/`medium`/`high`/`xhigh`/`max` range), and give `max_tokens` headroom at `xhigh`/`max` (the new tokenizer means a Sonnet-4.6-tuned `max_tokens` may truncate equivalent output). Then re-tune prompts: Claude Sonnet 5 interprets instructions more literally than 4.6 — holdover style/tone directives now apply at face value; it is more agentic by default and reaches for tools and self-verification loops more readily (with thinking disabled it is less tool-eager — add an explicit nudge); it gives better in-progress updates by default (drop forced "summarize every N tool calls" scaffolding); and code-review harnesses with conservative-reporting instructions may see lower recall (tell it to report everything and filter downstream).
+
+### Breaking changes (will 400 on Claude Sonnet 5)
+
+These bring the Sonnet line onto the same request surface as Opus 4.7/4.8. See the **Per-SDK Syntax Reference** above for the language-specific spelling of each.
+
+**1. Extended thinking removed — adaptive only.** `thinking: {type: "enabled", budget_tokens: N}` returns a 400. The transitional escape hatch that still worked on Sonnet 4.6 is gone. Use adaptive thinking with an effort hint:
+
+```python
+# Before — deprecated on Sonnet 4.6, now errors on Claude Sonnet 5
+thinking={"type": "enabled", "budget_tokens": 10000}
+
+# After
+thinking={"type": "adaptive"},
+output_config={"effort": "high"},  # or "xhigh" for the hardest coding/agentic tasks
+```
+
+To turn thinking off entirely, set `thinking: {type: "disabled"}` — but see *Adaptive vs. disabled* below before doing so.
+
+**2. Sampling parameters rejected.** Setting `temperature`, `top_p`, or `top_k` to a non-default value returns a 400; omitting the parameter, or passing its default, is still accepted. The safest migration is to omit them entirely and steer with prompting. If the caller was relying on `temperature=0` for determinism, note in the migration comment that it never guaranteed identical outputs.
+
+```python
+# Before
+client.messages.create(model="claude-sonnet-4-6", temperature=0.2, ...)
+
+# After — omit entirely
+client.messages.create(model="claude-sonnet-5", ...)
+```
+
+**3. Bedrock only: forced `tool_choice` requires `thinking: {type: "disabled"}`.** On Amazon Bedrock, pass `thinking: {type: "disabled"}` alongside `tool_choice: {type: "tool", name: ...}` or `tool_choice: {type: "any"}`. The Claude API and Vertex AI do not require this.
+
+**Not a request-shape error, but handle it: cybersecurity safeguards.** Claude Sonnet 5 is substantially more cyber-capable than Sonnet 4.6, so — like Opus 4.7/4.8 — requests touching prohibited or high-risk topics may be refused. Handle it as a content outcome (see the `refusal` stop-reason guidance in the Claude Fable 5 section if the caller needs a fallback path).
+
+**Unchanged from Sonnet 4.6:** assistant-turn prefills still return a 400 (use `output_config.format` or a system-prompt instruction); the 1M-token context window, the 128k max-output ceiling, prompt caching, batch processing, the Files API, PDF support, vision, and the full server- and client-side tool set all carry over.
+
+### Silent default change: adaptive thinking on when `thinking` is omitted
+
+On Sonnet 4.6, a request with no `thinking` field runs **without** thinking. On Claude Sonnet 5, the same request runs with **adaptive thinking**. This is not an error — but callers who never set `thinking` will now see thinking output (and spend thinking tokens) where they didn't before. `max_tokens` is a hard limit on total output (thinking + response text), so a workload that ran thinking-off on Sonnet 4.6 by omission may now truncate. Either set `thinking: {type: "disabled"}` explicitly to keep the old behavior, or revisit `max_tokens` to leave room for thinking.
+
+### Silent default change: `thinking.display` defaults to `"omitted"`
+
+`thinking.display` defaults to `"omitted"` on Claude Sonnet 5 (matching Opus 4.7/4.8 and Claude Fable 5); on Sonnet 4.6 it defaulted to `"summarized"`. With the default, `thinking` blocks stream with empty text — to a streaming UI this looks like a long pause before output. Combined with the adaptive-on-by-default change above, a Sonnet 4.6 caller who omits `thinking` entirely now gets adaptive thinking *and* empty-text thinking blocks. If you stream reasoning to users, set `thinking: {type: "adaptive", display: "summarized"}` explicitly. `display` controls visibility only — thinking happens and is billed the same under every setting.
+
+### New tokenizer (~30% more tokens)
+
+Claude Sonnet 5 uses the same new tokenizer as Opus 4.7/4.8. The same input text produces approximately 30% more tokens than on Sonnet 4.6. No request/response shape changes and no code edits are required, but **everything measured or budgeted in tokens shifts**: `usage` fields and `count_tokens()` results for the same text are higher, the 1M context window holds less text, and a `max_tokens` limit tuned for Sonnet 4.6 may truncate equivalent output. Per-token pricing is unchanged at the $3/$15 sticker (introductory $2/$10 per MTok applies through 2026-08-31), so the cost of an equivalent request can differ. Re-run `count_tokens()` against `claude-sonnet-5` rather than reusing counts measured against earlier models, and re-baseline cost dashboards before reacting to measured shifts.
+
+### Choosing an effort level on Claude Sonnet 5
+
+`effort` defaults to `high` when not set (same as Sonnet 4.6 and Opus 4.8). Claude Sonnet 5 supports the full `low`/`medium`/`high`/`xhigh`/`max` range — the first Sonnet-tier model with `xhigh`. **Keep the `high` default for most work and raise to `xhigh` for the hardest coding and agentic tasks**:
+
+| Level    | When to use on Claude Sonnet 5 |
+| -------- | ----- |
+| `max`    | Tasks needing the absolute highest capability with no token constraint. Can deliver gains in some use cases but may show diminishing returns and is sometimes prone to overthinking — test before committing |
+| `xhigh`  | The hardest coding and agentic use cases — the recommended setting for those |
+| `high`   | The default; balances token usage and intelligence for most use cases |
+| `medium` | Cost-saving step-down from the default — comparable to Sonnet 4.6 at `high` |
+| `low`    | Short, scoped tasks and latency-sensitive workloads that aren't intelligence-sensitive (chat, simple lookups) |
+
+As a rough cross-model mapping when migrating: Claude Sonnet 5 at `medium` is comparable in intelligence to Sonnet 4.6 at `high`, and Claude Sonnet 5 at `high` is comparable to Sonnet 4.6 at `max`. When benchmarking, match by observed thinking length rather than effort name.
+
+Claude Sonnet 5 **respects effort levels strictly, especially at the low end**. At `low` and `medium` it scopes its work to what was asked rather than going above and beyond — good for latency and cost, but on moderately complex tasks at `low` there is some risk of under-thinking. If you observe shallow reasoning on complex problems, **raise effort to `high` or `xhigh` rather than prompting around it**. If you must keep effort at `low` for latency, add targeted guidance:
+
+> *"This task involves multi-step reasoning. Think carefully through the problem before responding."*
+
+**Leave `max_tokens` headroom at `xhigh`/`max`.** Set a large output token budget (up to the 128k cap, unchanged from Sonnet 4.6) so the model has room for thinking and tool calls. On long tasks, adaptive thinking can use a large share of the budget; if the budget is tight you may see a response that is almost entirely thinking followed by a truncated answer and `stop_reason: "max_tokens"` — raise `max_tokens` or drop to `medium`. Because Claude Sonnet 5 uses the new tokenizer (~30% more tokens for the same text), `max_tokens` limits tuned for Sonnet 4.6 may truncate equivalent output.
+
+### Adaptive vs. disabled thinking
+
+Leave adaptive thinking on. Claude Sonnet 5 calibrates thinking spend to task complexity; the small added latency is usually worth the quality gain. If the caller was running Sonnet 4.6 with thinking off, **try adaptive + `effort: "low"` first** rather than `thinking: {type: "disabled"}`.
+
+The triggering behavior for adaptive thinking is steerable. If the model emits thinking blocks more often than wanted (which can happen with large or complex system prompts), prompt it directly — and measure the effect on quality:
+
+> *"Thinking adds latency and should only be used when it will meaningfully improve answer quality, typically for problems that require multi-step reasoning. When in doubt, respond directly."*
+
+Conversely, if you're running hard workloads at `medium` and seeing under-thinking, the first lever is to raise effort; if you need finer control, prompt for it directly.
+
+### Capability improvements
+
+**Coding and agentic tasks.** The largest gains over Sonnet 4.6 are in coding and agentic tasks. Claude Sonnet 5 performs well out of the box on existing Sonnet 4.6 prompts.
+
+**High-resolution vision.** Claude Sonnet 5 is the first Sonnet-tier model with high-resolution image support: maximum **2576 pixels on the long edge** (up from 1568px on Sonnet 4.6). High-res images can use up to ~3× more image tokens than on Sonnet 4.6 (4784 vs 1568 tokens per image at the limit) — if the added fidelity isn't needed, downsample before sending to control token costs. No beta header or opt-in required.
+
+**Computer use.** Supports the `computer_20251124` tool version (beta header `computer-use-2025-11-24`). Capability works across resolutions up to the 2576px / 3.75MP maximum; sending screenshots at **1080p** provides a good balance of performance and cost. For particularly cost-sensitive workloads, **720p** or **1366×768** are lower-cost options with strong performance. Test to find the ideal settings for the use case; experimenting with `effort` can also help tune behavior.
+
+### Behavioral shifts (prompt-tunable)
+
+None of these break code, but prompts tuned for Sonnet 4.6 may land differently. Claude Sonnet 5 follows instructions closely, so small explicit directives close the gap.
+
+**Response length and verbosity.** Claude Sonnet 5 calibrates response length to task complexity rather than defaulting to a fixed verbosity — usually shorter on simple lookups, longer on open-ended analysis. If a product depends on a particular verbosity, tune the prompt. To decrease verbosity:
+
+> *"Provide concise, focused responses. Skip non-essential context, and keep examples minimal."*
+
+If you see specific kinds of verbosity (e.g. over-explaining), add targeted instructions to prevent them. Positive examples showing the desired concision tend to be more effective than telling the model what not to do.
+
+**Tool use triggering.** Claude Sonnet 5 is more agentic than Sonnet 4.6 by default and will reach for tools and run self-verification loops more readily. **With thinking disabled**, the model is less likely to reach for tools or consider searching — if the harness relies on tool calls with thinking off, add an explicit nudge in the system prompt. `effort` is also a lever: `high` and `xhigh` show substantially more tool usage in agentic search and coding. For scenarios where you want more tool use, also explicitly instruct when and how to use the tools (e.g. if web-search is under-used, describe in the prompt why and how it should be called).
+
+**User-facing progress updates.** Claude Sonnet 5 provides regular, higher-quality updates to the user throughout long agentic traces by default. If the harness has scaffolding to force interim status messages ("After every 3 tool calls, summarize progress"), **try removing it**. If the length or content of the updates isn't well-calibrated to the use case, describe what they should look like in the prompt and provide an example.
+
+**More literal instruction following.** Claude Sonnet 5 interprets prompts literally and explicitly, particularly at lower effort levels. It does not silently generalize an instruction from one item to another, and it does not infer requests that weren't made. The upside is precision — better for carefully tuned prompts, structured extraction, and pipelines that need predictable behavior. If an instruction should apply broadly, **state the scope explicitly** ("Apply this formatting to every section, not just the first one"). The same literalism means style/tone directives carried over from Sonnet 4.6 may now over-apply — re-baseline holdover lines like "be concise" before keeping them.
+
+**Tone and writing style.** Prose style on long-form writing may shift. If a product relies on a specific voice, re-evaluate style prompts against the new baseline. For a warmer or more conversational voice:
+
+> *"Use a warm, collaborative tone. Acknowledge the user's framing before answering."*
+
+Because `temperature`/`top_p`/`top_k` are not accepted on Claude Sonnet 5, callers who previously relied on `temperature` for stylistic variety must use system-prompt instructions instead.
+
+**Code review harnesses.** A review harness tuned for an earlier model may initially see lower recall on Claude Sonnet 5. This is likely a harness effect, not a capability regression: when a review prompt says "only report high-severity issues" / "be conservative" / "don't nitpick," Claude Sonnet 5 follows that instruction more faithfully than earlier models did — it investigates just as thoroughly, identifies the bugs, and then doesn't report findings it judges below the stated bar. Precision typically rises, but measured recall can fall even though underlying bug-finding ability has improved. Recommended prompt language:
+
+> *"Report every issue you find, including ones you are uncertain about or consider low-severity. Do not filter for importance or confidence at this stage — a separate verification step will do that. Your goal here is coverage: it is better to surface a finding that later gets filtered out than to silently drop a real bug. For each finding, include your confidence level and an estimated severity so a downstream filter can rank them."*
+
+This works even without an actual second step, but moving confidence filtering out of the finding stage often helps. If you do want single-pass self-filtering, be concrete about where the bar is rather than using qualitative terms like "important" — e.g. "report any bugs that could cause incorrect behavior, a test failure, or a misleading result; only omit nits like pure style or naming preferences." Iterate against a subset of evals to validate recall/F1 gains.
+
+**Design and frontend defaults.** Claude Sonnet 5 may settle into a consistent default visual style on open-ended frontend and design briefs. Generic instructions ("don't use that color," "make it clean and minimal") tend to shift it to a different fixed palette rather than producing variety. Two approaches work reliably: **specify a concrete alternative** (the model follows explicit specs precisely — give the palette, typography, layout, and spacing), or **have the model propose options before building** (e.g. "Before building, propose 4 distinct visual directions tailored to this brief — bg hex / accent hex / typeface plus a one-line rationale — ask the user to pick one, then implement only that direction"). Because `temperature` isn't accepted on Claude Sonnet 5, the propose-then-pick approach is the recommended way to get meaningfully different design directions across runs. To steer away from generic AI-aesthetic patterns, a short directive in the system prompt also helps:
+
+> *"NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white or dark backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. Use unique fonts, cohesive colors and themes, and animations for effects and micro-interactions."*
+
+**Interactive coding products.** Token usage and behavior can differ between autonomous, asynchronous coding agents (single user turn) and interactive, synchronous coding agents (multiple user turns). To maximize both performance and token efficiency, use `effort: "xhigh"` or `"high"`, add autonomous features like an auto mode, and reduce the number of human interactions required. Specify task, intent, and constraints upfront in the first turn — well-specified initial prompts maximize autonomy and intelligence while minimizing extra token usage after user turns; ambiguous or progressively-revealed prompts tend to reduce token efficiency and sometimes performance.
+
+### Claude Sonnet 5 Migration Checklist
+
+Every item is tagged: **`[BLOCKS]`** items cause a 400 error or truncated output if missed; **`[TUNE]`** items are quality/cost adjustments — surface them to the user as recommendations.
+
+- [ ] **[BLOCKS]** Update the `model=` string to `claude-sonnet-5`
+- [ ] **[BLOCKS]** Replace `thinking: {type: "enabled", budget_tokens: N}` with `thinking: {type: "adaptive"}` + `output_config.effort` — the Sonnet 4.6 transitional escape hatch is gone
+- [ ] **[BLOCKS]** Strip `temperature`, `top_p`, `top_k` from request construction (use system-prompt instructions for tone/variety instead)
+- [ ] **[BLOCKS]** Bedrock only: pass `thinking: {type: "disabled"}` alongside forced `tool_choice` (`{type: "tool"}` / `{type: "any"}`) — not required on the Claude API or Vertex AI
+- [ ] **[BLOCKS]** At `effort: "xhigh"` or `"max"`: set a large `max_tokens` (up to 128k, unchanged from Sonnet 4.6) so the model has room for thinking and tool calls — Sonnet-4.6-tuned limits may truncate equivalent output under the new tokenizer (symptom: `stop_reason: "max_tokens"`)
+- [ ] **[TUNE]** Thinking-field omitted: adaptive is now the default (4.6 ran thinking-off) — either set `thinking: {type: "disabled"}` to preserve the old behavior, or revisit `max_tokens` for the added thinking spend
+- [ ] **[TUNE]** `thinking.display` defaults to `"omitted"` (4.6 defaulted to `"summarized"`): if you stream reasoning to users, set `thinking: {type: "adaptive", display: "summarized"}` explicitly — the default streams empty-text thinking blocks (long pause before output)
+- [ ] **[TUNE]** New tokenizer: re-run `count_tokens()` against `claude-sonnet-5` (~30% more tokens for the same text); revisit `max_tokens` and compaction triggers sized close to expected output length; re-baseline cost dashboards before reacting (per-token pricing unchanged)
+- [ ] **[TUNE]** Effort: keep the `high` default; raise to `xhigh` for the hardest coding/agentic tasks; `medium` is a cost-saving step-down (≈ Sonnet 4.6 at `high`); reserve `low` for short, latency-sensitive, non-intelligence-sensitive tasks. If shallow reasoning shows up at `low`/`medium`, raise effort rather than prompting around it
+- [ ] **[TUNE]** Thinking-off callers: try `thinking: {type: "adaptive"}` + `effort: "low"` instead of `disabled`; if `disabled` must stay, add an explicit tool-triggering nudge (the model is less tool-eager with thinking off)
+- [ ] **[TUNE]** Tool usage: more agentic than 4.6 by default (reaches for tools and self-verification more readily) — `effort` is a lever (`high`/`xhigh` for more tool use); add explicit when/how triggering instructions for under-used tools
+- [ ] **[TUNE]** Drop forced progress-update scaffolding ("after every N tool calls, summarize") — the default updates are higher quality; describe the desired update shape if it still needs tuning
+- [ ] **[TUNE]** Re-baseline holdover style/tone/scope directives — instructions are followed literally; state the scope explicitly when one should apply broadly
+- [ ] **[TUNE]** Verbosity-sensitive routes: tune response length via prompt (positive examples > "don't" instructions)
+- [ ] **[TUNE]** Code-review harnesses with conservative-reporting instructions ("only high-severity", "don't nitpick"): switch to a coverage-first prompt (report everything with confidence + severity) and filter downstream — measured recall can otherwise fall even though bug-finding improved
+- [ ] **[TUNE]** Open-ended frontend/design briefs: specify a concrete spec, or have the model propose 3–4 visual directions and pick one (the recommended substitute for `temperature`-driven variety)
+- [ ] **[TUNE]** Interactive coding products: use `effort: "xhigh"`/`"high"`, add autonomous features (e.g. auto mode), and put task/intent/constraints in the first turn
+- [ ] **[TUNE]** Vision-heavy / computer-use pipelines: leave images at native resolution up to 2576px long edge for the accuracy gain (downsample to control image-token cost if fidelity isn't needed); for computer use, 1080p screenshots are a good performance/cost balance with `computer_20251124`
+- [ ] **[TUNE]** Security workloads: add handling for safeguard refusals (cyber-capable topics may now be declined where Sonnet 4.6 answered)
 
 ---
 
@@ -892,7 +1299,7 @@ For a caller **already on Opus 4.7**, only the first item is required; everythin
 
 Claude Fable 5 is Anthropic's most capable widely released model — for the most demanding reasoning and long-horizon agentic work. **Claude Mythos 5** (`claude-mythos-5`) offers the same capabilities, pricing, and API behavior through Project Glasswing (participation is the only way to access it), and succeeds the invitation-only **Claude Mythos Preview** (`claude-mythos-preview`). Everything in this section applies to both models — only the ID differs. Mythos Preview migrators in Project Glasswing target `claude-mythos-5`; everyone else targets `claude-fable-5`. 1M token context window by default (the maximum is also the default), up to 128K output tokens per request.
 
-**Migrate to Claude Fable 5 only when the user explicitly chose it.** It is not the default Opus upgrade path — pricing is above Opus-tier and the new tokenizer changes cost baselines. For "upgrade to the latest model" requests, the target remains `claude-opus-4-8`.
+**Migrate to Claude Fable 5 only when the user explicitly chose it.** It is not the default Opus upgrade path — pricing is above Opus-tier. For "upgrade to the latest model" requests, the target remains `claude-opus-5`.
 
 ### Breaking changes (vs Opus-tier and Mythos Preview)
 
@@ -920,28 +1327,28 @@ Claude Fable 5 is Anthropic's most capable widely released model — for the mos
 
 3. **Interleaved scratchpad is not supported** (Mythos Preview migrators only). Inter-tool reasoning is returned in thinking blocks instead, which adaptive thinking produces automatically between tool calls.
 
-### Protected thinking — always encrypted, model-specific
+### Thinking output on Claude Fable 5 and Claude Mythos 5
 
-Claude Fable 5's `protected_thinking` policy protects the **raw chain of thought** — it is never exposed in responses. What you receive are **regular `thinking` blocks**, not encrypted blobs or `redacted_thinking`: `display: "summarized"` returns a readable summary of the reasoning, and with `"omitted"` — the default, same as Opus 4.8/4.7 — responses still include `thinking` blocks but the `thinking` field is an empty string. `display` controls visibility only; thinking happens and is billed the same under every setting. What's stricter on Claude Fable 5 is **replay**: pass thinking blocks back to the API **unchanged** when continuing a conversation on the same model (the standard multi-turn pattern; dropping or editing them breaks the turn).
+On Claude Fable 5 and Claude Mythos 5, the raw chain of thought is never returned. What you receive are **regular `thinking` blocks**, not encrypted blobs or `redacted_thinking`: `display: "summarized"` returns a readable summary of the reasoning, and with `"omitted"` — the default, same as Opus 4.8/4.7 — responses still include `thinking` blocks but the `thinking` field is an empty string. `display` controls visibility only; thinking happens and is billed the same under every setting. When continuing a conversation on the same model, pass thinking blocks back to the API **unchanged** (the standard multi-turn pattern; dropping or editing them breaks the turn).
 
 When continuing on the same model, pass each thinking block back **exactly as received — including blocks whose `thinking` text is empty**. The API rejects blocks whose content has been *modified*, not blocks you have read; displaying the summary is fine, editing or reconstructing blocks is not.
 
-Thinking blocks are tied to the model that produced them, but cross-model replay is forgiving: other models **silently ignore** them rather than rejecting the request (early-access builds returned `invalid_request_error`; that was reverted before launch). Ignored blocks still bill input tokens, though — so when switching models for good, e.g. after a classifier refusal, strip `thinking`/`redacted_thinking` blocks from prior assistant turns to avoid paying for dead weight. Two exceptions: fallback-credit retries must echo the refused body **unchanged**, and `fallback` blocks from a mid-output fallback stay where they appeared.
+Regular thinking blocks aren't origin-locked — they replay across models fine (the server renders them into the target model's prompt). Claude Fable 5/Claude Mythos 5 thinking is the exception: a thinking block from these models replayed to a different model is **dropped from the prompt** rather than rendered — typically silently (early-access builds hard-rejected with `invalid_request_error`; that broke workflows and was reverted before launch, but the new behavior is still rolling out, so don't build logic that depends on either outcome). The drop happens before the prompt is priced, so a dropped block **lowers `usage.input_tokens`** — you aren't billed for it, and there's nothing to strip for cost. Don't strip *regular* thinking blocks either: removing them can trigger ordering/signature 400s. Two rules for replay bodies stand regardless: fallback-credit retries must echo the refused body **unchanged**, and `fallback` blocks from a mid-output fallback stay where they appeared.
 
 Related: a request that tries to elicit the model's internal reasoning *in the response text* can be refused with `stop_details.category: "reasoning_extraction"` — applications needing reasoning visibility should read the summarized `thinking` blocks instead of prompting for reasoning.
 
-### New tokenizer — re-baseline tokens and cost
+### Tokenizer — unchanged from Opus 4.8
 
-Claude Fable 5 uses a new tokenizer. The same content tokenizes to **roughly 30% more tokens** than on Opus-tier and older models (varies by content and workload shape). Billing is per token, so an unchanged workload can cost more after migration even before the per-token price difference.
+Claude Fable 5 uses the **same tokenizer as Claude Opus 4.8** (the tokenizer introduced with Opus 4.7). Token counts are roughly unchanged when migrating from Opus 4.7/4.8 or from `claude-mythos-preview`; per-token pricing differs.
 
-- Coming **from `claude-mythos-preview`**: token counts are roughly unchanged (same tokenizer family).
-- Coming **from Opus/Sonnet/Haiku**: do not reuse token counts, context-window budgets, or `max_tokens` settings measured on the old model.
+- Coming **from Opus 4.7/4.8 or `claude-mythos-preview`**: token counts are roughly unchanged. Re-baseline cost and latency on your own workloads for the per-token price difference.
+- Coming **from Opus 4.6, Sonnet, Haiku, or older**: the Opus 4.7 tokenizer tokenizes the same content to roughly 1×–1.35× as many tokens (varies by content and workload shape). Do not reuse token counts, context-window budgets, or `max_tokens` settings measured on the old model; re-baseline with `count_tokens`.
 
-The token counting endpoint returns counts under **both** tokenizers when you pass `model: "claude-fable-5"` — `input_tokens` (new tokenizer, what you're billed) plus `input_tokens_prior_tokenizer` (the same request under the prior-generation tokenizer) — so you can measure the delta on your own prompts before switching.
+To measure the difference on your own prompts, call `count_tokens` once with your current model and once with `model: "claude-fable-5"`, and compare the two `input_tokens` values.
 
 ### `refusal` stop reason — handle before reading content
 
-Claude Fable 5 runs safety classifiers on incoming requests, targeting research biology and most cybersecurity content (Claude Fable 5 is not intended for those domains); benign adjacent work — security tooling, life-sciences tasks — can occasionally trigger false positives, which is why the fallback patterns below matter even for legitimate workloads. (Most Claude consumer surfaces ship with built-in Opus 4.8 fallbacks; API callers configure their own.) A declined request returns a **successful HTTP 200** with `stop_reason: "refusal"`, plus a `stop_details` object with the policy category (`"cyber"`, `"bio"`, `"reasoning_extraction"`, or `null` — treat `null` as a permanent valid state). **Branch on `stop_reason`, never on `stop_details`** — `stop_details` is informational and can be `null` even on a refusal, and `explanation` is not guaranteed present. Note that classifier blocks and ordinary model refusals (the model itself declining) both surface as `stop_reason: "refusal"`; `stop_details.category` tells you which class you're handling, and therefore whether retrying on a fallback model is the right response. The classifier can fire **before any output** (empty `content` array; not billed at all — no input or output tokens, no rate-limit consumption) or **mid-stream** after partial output (already-streamed output is billed at normal rates — discard the partial output rather than treating it as complete). Code that reads `response.content[0]` unconditionally will break — check `stop_reason` first:
+Claude Fable 5 runs safety classifiers on incoming requests, targeting research biology and most cybersecurity content (Claude Fable 5 is not intended for those domains); benign adjacent work — security tooling, life-sciences tasks — can occasionally trigger false positives, which is why the fallback patterns below matter even for legitimate workloads. (Most Claude consumer surfaces ship with built-in Opus 4.8 fallbacks; API callers configure their own.) A declined request returns a **successful HTTP 200** with `stop_reason: "refusal"`, plus a `stop_details` object with the policy category (values such as `"cyber"`, `"bio"`, `"reasoning_extraction"`, `"frontier_llm"`, or `null` — treat `null` as a permanent valid state; see the refusal category table in the public docs for the full set). **Branch on `stop_reason`, never on `stop_details`** — `stop_details` is informational and can be `null` even on a refusal, and `explanation` is not guaranteed present. Note that classifier blocks and ordinary model refusals (the model itself declining) both surface as `stop_reason: "refusal"`; `stop_details.category` tells you which class you're handling, and therefore whether retrying on a fallback model is the right response. The classifier can fire **before any output** (empty `content` array; not billed at all — no input or output tokens, no rate-limit consumption) or **mid-stream** after partial output (already-streamed output is billed at normal rates — discard the partial output rather than treating it as complete). Code that reads `response.content[0]` unconditionally will break — check `stop_reason` first:
 
 ```python
 response = client.messages.create(model="claude-fable-5", max_tokens=1024, messages=[...])
@@ -952,9 +1359,11 @@ else:
     print(response.content[0].text)
 ```
 
+**Default to opting in.** Fallbacks are not automatic on the API — a request without them simply stops on a refusal. Migrated and new Claude Fable 5 code should ship with pattern 1 below (pattern 2 on providers without server-side support) from day one, not as a later hardening step: emit the opt-in in the code, tell the user it's there, and remove it only if they decline.
+
 Three ways to retry a refused request on another model, in order of preference:
 
-**1. Server-side `fallbacks` parameter (beta: Claude API and Claude Platform on AWS) — preferred.** One round trip, a plain client, no client-side logic. Name substitute models (the only supported fallback target at launch is `claude-opus-4-8`, expansion expected); on a policy decline the API runs the next model on the same request and returns its answer, with credit-style repricing applied automatically. A `stop_reason: "refusal"` on the final response means the whole chain refused.
+**1. Server-side `fallbacks` parameter (beta; Claude API and Claude Platform on AWS) — preferred.** One round trip, a plain client, no client-side logic. Name substitute models (the only supported fallback target at launch is `claude-opus-4-8`, expansion expected); on a policy decline the API runs the next model on the same request and returns its answer, with credit-style repricing applied automatically. A `stop_reason: "refusal"` on the final response means the whole chain refused.
 
 ```python
 response = client.beta.messages.create(
@@ -970,23 +1379,26 @@ for block in response.content:
     if block.type == "fallback":
         print(f"{block.from_.model} declined; {block.to.model} continued")
 
-# Served-by signal: covers every fallback-served turn, INCLUDING sticky turns
-# (sticky-served turns carry no fallback block — nothing declined this turn)
-iterations = getattr(response.usage, "iterations", None) or []
-if any(entry.type == "fallback_message" for entry in iterations):
+# Served-by signal: a fallback_message in usage.iterations means a fallback model
+# ran; pair it with stop_reason to confirm the fallback served the response
+# (a fallback model can also refuse). Covers sticky turns too.
+fallback_ran = any(
+    entry.type == "fallback_message" for entry in response.usage.iterations or []
+)
+if fallback_ran and response.stop_reason != "refusal":
     print(f"Served by {response.model}")
 ```
 
 Key semantics:
 
-- **Header must be exactly `server-side-fallback-2026-06-01`** — other `server-side-fallback-*` values reject the `fallbacks` param with a 400. The current header carries the *earliest* date of the series (`-2026-06-09` and `-2026-06-02` were earlier previews) — do not "correct" it to a newer-looking date. Rejected on the Batches API; not available on Bedrock/Vertex (use pattern 2 there — the SDK middleware). Entries may override `max_tokens` per hop (bounding that attempt's own output independently of the top-level `max_tokens`); `thinking`, `output_config`, and `speed` overrides are rolling out (`speed` additionally requires its beta) — until your requests accept them, include only `model` and `max_tokens` in each entry. Entries must be distinct and must be in the requested model's `allowed_fallback_models` (visible on `/v1/models` under the beta). The request *with an entry's overrides merged in* must be valid as a direct request to that entry's model.
+- **Header depends on the form you use.** The **array** form (`fallbacks: [{...}]`) requires exactly `server-side-fallback-2026-06-01` — other `server-side-fallback-*` values reject it with a 400, and that header carries the *earliest* date of the series (`-2026-06-09` and `-2026-06-02` were earlier previews), so do not "correct" it to a newer-looking date. The **`"default"` scalar** form uses `server-side-fallback-2026-07-01` instead — see § New API features under Migrating to Claude Opus 5. Pairing either header with the other form 400s. Rejected on the Batches API; available on the Claude API and Claude Platform on AWS; not on Amazon Bedrock, Vertex AI, or Microsoft Foundry (use pattern 2 there — the SDK middleware). Entries may override `max_tokens` per hop (bounding that attempt's own output independently of the top-level `max_tokens`); `thinking`, `output_config`, and `speed` overrides are rolling out (`speed` additionally requires its beta) — until your requests accept them, include only `model` and `max_tokens` in each entry. Entries must be distinct and must be in the requested model's `allowed_fallback_models` (published on `/v1/models` when the `server-side-fallback-2026-06-01` beta header is set — not yet visible under the `fallback-credit-*` header alone, and not exposed on Amazon Bedrock, Vertex AI, or Microsoft Foundry). The request *with an entry's overrides merged in* must be valid as a direct request to that entry's model.
 - **Triggers on policy declines only** — rate limits, overloads, and server errors on the requested model are returned as-is, never falling back.
 - **Reading the response:** a `fallback` content block (`{"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}`) marks each switch point in `content`; the served-by signal is a `fallback_message` entry in `usage.iterations` (don't rely on the block — sticky-served turns have none). Top-level `model` names the model that produced the message.
-- **Billing:** `usage.iterations` is the per-attempt source of truth; top-level `usage` covers only the attempt that produced the returned message. Declined-before-output attempts are reported but not billed; fallback attempts bill at the fallback model's rates. Each attempt claims the rate limits of the model that ran it — if the fallback model is rate-limited or overloaded, the refusal is returned instead with `stop_details.recommended_model` naming the canonical model ID to retry directly (populated only when the request included `fallbacks` and the attempt couldn't be made) — size fallback-model limits for expected refusal volume.
+- **Billing:** `usage.iterations` is the per-attempt source of truth; top-level `usage` covers only the attempt that produced the returned message. Declined-before-output attempts are reported but not billed; fallback attempts bill at the fallback model's rates. Each attempt claims the rate limits of the model that ran it — if the fallback model is rate-limited or overloaded, the fallback attempt is not made and the preceding refusal is returned instead with `stop_details.recommended_model` naming a model to retry directly (the recommendation is a hint, not a guarantee, and is `null` when no recommendation is available) — size fallback-model limits for expected refusal volume.
 - **Sticky routing:** once a conversation falls back, later non-streaming requests with `fallbacks` are served directly by the fallback model for ~1 hour (best-effort; org-scoped content-hash record, not message content; not recorded for ZDR orgs). Handle the requested model being tried again at any time.
 - **Echoing fallback turns back:** after a mid-output fallback, omit `thinking`, `redacted_thinking`, and `tool_use` blocks — plus any `server_tool_use` block without its matching `server_tool_result`, and any other unrecognized model-internal block type — that appear *before* the final `fallback` block; text blocks, paired server-tool blocks, and everything after the boundary echo normally. The `fallback` block itself is an ignored audit marker (keep or drop). Streaming: the retry happens on the same stream and already-received content is never invalidated — a pre-output block is seamless (`message_start` names the fallback model; the `fallback` block arrives as an ordinary `content_block_start`, first in `content` — there is no special SSE event type; note `message_start` arrives only after the declined attempt, so time-to-first-byte includes it), and a mid-stream block keeps the partial, marks the boundary with the block, and continues — only the partial's `text` blocks are passed to the fallback model as continuation context (other block types stay in `content` but aren't part of it). Sticky routing is **not consulted on streaming requests** in the initial release, so on streams the `fallback` block check is the complete signal; non-streaming mid-output declines omit the declined partial entirely.
 
-**2. SDK client-side middleware — for providers without server-side fallbacks (Bedrock, Vertex).** Register it on the client and every `client.beta.messages` request (streaming included) retries refusals automatically, splicing the fallback model's events onto the open stream in the same wire shape as pattern 1 (a `fallback` content block at each boundary, per-hop `usage.iterations`). It is also a beta surface: the middleware sends the `fallback-credit-2026-06-01` header by default so retries are repriced via credit tokens (override with its `betas` option). `BetaFallbackState` pins follow-up turns to the model that accepted (the client-side analog of sticky routing) — reuse one state object per conversation:
+**2. SDK client-side middleware — for providers without server-side fallbacks (Amazon Bedrock, Vertex AI, Microsoft Foundry).** Register it on the client and every `client.beta.messages` request (streaming included) retries refusals automatically, splicing the fallback model's events onto the open stream in the same wire shape as pattern 1 (a `fallback` content block at each boundary, per-hop `usage.iterations`). It is also a beta surface: the middleware sends the `fallback-credit-2026-06-01` header by default so retries are repriced via credit tokens (override with its `betas` option). `BetaFallbackState` pins follow-up turns to the model that accepted (the client-side analog of sticky routing) — reuse one state object per conversation:
 
 ```python
 from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware
@@ -1005,13 +1417,13 @@ Create **one state per conversation** — it is the pinning scope; sharing one a
 
 For languages not listed (Java, Ruby, PHP) — or for a full runnable program in any language — each public SDK repo ships a fallbacks example under `examples/` (e.g. `examples/fallbacks.py`, `examples/refusal-fallback/`): WebFetch the repo from `shared/live-sources.md` § SDK Repositories rather than improvising the binding.
 
-**3. Hand-rolled retry + fallback credit (raw HTTP, or SDKs without the middleware).** Detect the refusal via `stop_reason` and re-send the conversation as-is on a model with broader availability such as `claude-opus-4-8` (Claude Fable 5's protected thinking blocks are silently ignored by other models — no stripping required); keep using the fallback model for subsequent turns. **Fallback credit** (beta: Claude API, Bedrock, Vertex) makes those retries cheaper. Prompt caches are per-model, so a plain retry pays cold cache-writes on the new model. With the `fallback-credit-2026-06-01` beta header (send it on both the original request and the retry), a refusal's `stop_details` carries `fallback_credit_token` (opaque; `null` when unavailable) and `fallback_has_prefill_claim`. Echo the token as the top-level `fallback_credit_token` request parameter on the retry (typed in the GA SDKs; on a pre-GA SDK pass it via `extra_body`) and the previously-cached span bills at cache-read rates — the retry costs what it would have if the conversation had been on that model all along. Rules: the retry body must match the refused request **exactly** in every prompt-shaping field (`system`, `messages`, `tools`, `tool_choice`, `thinking` — do **not** strip thinking blocks when redeeming a credit — the server handles them); the retry model must be in the refused model's `allowed_fallback_models`; the token expires in 5 minutes; Batches results carry no tokens. If `fallback_has_prefill_claim` is `true`, append one assistant message echoing the refused response's `content` — the retry model continues from where the refused model stopped (and completed server-tool work isn't re-run). When echoing, strip trailing whitespace from a final `text` block (the prefill validator rejects it; the credit match tolerates that edit), after omitting any unpaired `tool_use` blocks. On a 400, fall back to the unchanged body with the token; on a 400 naming `fallback_credit_token`, retry without it (credit forfeited).
+**3. Hand-rolled retry + fallback credit (raw HTTP, or SDKs without the middleware).** Detect the refusal via `stop_reason` and re-send the conversation as-is on a model with broader availability such as `claude-opus-4-8` (Claude Fable 5's thinking blocks are silently ignored by other models — no stripping required); keep using the fallback model for subsequent turns. **Fallback credit** (beta: Claude API, Claude Platform on AWS, Amazon Bedrock, Vertex AI, and Microsoft Foundry) makes those retries cheaper. Prompt caches are per-model, so a plain retry pays cold cache-writes on the new model. With the `fallback-credit-2026-06-01` beta header (send it on both the original request and the retry), a refusal's `stop_details` carries `fallback_credit_token` (opaque; `null` when unavailable) and `fallback_has_prefill_claim`. Echo the token as the top-level `fallback_credit_token` request parameter on the retry (typed in the GA SDKs; on a pre-GA SDK pass it via `extra_body`) and the previously-cached span bills at cache-read rates — the retry costs what it would have if the conversation had been on that model all along. Rules: the retry body must match the refused request **exactly** in every prompt-shaping field (`system`, `messages`, `tools`, `tool_choice`, `thinking` — do **not** strip thinking blocks when redeeming a credit — the server handles them); the retry model must be in the refused model's `allowed_fallback_models`; the token expires in 5 minutes; Batches results carry no tokens. If `fallback_has_prefill_claim` is `true`, append one assistant message echoing the refused response's `content` — the retry model continues from where the refused model stopped (and completed server-tool work isn't re-run). When echoing, strip trailing whitespace from a final `text` block (the prefill validator rejects it; the credit match tolerates that edit), after omitting any unpaired `tool_use` blocks. On a 400, fall back to the unchanged body with the token; on a 400 naming `fallback_credit_token`, retry without it (credit forfeited).
 
 **Migrating code built on the v1 preview.** If the code you're editing carries any of these markers, it targets the discontinued early-access surface — migrate it to the v2 shapes above, and ship the header and parameter changes together (the v1 parameter shape under the v2 header is a 400):
 
 | v1 marker (replace) | v2 |
 |---|---|
-| `server-side-fallback-2026-06-09` / `-2026-06-02` header | `server-side-fallback-2026-06-01` |
+| `server-side-fallback-2026-06-09` / `-2026-06-02` header | `server-side-fallback-2026-06-01` (array form; the `"default"` scalar form uses `-2026-07-01`) |
 | `fallback: {model, on_partial}` single object | `fallbacks: [{model, ...}]` array (1–3); `on_partial` no longer exists — partial-output behavior is fixed (streams keep the partial; non-streaming omits it). Unknown keys in an entry are a 400 |
 | Top-level `response.fallback` object (`from_model`, `reason`) | Never emitted — read `fallback` content blocks (switch points, no `reason` field) and `usage.iterations` (served-by) |
 | `event: fallback` SSE with discard indices | No dedicated event; streamed content is never invalidated — the switch arrives as an ordinary `content_block_start`/`stop` pair of type `fallback` |
@@ -1096,7 +1508,7 @@ None of these are API-breaking, but they're where migrated workloads feel differ
 }
 ```
 
-For agents that only narrate routine progress, default summaries are typically adequate without this tool.
+For agents that only narrate routine progress, the model's default progress narration is typically adequate without this tool.
 
 ### Claude Fable 5 Migration Checklist
 
@@ -1105,9 +1517,10 @@ For agents that only narrate routine progress, default summaries are typically a
 - [ ] **[BLOCKS]** Replace assistant prefill with structured outputs or system prompt instructions
 - [ ] **[BLOCKS]** Confirm the org meets the 30-day data-retention requirement (ZDR orgs get `400 invalid_request_error` on every request)
 - [ ] **[BLOCKS]** Remove all other `thinking` configuration (`{type: "enabled", budget_tokens: N}` returns a 400, same as on Opus 4.7/4.8); control depth with `output_config.effort` instead
-- [ ] **[TUNE]** Re-baseline token counts, context budgets, `max_tokens`, and cost — ~30% more tokens vs Opus-tier (roughly unchanged from Mythos Preview); use `count_tokens` with `model: "claude-fable-5"` to measure
-- [ ] **[TUNE]** Add `stop_reason == "refusal"` handling before reading `response.content` (pre-output: empty + unbilled; mid-stream: partial output billed — discard); pick a retry strategy — client-side (replay history as-is; other models ignore Fable's thinking blocks), fallback credit (`fallback-credit-2026-06-01`, exact body), or server-side `fallbacks` (`server-side-fallback-2026-06-01`, Claude API and Claude Platform on AWS)
-- [ ] **[TUNE]** If you surfaced thinking text to users, plan for protected (encrypted) thinking — pass blocks back unchanged on the same model, never render or cross-model them
+- [ ] **[BLOCKS]** If thinking content is surfaced to users or stored in logs: add `thinking: {type: "adaptive", display: "summarized"}` (the default is `"omitted"` — otherwise the rendered text is empty)
+- [ ] **[TUNE]** Re-baseline cost and latency on your own workloads — token counts are roughly unchanged from Opus 4.7/4.8 and Mythos Preview (same tokenizer); per-token pricing differs. Coming from Opus 4.6, Sonnet, Haiku, or older, token counts differ — use `count_tokens` with each model to compare
+- [ ] **[TUNE]** Add `stop_reason == "refusal"` handling before reading `response.content` (pre-output: empty + unbilled; mid-stream: partial output billed — discard); opt into a fallback by default — server-side `fallbacks` (Claude API and Claude Platform on AWS: `fallbacks: "default"` with `server-side-fallback-2026-07-01`, or the array form with `server-side-fallback-2026-06-01`) where available, otherwise the SDK middleware or fallback credit (`fallback-credit-2026-06-01`, exact body); a bare client-side replay (history as-is; other models drop Fable's thinking blocks) is the floor, not the recommendation
+- [ ] **[TUNE]** If you surfaced thinking text to users, plan for the thinking output change — the raw chain of thought is never returned; render the `display: "summarized"` summary (per the [BLOCKS] item above); pass blocks back unchanged on the same model; other models drop them from the prompt (unbilled)
 - [ ] **[TUNE]** Plan for minutes-long turns: timeouts, streaming, async check-ins, progress UX (see Behavior changes above)
 - [ ] **[TUNE]** Run an effort sweep including low/medium for routine workloads; add the no-tidying instruction if higher effort produces unrequested refactors
 - [ ] **[TUNE]** A/B with prior-model scaffolding removed — over-prescriptive prompts/skills reduce Claude Fable 5 output quality
@@ -1116,10 +1529,10 @@ For agents that only narrate routine progress, default summaries are typically a
 
 ## Verify the Migration
 
-After updating, spot-check that the new model is actually being used. Replace `YOUR_TARGET_MODEL` with the model string you migrated to (e.g. `claude-fable-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`) and keep the assertion prefix in sync:
+After updating, spot-check that the new model is actually being used. Replace `YOUR_TARGET_MODEL` with the model string you migrated to (e.g. `claude-fable-5`, `claude-opus-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-5`, `claude-sonnet-4-6`, `claude-haiku-4-5`) and keep the assertion prefix in sync:
 
 ```python
-YOUR_TARGET_MODEL = "claude-opus-4-8"  # or "claude-opus-4-7", "claude-sonnet-4-6", "claude-haiku-4-5"
+YOUR_TARGET_MODEL = "claude-opus-5"  # or "claude-opus-4-7", "claude-sonnet-5", "claude-sonnet-4-6", "claude-haiku-4-5"
 response = client.messages.create(model=YOUR_TARGET_MODEL, max_tokens=64, messages=[...])
 assert response.model.startswith(YOUR_TARGET_MODEL), response.model
 ```

skills/claude-api/shared/models.md

@@ -59,19 +59,23 @@ curl https://api.anthropic.com/v1/models/claude-opus-4-8 \
 |-------------------|---------------------|-------------------------------|----------------|------------|--------|
 | Claude Fable 5    | `claude-fable-5`      | —                             | 1M             | 128K       | Active |
 | Claude Mythos 5   | `claude-mythos-5`     | —                             | 1M             | 128K       | Active (Project Glasswing only) |
+| Claude Opus 5     | `claude-opus-5`       | —                             | 1M             | 128K       | Active |
 | Claude Opus 4.8   | `claude-opus-4-8`   | —                             | 1M             | 128K       | Active |
 | Claude Opus 4.7   | `claude-opus-4-7`   | —                             | 1M             | 128K       | Active |
 | Claude Opus 4.6   | `claude-opus-4-6`   | —                             | 1M             | 128K       | Active |
-| Claude Sonnet 4.6 | `claude-sonnet-4-6` | -                             | 1M             | 64K        | Active |
+| Claude Sonnet 5 | `claude-sonnet-5` | —                         | 1M             | 128K       | Active |
+| Claude Sonnet 4.6 | `claude-sonnet-4-6` | -                             | 1M             | 128K       | Active |
 | Claude Haiku 4.5  | `claude-haiku-4-5`  | `claude-haiku-4-5-20251001`   | 200K           | 64K        | Active |
 
 ### Model Descriptions
-- **Claude Fable 5** — Anthropic's most capable widely released model, for the most demanding reasoning and long-horizon agentic work. Same API surface as Opus 4.7/4.8 with one new breaking change: an explicit `thinking: {type: "disabled"}` returns a 400 — omit the `thinking` parameter instead (thinking is always on, returned in protected/encrypted form). New tokenizer (~30% more tokens than Opus-tier for the same content). Safety classifiers may return `stop_reason: "refusal"`. No assistant prefill. Requires 30-day data retention (not available under ZDR). $10/$50 per MTok; 1M context window (default), 128K max output. See `shared/model-migration.md` → Migrating to Claude Fable 5.
+- **Claude Fable 5** — Anthropic's most capable widely released model, for the most demanding reasoning and long-horizon agentic work. Same API surface as Opus 4.7/4.8 with one new breaking change: an explicit `thinking: {type: "disabled"}` returns a 400 — omit the `thinking` parameter instead (thinking is always on; the raw chain of thought is never returned — summaries via `display: "summarized"`). Same tokenizer as Opus 4.8 (token counts roughly unchanged vs Opus 4.7/4.8). Safety classifiers may return `stop_reason: "refusal"`. No assistant prefill. Requires 30-day data retention (not available under ZDR). $10/$50 per MTok; 1M context window (default), 128K max output. See `shared/model-migration.md` → Migrating to Claude Fable 5.
 - **Claude Mythos 5** — Same capabilities, pricing, limits, and API behavior as Claude Fable 5; only the model ID differs. Available exclusively through Project Glasswing, where it joins (and succeeds) the invitation-only Claude Mythos Preview (`claude-mythos-preview`). Use it only when the org participates in Project Glasswing; otherwise use claude-fable-5.
-- **Claude Opus 4.8** — The most capable Opus-tier model — highly autonomous, state-of-the-art on long-horizon agentic work, knowledge work, and memory; clearer, warmer writing. Same API surface as Opus 4.7 (adaptive thinking only; sampling parameters and `budget_tokens` removed). 1M context window at standard API pricing (no long-context premium). See `shared/model-migration.md` → Migrating to Opus 4.8 — a 4.7 → 4.8 move is a model-ID swap plus prompt re-tuning, no new breaking changes.
+- **Claude Opus 5** — For complex agentic coding and enterprise work; a step-change over Claude Opus 4.8, strongest on deep reasoning, agentic and long-horizon work, and test-time compute scaling, at half the cost of Claude Fable 5 (Claude Fable 5 remains the highest-capability tier). Safety classifiers can return `stop_reason: "refusal"` — handle it before reading `content`. A drop-in upgrade at Opus 4.8's pricing ($5/$25 per MTok) with the same feature set. Thinking is on by default (omitting `thinking` runs adaptive; `{type: "adaptive"}` is equivalent), and `thinking: {type: "disabled"}` is available only at effort `high` or lower — pairing it with `xhigh`/`max` returns a 400. Raw thinking tokens are never returned. Full effort ladder through `max`; 512-token prompt-cache minimum (down from 1024 on Opus 4.8); fast mode on the Claude API only. Elevated cybersecurity safeguards. Separate rate-limit bucket from the combined Opus 4.x pool. 1M context window (default and maximum), 128K max output. See `shared/model-migration.md` → Migrating to Claude Opus 5.
+- **Claude Opus 4.8** — The most capable model in the Opus 4 series — highly autonomous, state-of-the-art on long-horizon agentic work, knowledge work, and memory; clearer, warmer writing. Same API surface as Opus 4.7 (adaptive thinking only; sampling parameters and `budget_tokens` removed). 1M context window at standard API pricing (no long-context premium). See `shared/model-migration.md` → Migrating to Opus 4.8 — a 4.7 → 4.8 move is a model-ID swap plus prompt re-tuning, no new breaking changes.
 - **Claude Opus 4.7** — Previous-generation Opus. Highly autonomous; strong on long-horizon agentic work, knowledge work, vision, and memory. Adaptive thinking only; sampling parameters and `budget_tokens` removed. 1M context window. See `shared/model-migration.md` → Migrating to Opus 4.7.
 - **Claude Opus 4.6** — Older Opus. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window.
-- **Claude Sonnet 4.6** — Our best combination of speed and intelligence. Supports adaptive thinking (recommended). 1M context window. 64K max output tokens.
+- **Claude Sonnet 5** — The best combination of speed and intelligence in the Sonnet tier; near-Opus quality on coding and agentic work. Adaptive thinking on by default (omitting `thinking` runs adaptive); manual `budget_tokens` removed; non-default sampling parameters rejected. `effort` supports `low`/`medium`/`high`/`xhigh`/`max`. New tokenizer (~30% more tokens for the same text vs Sonnet 4.6). High-resolution vision (2576px). 1M context window, 128K max output. See `shared/model-migration.md` → Migrating to Claude Sonnet 5.
+- **Claude Sonnet 4.6** — Previous-generation Sonnet. Supports adaptive thinking (recommended). 1M context window. 128K max output tokens.
 - **Claude Haiku 4.5** — Fastest and most cost-effective model for simple tasks.
 
 ## Legacy Models (still active)
@@ -79,7 +83,7 @@ curl https://api.anthropic.com/v1/models/claude-opus-4-8 \
 | Friendly Name     | Alias (use this)    | Full ID                       | Status |
 |-------------------|---------------------|-------------------------------|--------|
 | Claude Opus 4.5   | `claude-opus-4-5`   | `claude-opus-4-5-20251101`    | Active |
-| Claude Opus 4.1   | `claude-opus-4-1`   | `claude-opus-4-1-20250805`    | Deprecated (retires 2026-08-05 — migrate to `claude-opus-4-8`) |
+| Claude Opus 4.1   | `claude-opus-4-1`   | `claude-opus-4-1-20250805`    | Deprecated (retires 2026-08-05 — migrate to `claude-opus-5`) |
 | Claude Sonnet 4.5 | `claude-sonnet-4-5` | `claude-sonnet-4-5-20250929`  | Active |
 
 ## Deprecated Models (retiring soon)
@@ -113,19 +117,21 @@ When a user asks for a model by name, use this table to find the correct model I
 | "most powerful"                           | `claude-fable-5`                 |
 | "mythos", "mythos 5"                      | `claude-mythos-5` (Project Glasswing participants only; otherwise use `claude-fable-5`) |
 | "mythos preview"                          | `claude-mythos-5` (successor to `claude-mythos-preview` — see migration guide) |
-| "opus"                                    | `claude-opus-4-8`              |
+| "opus"                                    | `claude-opus-5`                   |
+| "opus 5"                                  | `claude-opus-5`             |
 | "opus 4.8"                                | `claude-opus-4-8`              |
 | "opus 4.7"                                | `claude-opus-4-7`              |
 | "opus 4.6"                                | `claude-opus-4-6`              |
 | "opus 4.5"                                | `claude-opus-4-5`              |
-| "opus 4.1"                                | `claude-opus-4-1` (deprecated, retires 2026-08-05 — suggest `claude-opus-4-8`) |
-| "opus 4", "opus 4.0"                      | `claude-opus-4-0` (deprecated — suggest `claude-opus-4-8`) |
-| "sonnet", "balanced"                      | `claude-sonnet-4-6`            |
+| "opus 4.1"                                | `claude-opus-4-1` (deprecated, retires 2026-08-05 — suggest `claude-opus-5`) |
+| "opus 4", "opus 4.0"                      | `claude-opus-4-0` (deprecated — suggest `claude-opus-5`) |
+| "sonnet", "balanced"                      | `claude-sonnet-5`           |
+| "sonnet 5"                                | `claude-sonnet-5`           |
 | "sonnet 4.6"                              | `claude-sonnet-4-6`            |
 | "sonnet 4.5"                              | `claude-sonnet-4-5`            |
-| "sonnet 4", "sonnet 4.0"                  | `claude-sonnet-4-0` (deprecated — suggest `claude-sonnet-4-6`) |
-| "sonnet 3.7"                              | Retired — suggest `claude-sonnet-4-6` |
-| "sonnet 3.5"                              | Retired — suggest `claude-sonnet-4-6` |
+| "sonnet 4", "sonnet 4.0"                  | `claude-sonnet-4-0` (deprecated — suggest `claude-sonnet-5`) |
+| "sonnet 3.7"                              | Retired — suggest `claude-sonnet-5` |
+| "sonnet 3.5"                              | Retired — suggest `claude-sonnet-5` |
 | "haiku", "fast", "cheap"                  | `claude-haiku-4-5`             |
 | "haiku 4.5"                               | `claude-haiku-4-5`             |
 | "haiku 3.5"                               | Retired — suggest `claude-haiku-4-5` |

skills/claude-api/shared/platform-availability.md

@@ -0,0 +1,97 @@
+# Platform Availability
+
+Which features work on which provider platform. **This table is the single source of truth in this skill** — per-feature sections elsewhere point here instead of restating availability. When writing code for a third-party platform (Bedrock, Vertex, Foundry) or Claude Platform on AWS, check this table first; a feature not supported there means use the first-party Claude API surface or a different approach.
+
+Columns: **1P** = first-party Claude API, **P-AWS** = Claude Platform on AWS (Anthropic-operated, same-day parity), **Bedrock** = Amazon Bedrock, **Vertex** = Google Cloud Vertex AI, **Foundry** = Microsoft Foundry. ✅ = GA, β = beta, ❌ = not supported.
+
+| Feature | 1P | P-AWS | Bedrock | Vertex | Foundry | Notes |
+|---|---|---|---|---|---|---|
+| Messages, streaming, tool use | ✅ | ✅ | ✅ | ✅ | ✅ | Core API |
+| PDF input | ✅ | ✅ | ✅ | ✅ | β | |
+| Structured outputs / strict tool use | ✅ | ✅ | ✅ | ✅ | β | |
+| Adaptive thinking / effort | ✅ | ✅ | ✅ | ✅ | β | |
+| Extended thinking | ✅ | ✅ | ✅ | ✅ | β | |
+| Prompt caching (5m, 1h) | ✅ | ✅ | ✅ | ✅ | β | |
+| Automatic prompt caching | ✅ | ✅ | ❌ | ❌ | β | |
+| Token counting | ✅ | ✅ | ✅ | ✅ | β | |
+| Citations | ✅ | ✅ | ✅ | ✅ | β | |
+| Search results content blocks | ✅ | ✅ | ✅ | ✅ | β | |
+| Fine-grained tool streaming | ✅ | ✅ | ✅ | ✅ | ✅ | |
+| Compaction | β | β | β | β | β | |
+| Context editing | β | β | β | β | β | |
+| Context windows (1M) | ✅ | ✅ | ✅ | ✅ | β | |
+| `inference_geo` (data residency) | ✅ | ✅ | ❌ | ❌ | ❌ | |
+| **Server-side tools** | | | | | | |
+|   Web search | ✅ | ✅ | ❌ | ✅ | β | Vertex: basic `web_search_20250305` only (no `_20260209` dynamic filtering) |
+|   Web fetch | ✅ | ✅ | ❌ | ❌ | β | |
+|   Code execution | ✅ | ✅ | ❌ | ❌ | β | |
+|   Tool search | ✅ | ✅ | ✅ | ✅ | β | Bedrock: InvokeModel API only, not Converse |
+|   Advisor tool | β | β | ❌ | ❌ | ❌ | |
+| **Client-implemented tools** | | | | | | |
+|   Bash, text editor, memory | ✅ | ✅ | ✅ | ✅ | β | |
+|   Computer use | β | β | β | β | β | |
+| **Agentic / orchestration** | | | | | | |
+|   Agent Skills (Messages API) | β | β | ❌ | ❌ | β | |
+|   Programmatic tool calling | ✅ | ✅ | ❌ | ❌ | β | |
+|   MCP connector | β | β | ❌ | ❌ | β | |
+|   Managed Agents | β | β | ❌ | ❌ | ❌ | Foundry ❌ inferred (not in Foundry docs either way) |
+|   Self-hosted sandboxes | β | β | ❌ | ❌ | ❌ | P-AWS: `GET /v1/environments/{id}/work` list endpoint not supported; other work endpoints OK |
+| **API endpoints** | | | | | | |
+|   Message Batches | ✅ | ✅ | ❌ | ❌ | ❌ | |
+|   Files API | β | β | ❌ | ❌ | β | |
+|   Models API | ✅ | ✅ | ❌ | ❌ | ❌ | |
+| **Other** | | | | | | |
+|   Mid-conversation system messages | ✅ | ✅ | ❌ | ❌ | ❌ | Claude Opus 5, Claude Opus 4.8, Claude Fable 5, Claude Mythos 5; not Claude Sonnet 5 |
+|   Server-side `fallbacks` | β | β | ❌ | ❌ | ❌ | `"default"` → beta `server-side-fallback-2026-07-01`; array form → beta `server-side-fallback-2026-06-01` |
+|   Fast mode | β | ❌ | ❌ | ❌ | ❌ | Research preview, beta `fast-mode-2026-02-01`, first-party API only |
+|   Cache diagnostics | β | ❌ | ❌ | ❌ | ❌ | First-party API only |
+|   Task budgets | β | β | ❌ | ❌ | ❌ | Beta header `task-budgets-2026-03-13`; 3P availability not documented — assume unsupported |
+
+<!--
+GROUNDING (reviewer-only; stripped at runtime by processSkillMarkdown).
+All paths are under docker_eval/resources/cdp-skill/public-docs/.
+
+Primary source: build-with-claude/overview.mdx <PlatformAvailability> props
+(claudeApi→1P, claudePlatformAws→P-AWS, bedrock→Bedrock, vertexAi→Vertex,
+azureAi→Foundry; *Beta suffix→β; prop absent→❌). Per-row citations:
+
+  Context windows          ov:44
+  Adaptive thinking        ov:45
+  Batch / Message Batches  ov:46; bed:360; vtx:381; fdy:507
+  Citations                ov:47
+  inference_geo            ov:48
+  Effort                   ov:49
+  Extended thinking        ov:50
+  PDF input                ov:51
+  Search results           ov:52
+  Structured outputs       ov:53
+  Advisor tool             ov:63
+  Code execution           ov:64
+  Web fetch                ov:65
+  Web search               ov:66; agents-and-tools/tool-use/web-search-tool.mdx:41
+  Bash/text-editor/memory  ov:72,75,74
+  Computer use             ov:73
+  Agent Skills             ov:83
+  Fine-grained streaming   ov:84
+  MCP connector            ov:85; agents-and-tools/mcp-connector.mdx:36
+  Programmatic tool call   ov:86
+  Tool search              ov:87; agents-and-tools/tool-use/tool-search-tool.mdx:24-30
+  Compaction               ov:95
+  Context editing          ov:96
+  Automatic caching        ov:97
+  Prompt caching 5m/1h     ov:98,99
+  Token counting           ov:100
+  Files API                ov:108; build-with-claude/files.mdx:17
+  Managed Agents           managed-agents/overview.mdx:11,70-72; bed:360; vtx:381
+  Self-hosted sandboxes    build-with-claude/claude-platform-on-aws.mdx:525,547
+  Mid-convo system msgs    build-with-claude/mid-conversation-system-messages.mdx:15
+  Fast mode                build-with-claude/fast-mode.mdx:23
+  Cache diagnostics        build-with-claude/cache-diagnostics.mdx:15,1379
+  Task budgets             build-with-claude/task-budgets.mdx:15
+  Models API               bed:360; vtx:381; fdy:506
+
+  ov  = build-with-claude/overview.mdx
+  bed = build-with-claude/claude-in-amazon-bedrock.mdx
+  vtx = build-with-claude/claude-on-vertex-ai.mdx
+  fdy = build-with-claude/claude-in-microsoft-foundry.mdx
+-->

skills/claude-api/shared/prompt-caching.md

@@ -64,7 +64,7 @@ Many requests share a large fixed preamble (few-shot examples, retrieved docs, i
 
 ### Mid-conversation system messages
 
-**Beta, model-gated.** When an operator instruction arrives mid-conversation — a mode switch, updated context, dynamically injected state — send it as `{"role": "system", "content": "..."}` appended to `messages[]`, rather than editing top-level `system`. Editing top-level `system` changes the prefix ahead of the entire conversation history, so every cached turn is re-processed uncached; a `role: "system"` message sits after the history and leaves the cached prefix intact.
+**Claude Opus 5, Claude Opus 4.8, Claude Fable 5, and Claude Mythos 5; no beta header. Not available on Claude Sonnet 5** — use top-level `system` there. (Sources conflict on Claude Sonnet 5: the model config marks it supported, but every canonical docs page omits it. Treat it as unsupported and catch the 400.) When an operator instruction arrives mid-conversation — a mode switch, updated context, dynamically injected state — send it as `{"role": "system", "content": "..."}` appended to `messages[]`, rather than editing top-level `system`. Editing top-level `system` changes the prefix ahead of the entire conversation history, so every cached turn is re-processed uncached; a `role: "system"` message sits after the history and leaves the cached prefix intact.
 
 ```json
 // Top-level system stays byte-identical; new instruction goes after the cached history
@@ -78,7 +78,7 @@ Many requests share a large fixed preamble (few-shot examples, retrieved docs, i
 
 This is also the prompt-injection-safe replacement for embedding operator instructions as text inside a user turn (the `<system-reminder>` pattern): both have the same caching profile, but `role: "system"` is the non-spoofable operator channel, whereas text inside user/tool content can be forged by anything that writes to user-visible input.
 
-Requires `anthropic-beta: mid-conversation-system-2026-04-07`. Must follow a `role: "user"` message (or an assistant message ending in a server tool result); cannot be `messages[0]` — use top-level `system` for the initial prompt. Content is text-only. Model-gated — unsupported models return a 400 (`BadRequestError`: `role 'system' is not supported on this model`); catch that error and fall back to putting the instruction in a user-turn `<system-reminder>` block.
+Must follow a `role: "user"` message (or an `assistant` message ending in server-tool use), and must be either the last entry in `messages` or be followed by an `assistant` turn; cannot be `messages[0]` — use top-level `system` for the initial prompt. Content is text-only. Unsupported models return a 400 (`BadRequestError`: `role 'system' is not supported on this model`); catch that error and fall back to putting the instruction in a user-turn `<system-reminder>` block.
 
 ### Prompts that change from the beginning every time
 
@@ -129,11 +129,14 @@ Fix by moving the dynamic piece after the last breakpoint, making it determinist
 
 | Model | Minimum |
 |---|---:|
-| Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5, Haiku 4.5 | 4096 tokens |
-| Fable 5, Sonnet 4.6, Haiku 3.5, Haiku 3 | 2048 tokens |
-| Sonnet 4.5, Sonnet 4.1, Sonnet 4, Sonnet 3.7 | 1024 tokens |
+| Claude Opus 5, Claude Fable 5, Claude Mythos 5 | 512 tokens |
+| Opus 4.8, Claude Sonnet 5, Sonnet 4.6, Sonnet 4.5, Opus 4.1, Opus 4, Sonnet 4 | 1024 tokens |
+| Opus 4.7, Mythos Preview, Haiku 3.5 | 2048 tokens |
+| Opus 4.6, Opus 4.5, Haiku 4.5 | 4096 tokens |
 
-A 3K-token prompt caches on Sonnet 4.5 and Fable 5 but silently won't on Opus 4.8.
+**The minimum is not monotonic across generations** — 512 on the newest models, but 4096 on Opus 4.6/4.5 and Haiku 4.5. A 3K-token prompt caches on Claude Opus 5, Opus 4.8, and Sonnet 4.5, and silently won't on Opus 4.6 or Haiku 4.5. Claude Opus 5 halves the Opus 4.8 minimum (1024 → 512), so prompts previously too short to cache now create entries with no code change.
+
+These minimums apply on **every** platform where the model is available — the old Amazon Bedrock override for Claude Fable 5 was removed, and no per-platform exception remains.
 
 **Economics:** Cache reads cost ~0.1× base input price. Cache writes cost **1.25× for 5-minute TTL, 2× for 1-hour TTL**. Break-even depends on TTL: with 5-minute TTL, two requests break even (1.25× + 0.1× = 1.35× vs 2× uncached); with 1-hour TTL, you need at least three requests (2× + 0.2× = 2.2× vs 3× uncached). The 1-hour TTL keeps entries alive across gaps in bursty traffic, but the doubled write cost means it needs more reads to pay off.
 
@@ -172,6 +175,15 @@ Not every parameter change invalidates everything. The API has three cache tiers
 
 Implication: you can change `tool_choice` per-request or toggle `thinking` without losing the tools+system cache. Don't over-worry about these — only tool-definition and model changes force a full rebuild.
 
+**Two of these rows have a cache-preserving escape hatch**, each by moving the change out of the top-level request and into a system message inside `messages[]`, after the cached prefix. **Availability differs per row** — the two are not gated together:
+
+| Top-level change that invalidates | Cache-preserving form | Available on |
+|---|---|---|
+| Tool definitions (add/remove) | `tool_addition` / `tool_removal` blocks — see `shared/tool-use-concepts.md` § Mid-conversation tool changes | Claude Opus 5 onward, behind `mid-conversation-tool-changes-2026-07-01` |
+| System prompt content | A `{"role": "system", "content": "…"}` message — see § Mid-conversation system messages above | Claude Opus 5, Claude Opus 4.8, Claude Fable 5, Claude Mythos 5 — **already available today**, no beta header |
+
+Model switch has no escape hatch: caches are model-scoped. Keep the main loop on one model and spawn a subagent for cheaper sub-tasks (see `agent-design.md` § Caching for Agents).
+
 ---
 
 ## 20-block lookback window
@@ -205,7 +217,7 @@ To eliminate the cache-miss latency on the *first* real request, send a **`max_t
 
 ```python
 client.messages.create(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     max_tokens=0,
     system=[{
         "type": "text",

skills/claude-api/shared/token-counting.md

@@ -16,7 +16,7 @@ from anthropic import Anthropic
 
 client = Anthropic()
 resp = client.messages.count_tokens(
-    model="claude-opus-4-8",
+    model="claude-opus-5",
     messages=[{"role": "user", "content": open("CLAUDE.md").read()}],
 )
 print(resp.input_tokens)
@@ -28,7 +28,7 @@ TypeScript: `await client.messages.countTokens({model, messages})` →
 ## CLI
 
 ```sh
-ant messages count-tokens --model claude-opus-4-8 \
+ant messages count-tokens --model claude-opus-5 \
   --message '{role: user, content: "@./CLAUDE.md"}' \
   --transform input_tokens -r
 ```
@@ -44,7 +44,7 @@ import subprocess
 client = Anthropic()
 def count(text: str) -> int:
     return client.messages.count_tokens(
-        model="claude-opus-4-8",
+        model="claude-opus-5",
         messages=[{"role": "user", "content": text}],
     ).input_tokens
 

skills/claude-api/shared/tool-use-concepts.md

@@ -59,9 +59,25 @@ Any `tool_choice` value can also include `"disable_parallel_tool_use": true` to
 
 ### Tool Runner vs Manual Loop
 
-**Tool Runner (Recommended):** The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, Ruby, and PHP SDKs (beta). The Python SDK also provides MCP conversion helpers (`anthropic.lib.tools.mcp`) to convert MCP tools, prompts, and resources for use with the tool runner — see `python/claude-api/tool-use.md` for details.
+**Tool Runner (Recommended):** The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, Ruby, PHP, and C# SDKs (beta). The Python SDK also provides MCP conversion helpers (`anthropic.lib.tools.mcp`) to convert MCP tools, prompts, and resources for use with the tool runner — see `python/claude-api/tool-use.md` for details. **Default to the tool runner** for any custom-tool agent.
 
-**Manual Agentic Loop:** Use when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval). Loop until `stop_reason == "end_turn"`, always append the full `response.content` to preserve tool_use blocks, and ensure each `tool_result` includes the matching `tool_use_id`.
+**The tool runner is not a black box — "I need control" is rarely a reason to drop to the manual loop.** Each iteration yields the assistant message *before* the tools run and lets you intervene, so most "fine-grained control" needs are covered without hand-writing the loop:
+
+- **Human-in-the-loop approval / gating** — gate in the tool's run function (return a "user declined" result instead of executing), or inspect the tool call in the yielded message and override the pending request with `set_messages_params()` / `setMessagesParams()` / `append_messages()` / `pushMessages()` to allow or deny *before* the tool executes. The runner runs your function automatically only if you don't intervene.
+- **Error interception** — inspect the tool result before it returns to Claude (`generate_tool_call_response()` / `generateToolResponse()`); stop early or handle it yourself.
+- **Result modification** — mutate the tool result before it goes back (e.g. add `cache_control` for prompt caching, or transform the output).
+- **Per-turn retries / param changes** — e.g. bump `max_tokens` and re-run a truncated turn; bound the whole loop with `max_iterations`.
+- **Streaming and automatic compaction** are both supported.
+
+These hooks are SDK helper features, not separate API parameters — for the exact method names and worked examples, WebFetch the per-language SDK repo listed in `shared/live-sources.md` → *Claude API SDK Repositories* (the tool-runner helpers live in each repo's `tools.md` / `helpers.md`). The bundled `python/claude-api/tool-use.md` and `typescript/claude-api/tool-use.md` show the basic tool-runner setup.
+
+**Don't drop to a manual loop because of these misconceptions:**
+
+- The tool runner does not require Zod/Pydantic — `betaTool()` (TS) and `@beta_tool` (Python) accept raw JSON Schema; other SDKs use plain structs/maps/classes.
+- The runner makes detecting the final turn *easier*, not harder — iteration ends when Claude stops calling tools, and the last yielded message is the final response. Most SDKs also offer a one-shot variant (`runner.until_done()` / `runner.runUntilDone()` / `RunToCompletion()`).
+- Confirmation/approval gates work with the runner (see Security below).
+
+**Manual Agentic Loop:** Reach for this only when you want to own the *entire* loop — you need control the runner does not expose (e.g., a custom transport, request shapes the SDK cannot build, per-token streaming on SDKs whose runner does not support it), you'd rather not take the beta dependency, or your control flow doesn't fit the runner's per-turn hooks (e.g. interleaving unrelated work mid-loop). Approval gates, logging, interception, result modification, and conditional execution do **not** require it — the tool runner covers those (above). Loop until `stop_reason == "end_turn"`, always append the full `response.content` to preserve tool_use blocks, and ensure each `tool_result` includes the matching `tool_use_id`.
 
 **Stop reasons for server-side tools:** When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have `stop_reason: "pause_turn"`. To continue, re-send the user message and assistant response and make another API request — the server will resume where it left off. Do NOT add an extra user message like "Continue." — the API detects the trailing `server_tool_use` block and knows to resume automatically.
 
@@ -74,13 +90,15 @@ if response.stop_reason == "pause_turn":
     ]
     # Make another API request — server resumes automatically
     response = client.messages.create(
-        model="claude-opus-4-8", messages=messages, tools=tools
+        model="claude-opus-5", messages=messages, tools=tools
     )
 ```
 
+**Note:** the SDK tool runners do not auto-resume `pause_turn` (as of `@anthropic-ai/sdk` 0.110.0 / `anthropic` 0.116.0) — a paused turn ends the runner and is returned as the final message, with no error. In TypeScript you can resume inside the iteration body (push the paused assistant turn back onto the runner); in Python the runner cannot be resumed mid-loop — restart a new runner with the paused turn appended, or handle `pause_turn` in a manual loop. See each language's `tool-use.md` for the pattern.
+
 Set a `max_continuations` limit (e.g., 5) to prevent infinite loops. For the full guide, see: `https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons`
 
-> **Security:** The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs within your tool functions and consider requiring confirmation for destructive operations. Use the manual agentic loop if you need human-in-the-loop approval before each tool execution.
+> **Security:** The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs and gate destructive operations behind human approval. **Both** the tool runner and the manual loop support this — with the tool runner, gate inside the tool's run function (prompt the user and return a "user declined" result instead of executing), or inspect the tool call in each yielded message and take over message history with `set_messages_params()` / `setMessagesParams()` to allow or deny *before* the tool runs (it executes your function automatically only if you don't intervene); with the manual loop you gate inline before calling the function.
 
 ---
 
@@ -171,7 +189,7 @@ Web search and web fetch let Claude search the web and retrieve page content. Th
 ]
 ```
 
-### Dynamic Filtering (Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 4.6)
+### Dynamic Filtering (Claude Opus 5 / Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 5 / Sonnet 4.6)
 
 The `web_search_20260209` and `web_fetch_20260209` versions support **dynamic filtering** — Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the `code_execution` tool or pass any beta header.
 
@@ -212,13 +230,96 @@ For full documentation, use WebFetch:
 
 ---
 
-## Skills
+## Mid-conversation tool changes (Beta)
 
-Skills package task-specific instructions that Claude loads only when relevant. Each skill is a folder containing a `SKILL.md` file. The skill's short description sits in context by default; Claude reads the full file when the current task calls for it. Use skills to keep specialized instructions out of the base system prompt without losing discoverability.
+**Beta header `mid-conversation-tool-changes-2026-07-01`; Claude Opus 5 onward.** Normally `tools` is fixed for a conversation's lifetime — editing it changes the very front of the prompt prefix and invalidates the entire cache (see `prompt-caching.md` § Invalidation hierarchy). This feature lets you add and remove tools between turns while the cached prefix survives.
 
-For full documentation, use WebFetch:
+Both operations are content blocks on a `{"role": "system", ...}` message appended to `messages[]`, and both reference a tool by name via a `tool_reference`:
 
-- URL: `https://platform.claude.com/docs/en/agents-and-tools/skills`
+```python
+# Removal — must sit immediately before an assistant message, or last in messages.
+{"role": "system", "content": [
+    {"type": "tool_removal", "tool": {"type": "tool_reference", "name": "get_weather"}},
+]}
+
+# Addition — surfaces a tool declared up front with defer_loading.
+{"role": "system", "content": [
+    {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "get_forecast"}},
+]}
+```
+
+**A tool you plan to add must already be declared in `tools[]` with `"defer_loading": True`.** Deferred tools are known to the request but not loaded into the model's context until a `tool_addition` surfaces them:
+
+```python
+tools = [
+    {"name": "get_weather", "description": "Get weather",
+     "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}}},
+    {"name": "get_forecast", "description": "Get 5-day forecast",
+     "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}},
+     "defer_loading": True},
+]
+```
+
+**To change a tool's definition**, do it across two requests: send a `tool_removal` for the old definition on the first, then carry the conversation forward with the updated entry in `tools[]` on the next.
+
+> ⚠️ Earlier previews used a different beta header and different block shapes; both are deprecated. Use `mid-conversation-tool-changes-2026-07-01` with `tool_addition` / `tool_removal` / `tool_reference`.
+
+SDK typings lag these blocks — pass them as plain dicts in Python, or add a `@ts-expect-error` in TypeScript.
+
+**Choosing between this and tool search:** tool search is for *discovery* — Claude finds what it needs from a large library on its own. Mid-conversation tool changes are for *control* — your application decides the tool set has changed (a mode switch, a resource that became available, a capability you want to revoke) and says so explicitly.
+
+---
+
+## Agent Skills (Messages API)
+
+Agent Skills package task-specific instructions and files that Claude loads when relevant (e.g., the Anthropic pre-built `pptx`, `xlsx`, `pdf`, `docx` skills). On the **Messages API**, skills are enabled via the `container` parameter alongside the code-execution tool — this is **not** the Managed Agents surface and does **not** use `client.beta.agents` / `sessions` / `environments`. Availability: see `shared/platform-availability.md`.
+
+Required on each request:
+
+1. `client.beta.messages.create(...)` with **both** beta flags: `code-execution-2025-08-25` **and** `skills-2025-10-02`.
+2. `container={"skills": [{"type": "anthropic", "skill_id": "<id>", "version": "latest"}]}` — the skills list selects which skills are available inside the execution container.
+3. `tools=[{"type": "code_execution_20260521", "name": "code_execution"}]` — skills execute via code execution in the container.
+
+```python
+response = client.beta.messages.create(
+    model="claude-opus-5", max_tokens=16000,
+    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
+    container={"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]},
+    tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
+    messages=[{"role": "user", "content": "Create a 3-slide presentation on X"}],
+)
+```
+
+Generated files (`.pptx`, `.xlsx`, …) are written inside the container; the response carries a file ID for each. Download by passing that ID to the Files API (`client.beta.files.download(file_id)` / `GET /v1/files/{id}/content` with `anthropic-beta: files-api-2025-04-14`).
+
+List available skills via `GET /v1/skills` (requires `anthropic-beta: skills-2025-10-02`).
+
+---
+
+## MCP Connector (Beta)
+
+The MCP connector lets Claude call tools hosted on a remote MCP server directly from the Messages API — Anthropic makes the MCP connection server-side. Requires beta flag `mcp-client-2025-11-20` on `client.beta.messages.create(...)`. Availability: see `shared/platform-availability.md`.
+
+**Two parameters are required together:**
+
+- `mcp_servers` — array of server connection definitions: `[{"type": "url", "url": "<server URL>", "name": "<server-name>", "authorization_token": "<optional>"}]`
+- `tools` — must include an `mcp_toolset` entry that references the server by name: `[{"type": "mcp_toolset", "mcp_server_name": "<server-name>"}]`
+
+The `mcp_server_name` in the toolset must match a `name` in `mcp_servers`. Omitting the `mcp_toolset` entry is rejected as a validation error — every server in `mcp_servers` must be referenced by exactly one toolset.
+
+```python
+client.beta.messages.create(
+    model="claude-opus-5", max_tokens=1024,
+    betas=["mcp-client-2025-11-20"],
+    mcp_servers=[{"type": "url", "url": "https://example/sse", "name": "example-mcp"}],
+    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
+    messages=[...],
+)
+```
+
+Go uses the typed constant `anthropic.AnthropicBetaMCPClient2025_11_20`; the older `…2025_04_04` constant is deprecated.
+
+Optional toolset fields: `default_config` (defaults for all tools, e.g. `{"enabled": false}` for allowlist mode) and `configs` (per-tool overrides keyed by tool name).
 
 ---
 
@@ -232,9 +333,9 @@ For full documentation, use WebFetch:
 
 ---
 
-## Server-Side Tools: Computer Use
+## Client-Side Tools: Computer Use
 
-Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It can be Anthropic-hosted (server-side, like code execution) or self-hosted (you provide the environment and execute actions client-side).
+Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It is a client-side tool — your application provides the environment and executes the actions Claude requests; Anthropic processes the screenshots and action requests in real time but does not host the environment or retain the data.
 
 For full documentation, use WebFetch:
 
@@ -244,7 +345,9 @@ For full documentation, use WebFetch:
 
 ## Context Editing
 
-Context editing clears stale tool results and thinking blocks from the transcript as a long-running agent accumulates turns. Unlike compaction (which summarizes), context editing prunes — the cleared content is removed, not replaced. Use it when old tool outputs are no longer relevant and you want to keep the transcript lean without losing the conversation structure. Thresholds for what to clear are configurable.
+Context editing clears stale tool results and thinking blocks from the transcript as a long-running agent accumulates turns. Unlike compaction (which summarizes), context editing prunes — the cleared content is removed, not replaced. Use it when old tool outputs are no longer relevant and you want to keep the transcript lean without losing the conversation structure.
+
+**Beta.** Use `client.beta.messages.*` with beta `context-management-2025-06-27`. Configure via `context_management.edits` with a strategy type of `clear_tool_uses_20250919` (clear old tool results; optional `clear_tool_inputs: true` also clears the tool_use params) or `clear_thinking_20251015` (clear thinking blocks). These are **not** the compaction types — `compact_20260112` with beta `compact-2026-01-12` is the separate compaction feature.
 
 For full documentation, use WebFetch:
 
@@ -254,7 +357,7 @@ For full documentation, use WebFetch:
 
 ## Server-Side Tools: Advisor (Beta)
 
-The advisor tool lets Claude consult a secondary model during a conversation. The advisor runs its own API call with a model you specify and returns its analysis to the primary model. Use it when you want a second opinion, specialized expertise, or cross-model verification without managing the orchestration yourself.
+The advisor tool pairs a faster, lower-cost **executor** model (the top-level `model` on the request) with a higher-intelligence **advisor** model (the `model` field inside the tool definition) that provides strategic guidance mid-generation. The executor does most of the token generation; the advisor is consulted for planning. Availability: see `shared/platform-availability.md`.
 
 ### Tool Definition
 
@@ -262,13 +365,30 @@ The advisor tool lets Claude consult a secondary model during a conversation. Th
 {
   "type": "advisor_20260301",
   "name": "advisor",
-  "model": "claude-sonnet-4-6"
+  "model": "claude-opus-4-8"
 }
 ```
 
-The `model` parameter is required — it specifies which model the advisor uses for its own inference. Optional fields: `caching`, `max_uses`, `allowed_callers`, `defer_loading`, `strict`.
+**The advisor model must be at least as capable as the executor.** An invalid pairing returns `400 invalid_request_error`. Valid pairs:
 
-**Beta header required:** `advisor-tool-2026-03-01`. The SDK sets this automatically when using `client.beta.messages.create()` with advisor tools.
+| Executor (request `model`) | Valid advisor (tool `model`) |
+|---|---|
+| `claude-haiku-4-5` / `claude-sonnet-4-6` / `claude-sonnet-5` / `claude-opus-4-6` / `claude-opus-4-7` | `claude-opus-5`, `claude-fable-5`, `claude-mythos-5`, `claude-opus-4-8`, or `claude-opus-4-7` |
+| `claude-opus-4-8` | `claude-opus-5`, `claude-fable-5`, `claude-mythos-5`, or `claude-opus-4-8` |
+| `claude-opus-5` | `claude-opus-5`, `claude-fable-5`, or `claude-mythos-5` |
+| `claude-fable-5` | `claude-fable-5` or `claude-opus-5` |
+| `claude-mythos-5` | `claude-mythos-5` or `claude-opus-5` |
+
+> ⚠️ **The advisor's payload shape differs by advisor model.** The response block is always `advisor_tool_result`; what varies is its **`content`**, a discriminated union:
+>
+> | `content` type | Fields | When |
+> |---|---|---|
+> | `advisor_result` | `text`, `stop_reason` | Advisor returns plaintext (e.g. Opus 4.8) |
+> | `advisor_redacted_result` | `encrypted_content`, `stop_reason` | Advisor returns encrypted output — Claude Opus 5, Claude Fable 5, Claude Mythos 5 |
+>
+> So switch on `advisor_tool_result.content` type, not on the block type. Code that reads `.text` unconditionally gets nothing back from an Claude Opus 5 advisor, because the payload is under `encrypted_content` instead — and you cannot read it, only replay it.
+
+Call via `client.beta.messages.create(...)` with `betas=["advisor-tool-2026-03-01"]` (or the `anthropic-beta: advisor-tool-2026-03-01` header). In multi-turn conversations, append the full `response.content` — including any `advisor_tool_result` blocks — back to `messages` on the next turn. If you remove the advisor tool from `tools` on a later turn while the history still contains `advisor_tool_result` blocks, the API returns a 400.
 
 ---
 
@@ -291,6 +411,53 @@ For full implementation examples, use WebFetch:
 
 ---
 
+## Client-Side Tools: Bash and Text Editor
+
+The bash and text editor tools are **Anthropic-defined, schema-less** tools. Declare them by `type` and `name` only — the input schema is built into the model and cannot be modified. **Do not pass an `input_schema`**, and do not define a custom tool that happens to be named `"bash"` — that creates a user-defined tool without the built-in behavior.
+
+Both are **client-executed**: Claude returns a `tool_use` block, your code performs the action locally, and you send back a `tool_result`. The API is stateless; your application maintains the shell session or filesystem between turns.
+
+### Bash tool declaration
+
+```json
+{"type": "bash_20250124", "name": "bash"}
+```
+
+| Language | Declaration |
+|---|---|
+| Python / TypeScript / Ruby / cURL | plain object `{"type": "bash_20250124", "name": "bash"}` |
+| Go | `anthropic.ToolUnionParam{OfBashTool20250124: &anthropic.ToolBash20250124Param{}}` |
+| Java | `.addTool(ToolBash20250124.builder().build())` from `com.anthropic.models.messages` |
+| C# | `Tools = [new ToolBash20250124()]` from `Anthropic.Models.Messages` |
+| PHP | `tools: [new \Anthropic\Messages\ToolBash20250124()]` |
+
+Claude's `tool_use.input` contains either `{"command": "<string>"}` or `{"restart": true}`. Check for `restart` first (reset the session, return a confirmation string); otherwise run `command` and return combined stdout + stderr.
+
+> **Security — commands are untrusted model output.** Run in an isolated environment (container, VM, or restricted user); apply an **allowlist** of permitted executables and reject shell operators (`&&`, `|`, `;`, `` ` ``, `$()`); set timeouts and resource limits; log every command. A blocklist is not sufficient.
+
+### Text editor tool declaration
+
+```json
+{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}
+```
+
+Optional field: `max_characters` to cap `view` output. Java exposes a typed `ToolTextEditor20250728` builder (`com.anthropic.models.messages`); other statically-typed SDKs follow the same naming pattern — see the Anthropic-Defined Tools section in `{lang}/claude-api/tool-use.md` for the exact class.
+
+> **Security — `path` is untrusted model output. Confine every file operation to a fixed project root.** Before executing any command, resolve the model-supplied `path` to its canonical form and verify it remains within your project root; reject the request if it escapes (`..`, symlinks, absolute paths outside the root, URL-encoded traversal like `%2e%2e%2f`). Use your language's built-in path utilities (e.g., Python `pathlib.Path.resolve()` then check `.is_relative_to(root)`). Never call `open()` / `writeFile` / `unlink` directly on the raw `path` value.
+
+`tool_use.input.command` is one of:
+
+| `command` | Other inputs | Action |
+|---|---|---|
+| `view` | `path`, optional `view_range` | Return file contents or directory listing |
+| `create` | `path`, `file_text` | Create/overwrite file with `file_text`. Create a backup if the file already exists. |
+| `str_replace` | `path`, `old_str`, `new_str` | Replace exactly one occurrence; error if 0 or >1 matches |
+| `insert` | `path`, `insert_line`, `insert_text` | Insert `insert_text` after line `insert_line` (0 = beginning of file) |
+
+For both tools, on error return `{"type": "tool_result", "tool_use_id": "…", "content": "<error text>", "is_error": true}` so Claude can recover.
+
+---
+
 ## Structured Outputs
 
 Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool — it enhances the Messages API response format and/or tool parameter validation.
@@ -300,7 +467,7 @@ Two features are available:
 - **JSON outputs** (`output_config.format`): Control Claude's response format
 - **Strict tool use** (`strict: true`): Guarantee valid tool parameter schemas
 
-**Supported models:** Claude Fable 5, Claude Opus 4.8, Claude Sonnet 4.6, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs.
+**Supported models:** Claude Fable 5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs.
 
 > **Recommended:** Use `client.messages.parse()` which automatically validates responses against your schema. When using `messages.create()` directly, use `output_config: {format: {...}}`. The `output_format` convenience parameter is also accepted by some SDK methods (e.g., `.parse()`), but `output_config.format` is the canonical API-level parameter.
 

skills/claude-api/typescript/claude-api/README.md

@@ -1,11 +1,17 @@
 # Claude API — TypeScript
 
+| Feature | Namespace | Key types / call |
+|---|---|---|
+| User profiles | beta | `client.beta.userProfiles.create(...)` / `.retrieve(id)` / `.list()`. Pass the returned profile id on `client.beta.messages.create`. Requires a beta header — check the SDK's beta-headers reference for the current flag. |
+
 ## Installation
 
 ```bash
 npm install @anthropic-ai/sdk
 ```
 
+> **Reading local files (ESM):** `__dirname` and `__filename` are **undefined** in ES modules — using either throws `ReferenceError: __dirname is not defined` at runtime. For cwd-relative reads, pass the bare relative path (`fs.readFileSync("./sample.png")`). For script-relative paths, derive the directory from `import.meta.url`: `const here = path.dirname(fileURLToPath(import.meta.url))`. Never write `path.join(__dirname, …)` in an ESM `.ts` file.
+
 ## Client Initialization
 
 ```typescript
@@ -26,7 +32,7 @@ const client = new Anthropic({ apiKey: "your-api-key" });
 
 ```typescript
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   messages: [{ role: "user", content: "What is the capital of France?" }],
 });
@@ -45,7 +51,7 @@ for (const block of response.content) {
 
 ```typescript
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   system:
     "You are a helpful coding assistant. Always provide examples in Python.",
@@ -53,30 +59,24 @@ const response = await client.messages.create({
 });
 ```
 
-### Mid-conversation system messages (beta, model-gated)
+### Mid-conversation system messages (model-gated)
 
-For operator instructions that arrive mid-conversation (mode switches, injected state), append `{role: "system", ...}` to `messages` instead of editing top-level `system` — this preserves the cached prefix and carries operator authority. Must follow a user message; cannot be `messages[0]`. Unsupported models return a 400 (`role 'system' is not supported on this model`). See `shared/prompt-caching.md` for when to use this vs. top-level `system`.
+For operator instructions that arrive mid-conversation (mode switches, injected state), append `{role: "system", ...}` to `messages` instead of editing top-level `system` — this preserves the cached prefix and carries operator authority. Must follow a user message (or an `assistant` message ending in server-tool use), and must be either the last entry in `messages` or be followed by an `assistant` turn; cannot be `messages[0]`. Unsupported models return a 400 (`role 'system' is not supported on this model`). See `shared/prompt-caching.md` for when to use this vs. top-level `system`.
 
 ```typescript
-// SDK types for role:"system" in messages are pending — pass the beta header
-// directly until the SDK updates, then switch to client.beta.messages.create
-// with betas: ["mid-conversation-system-2026-04-07"].
-const response = await client.messages.create(
-  {
-    model: MODEL_ID, // must support mid-conversation system messages
-    max_tokens: 16000,
-    system: [
-      { type: "text", text: STABLE_SYSTEM, cache_control: { type: "ephemeral" } },
-    ],
-    messages: [
-      ...history,
-      { role: "user", content: userMessage },
-      // @ts-expect-error — role:"system" pending SDK types
-      { role: "system", content: "Terse mode enabled — keep responses under 40 words." },
-    ],
-  },
-  { headers: { "anthropic-beta": "mid-conversation-system-2026-04-07" } },
-);
+// No beta header needed — use regular client.messages.create.
+const response = await client.messages.create({
+  model: MODEL_ID, // must support mid-conversation system messages
+  max_tokens: 16000,
+  system: [
+    { type: "text", text: STABLE_SYSTEM, cache_control: { type: "ephemeral" } },
+  ],
+  messages: [
+    ...history,
+    { role: "user", content: userMessage },
+    { role: "system", content: "Terse mode enabled — keep responses under 40 words." },
+  ],
+});
 ```
 
 ---
@@ -87,7 +87,7 @@ const response = await client.messages.create(
 
 ```typescript
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   messages: [
     {
@@ -112,7 +112,7 @@ import fs from "fs";
 const imageData = fs.readFileSync("image.png").toString("base64");
 
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   messages: [
     {
@@ -141,7 +141,7 @@ Use top-level `cache_control` to automatically cache the last cacheable block in
 
 ```typescript
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   cache_control: { type: "ephemeral" }, // auto-caches the last cacheable block
   system: "You are an expert on this large document...",
@@ -155,7 +155,7 @@ For fine-grained control, add `cache_control` to specific content blocks:
 
 ```typescript
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   system: [
     {
@@ -169,7 +169,7 @@ const response = await client.messages.create({
 
 // With explicit TTL (time-to-live)
 const response2 = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   system: [
     {
@@ -196,16 +196,17 @@ If `cache_read_input_tokens` is zero across repeated identical-prefix requests,
 
 ## Extended Thinking
 
-> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Claude Opus 5:** thinking is on by default — omitting `thinking` runs adaptive (`{ type: "adaptive" }` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `{ type: "disabled" }` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400.
 > **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024).
 
 ```typescript
-// Fable 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
+// Fable 5 / Claude Opus 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
-  thinking: { type: "adaptive" },
-  output_config: { effort: "high" }, // low | medium | high | max
+  thinking: { type: "adaptive", display: "summarized" }, // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7
+  output_config: { effort: "high" }, // low | medium | high | xhigh | max
   messages: [
     { role: "user", content: "Solve this math problem step by step..." },
   ],
@@ -260,7 +261,7 @@ const messages: Anthropic.MessageParam[] = [
 ];
 
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   messages: messages,
 });
@@ -276,7 +277,7 @@ const response = await client.messages.create({
 
 ### Compaction (long conversations)
 
-> **Beta, Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text.
+> **Beta, Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text.
 
 ```typescript
 import Anthropic from "@anthropic-ai/sdk";
@@ -289,7 +290,7 @@ async function chat(userMessage: string): Promise<string> {
 
   const response = await client.beta.messages.create({
     betas: ["compact-2026-01-12"],
-    model: "claude-opus-4-8",
+    model: "claude-opus-5",
     max_tokens: 16000,
     messages,
     context_management: {
@@ -333,11 +334,43 @@ When `stop_reason` is `"refusal"`, the response includes a `stop_details` object
 
 ```typescript
 if (response.stop_reason === "refusal" && response.stop_details) {
-  console.log(`Category: ${response.stop_details.category}`); // "cyber" | "bio" | null
+  console.log(`Category: ${response.stop_details.category}`); // e.g. "cyber", "bio", "reasoning_extraction", "frontier_llm", or null — see docs for the full set
   console.log(`Explanation: ${response.stop_details.explanation}`);
 }
 ```
 
+### Refusal Fallbacks (Claude Fable 5) — opt in by default
+
+Fallbacks are **opt-in**: without them a refused request simply stops. Include the server-side `fallbacks` parameter in `claude-fable-5` code by default — on a policy decline the API re-runs the same request on the fallback model inside the same call. A decline before any output isn't billed (a mid-stream decline bills the streamed partial); the rescue bills at the fallback model's own rates, with cache repricing applied automatically.
+
+```typescript
+const response = await client.beta.messages.create({
+  model: "claude-fable-5",
+  max_tokens: 16000,
+  betas: ["server-side-fallback-2026-06-01"],
+  fallbacks: [{ model: "claude-opus-4-8" }],
+  messages: [{ role: "user", content: "..." }],
+});
+
+// Switch points: one fallback block per model that ran and declined this turn
+for (const block of response.content) {
+  if (block.type === "fallback") {
+    console.log(`${block.from.model} declined; ${block.to.model} continued`);
+  }
+}
+
+// Served-by signal — covers sticky turns, which carry no fallback block.
+// Pair with stop_reason: the fallback model can itself refuse.
+const fallbackRan = (response.usage.iterations ?? []).some(
+  (entry) => entry.type === "fallback_message",
+);
+if (fallbackRan && response.stop_reason !== "refusal") {
+  console.log(`Served by ${response.model}`);
+}
+```
+
+A `stop_reason: "refusal"` on the final response means the whole chain refused. The header must be exactly `server-side-fallback-2026-06-01` **for this array form**; the newer `fallbacks: "default"` scalar form uses `server-side-fallback-2026-07-01` instead (see `shared/model-migration.md` → Migrating to Claude Opus 5 → New API features), and pairing either header with the other form returns a 400. The parameter is rejected on the Batches API and unavailable on Amazon Bedrock, Vertex AI, and Microsoft Foundry — register the client-side `betaRefusalFallbackMiddleware` on the client there instead. Full semantics (sticky routing, billing, streaming, echoing fallback turns back): `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason.
+
 ---
 
 ## Cost Optimization Strategies
@@ -347,7 +380,7 @@ if (response.stop_reason === "refusal" && response.stop_details) {
 ```typescript
 // Automatic caching (simplest — caches the last cacheable block)
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   cache_control: { type: "ephemeral" },
   system: largeDocumentText, // e.g., 50KB of context
@@ -362,7 +395,7 @@ const response = await client.messages.create({
 
 ```typescript
 const countResponse = await client.messages.countTokens({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   messages: messages,
   system: system,
 });

skills/claude-api/typescript/claude-api/batches.md

@@ -24,7 +24,7 @@ const messageBatch = await client.messages.batches.create({
     {
       custom_id: "request-1",
       params: {
-        model: "claude-opus-4-8",
+        model: "claude-opus-5",
         max_tokens: 16000,
         messages: [
           { role: "user", content: "Summarize climate change impacts" },
@@ -34,7 +34,7 @@ const messageBatch = await client.messages.batches.create({
     {
       custom_id: "request-2",
       params: {
-        model: "claude-opus-4-8",
+        model: "claude-opus-5",
         max_tokens: 16000,
         messages: [
           { role: "user", content: "Explain quantum computing basics" },

skills/claude-api/typescript/claude-api/files-api.md

@@ -41,7 +41,7 @@ console.log(`Size: ${uploaded.size_bytes} bytes`);
 
 ```typescript
 const response = await client.beta.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   messages: [
     {

skills/claude-api/typescript/claude-api/streaming.md

@@ -4,7 +4,7 @@
 
 ```typescript
 const stream = client.messages.stream({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 64000,
   messages: [{ role: "user", content: "Write a story" }],
 });
@@ -23,13 +23,13 @@ for await (const event of stream) {
 
 ## Handling Different Content Types
 
-> **Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead.
+> **Fable 5 / Claude Opus 5 / Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On Claude Opus 5 adaptive is also what you get by omitting `thinking` entirely. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead.
 
 ```typescript
 const stream = client.messages.stream({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 64000,
-  thinking: { type: "adaptive" },
+  thinking: { type: "adaptive", display: "summarized" }, // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7
   messages: [{ role: "user", content: "Analyze this problem" }],
 });
 
@@ -82,7 +82,7 @@ const getWeather = betaZodTool({
 });
 
 const runner = client.beta.messages.toolRunner({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 64000,
   tools: [getWeather],
   messages: [
@@ -117,7 +117,7 @@ for await (const messageStream of runner) {
 
 ```typescript
 const stream = client.messages.stream({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 64000,
   messages: [{ role: "user", content: "Hello" }],
 });

skills/claude-api/typescript/claude-api/tool-use.md

@@ -30,7 +30,7 @@ const getWeather = betaZodTool({
 
 // The tool runner handles the agentic loop and returns the final message
 const finalMessage = await client.beta.messages.toolRunner({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   tools: [getWeather],
   messages: [{ role: "user", content: "What's the weather in Paris?" }],
@@ -39,18 +39,59 @@ const finalMessage = await client.beta.messages.toolRunner({
 console.log(finalMessage.content);
 ```
 
+Zod is optional — `betaTool()` from `@anthropic-ai/sdk/helpers/beta/json-schema` accepts a raw JSON Schema `inputSchema` plus a `run` function if you don't want a Zod dependency.
+
 **Key benefits of the tool runner:**
 
 - No manual loop — the SDK handles calling tools and feeding results back
-- Type-safe tool inputs via Zod schemas
+- Type-safe tool inputs via Zod schemas (or raw JSON Schema via `betaTool()`)
 - Tool schemas are generated automatically from Zod definitions
 - Iteration stops automatically when Claude has no more tool calls
 
+### Server tools with the tool runner
+
+The runner's `tools` array accepts raw server-tool definitions (`web_search_20260209`, `web_fetch_20260209`, code execution) alongside runnable tools — pass the literal tool object; server tools run on Anthropic's servers, so there is no `run` function.
+
+**Caution — the runner does not auto-resume `pause_turn` (as of `@anthropic-ai/sdk` 0.110.0).** A long-running server-tool turn can stop with `stop_reason: "pause_turn"`. The runner only continues after a client tool produces a result, so a paused turn ends the loop and is returned as the final message — no error, no warning, just a silently truncated answer. If you mix server tools into the runner, check `stop_reason` on every iteration and resume by pushing the paused assistant turn back:
+
+```typescript
+const params = {
+  model: "claude-opus-5",
+  max_tokens: 16000,
+  tools: [getWeather, { type: "web_search_20260209", name: "web_search", max_uses: 5 }],
+  messages: [{ role: "user", content: "Compare this week's forecasts for Paris across two sources" }],
+};
+
+const runner = client.beta.messages.toolRunner(params);
+
+// Non-streaming: each iteration yields a complete message
+for await (const message of runner) {
+  if (message.stop_reason === "pause_turn") {
+    runner.pushMessages({ role: "assistant", content: message.content });
+  }
+}
+
+// Streaming alternative — construct the runner with `stream: true` (same
+// params as above). Each iteration then yields a stream, not a message — a
+// bare `message.stop_reason` check never fires. Resolve the stream first:
+const streamingRunner = client.beta.messages.toolRunner({ ...params, stream: true });
+for await (const stream of streamingRunner) {
+  const message = await stream.finalMessage();
+  if (message.stop_reason === "pause_turn") {
+    streamingRunner.pushMessages({ role: "assistant", content: message.content });
+  }
+}
+```
+
+Each pause–resume consumes a `max_iterations` tick, so a capped run can still end paused — check the final message's `stop_reason` before trusting the result (after the loop, call `.done()` on the runner you iterated to get the final message). Alternatively, use the manual loop below, which handles `pause_turn` explicitly.
+
 ---
 
 ## Manual Agentic Loop
 
-Use this when you need fine-grained control (custom logging, conditional tool execution, streaming individual iterations, human-in-the-loop approval):
+Prefer the tool runner above. Drop to a manual loop only when you need control the runner does not expose (e.g., a custom transport, request shapes the SDK cannot build, or avoiding a beta dependency — the runner is beta, and it supports per-token streaming via `stream: true`). Human-in-the-loop approval does *not* require a manual loop — gate inside the tool's `run()` function (return a "user declined" result) or inspect pending `tool_use` blocks and call `setMessagesParams()` between iterations.
+
+If you do need a manual loop:
 
 ```typescript
 import Anthropic from "@anthropic-ai/sdk";
@@ -61,7 +102,7 @@ let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }];
 
 while (true) {
   const response = await client.messages.create({
-    model: "claude-opus-4-8",
+    model: "claude-opus-5",
     max_tokens: 16000,
     tools: tools,
     messages: messages,
@@ -108,7 +149,7 @@ let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }];
 
 while (true) {
   const stream = client.messages.stream({
-    model: "claude-opus-4-8",
+    model: "claude-opus-5",
     max_tokens: 64000,
     tools,
     messages,
@@ -163,7 +204,7 @@ while (true) {
 
 ```typescript
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   tools: tools,
   messages: [{ role: "user", content: "What's the weather in Paris?" }],
@@ -174,7 +215,7 @@ for (const block of response.content) {
     const result = await executeTool(block.name, block.input);
 
     const followup = await client.messages.create({
-      model: "claude-opus-4-8",
+      model: "claude-opus-5",
       max_tokens: 16000,
       tools: tools,
       messages: [
@@ -198,7 +239,7 @@ for (const block of response.content) {
 
 ```typescript
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   tools: tools,
   tool_choice: { type: "tool", name: "get_weather" },
@@ -208,16 +249,16 @@ const response = await client.messages.create({
 
 ---
 
-## Server-Side Tools
+## Anthropic-Defined Tools
 
-Version-suffixed `type` literals; `name` is fixed per interface. Pass plain object literals — the `ToolUnion` type is satisfied structurally. **The `name`/`type` pair must match the interface**: mixing `str_replace_based_edit_tool` (20250728 name) with `text_editor_20250124` (which expects `str_replace_editor`) is a TS2322.
+Version-suffixed `type` literals; `name` is fixed per interface. Web search and code execution are server-executed; bash and text editor are client-executed (you handle the `tool_use` locally — see `shared/tool-use-concepts.md`). Pass plain object literals — the `ToolUnion` type is satisfied structurally. **The `name`/`type` pair must match the interface**: mixing `str_replace_based_edit_tool` (20250728 name) with `text_editor_20250124` (which expects `str_replace_editor`) is a TS2322.
 
 **Don't type-annotate as `Tool[]`** — `Tool` is just the custom-tool variant. Let structural typing infer from the `tools` param, or annotate as `Anthropic.Messages.ToolUnion[]` if you must:
 
 ```typescript
 // ✓ let inference work — no annotation
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   tools: [
     { type: "text_editor_20250728", name: "str_replace_based_edit_tool" },
@@ -257,7 +298,7 @@ import Anthropic from "@anthropic-ai/sdk";
 const client = new Anthropic();
 
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   messages: [
     {
@@ -305,7 +346,7 @@ const uploaded = await client.beta.files.upload({
 // Code execution is GA; Files API is still beta (pass via RequestOptions)
 const response = await client.messages.create(
   {
-    model: "claude-opus-4-8",
+    model: "claude-opus-5",
     max_tokens: 16000,
     messages: [
       {
@@ -365,7 +406,7 @@ for (const block of response.content) {
 ```typescript
 // First request: set up environment
 const response1 = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   messages: [
     {
@@ -382,7 +423,7 @@ const containerId = response1.container!.id;
 
 const response2 = await client.messages.create({
   container: containerId,
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   messages: [
     {
@@ -402,7 +443,7 @@ const response2 = await client.messages.create({
 
 ```typescript
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   messages: [
     {
@@ -436,7 +477,7 @@ const handlers: MemoryToolHandlers = {
 const memory = betaMemoryTool(handlers);
 
 const runner = client.beta.messages.toolRunner({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   tools: [memory],
   messages: [{ role: "user", content: "Remember my preferences" }],
@@ -473,7 +514,7 @@ const ContactInfoSchema = z.object({
 const client = new Anthropic();
 
 const response = await client.messages.parse({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   messages: [
     {
@@ -495,7 +536,7 @@ console.log(response.parsed_output!.name); // "Jane Doe"
 
 ```typescript
 const response = await client.messages.create({
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   max_tokens: 16000,
   messages: [
     {
@@ -525,3 +566,24 @@ const response = await client.messages.create({
   ],
 });
 ```
+
+---
+
+## Agent Skills
+
+Enable an Anthropic-managed skill (e.g., `pptx`) via `container.skills` + the `code_execution` tool on the beta path. Both beta headers are required. Outputs land as files in the response content — download by file ID via the Files API.
+
+```typescript
+const response = await client.beta.messages.create({
+  model: "claude-opus-5",
+  max_tokens: 16000,
+  container: {
+    skills: [{ type: "anthropic", skill_id: "pptx", version: "latest" }],
+  },
+  tools: [{ type: "code_execution_20260521", name: "code_execution" }],
+  betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
+  messages: [{ role: "user", content: "Create a 3-slide deck about X." }],
+});
+// Find the file_id in response.content, then:
+// await client.beta.files.download(fileId)
+```

skills/claude-api/typescript/managed-agents/README.md

@@ -2,7 +2,7 @@
 
 > **Bindings not shown here:** This README covers the most common managed-agents flows for TypeScript. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the TypeScript SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
 
-> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
+> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. **Recommended:** define agents and environments as version-controlled YAML applied with the `ant` CLI — see `shared/anthropic-cli.md` (its live-docs URL is in `shared/live-sources.md`). The CLI owns the control plane (create/update); your code owns the data plane (sessions with the stored ID). The examples below show in-code creation for when you must provision programmatically; in production the create call belongs in setup, not in the request path.
 
 ## Installation
 
@@ -54,7 +54,7 @@ console.log(environment.id); // env_...
 const agent = await client.beta.agents.create(
   {
     name: "Coding Assistant",
-    model: "claude-opus-4-8",
+    model: "claude-opus-5",
     tools: [{ type: "agent_toolset_20260401", default_config: { enabled: true } }],
   },
 );
@@ -67,6 +67,7 @@ const session = await client.beta.sessions.create(
   },
 );
 console.log(session.id, session.status);
+console.log(`Trace: https://platform.claude.com/workspaces/default/sessions/${session.id}`); // swap 'default' for your workspace ID if the API key is not in the Default workspace
 ```
 
 ### With system prompt and custom tools
@@ -75,7 +76,7 @@ console.log(session.id, session.status);
 const agent = await client.beta.agents.create(
   {
     name: "Code Reviewer",
-    model: "claude-opus-4-8",
+    model: "claude-opus-5",
     system: "You are a senior code reviewer.",
     tools: [
       { type: "agent_toolset_20260401", default_config: { enabled: true } },
@@ -336,7 +337,7 @@ await client.beta.sessions.archive("sesn_011CZxAbc123Def456");
 // Agent declares MCP server (no auth here — auth goes in a vault)
 const agent = await client.beta.agents.create({
   name: "MCP Agent",
-  model: "claude-opus-4-8",
+  model: "claude-opus-5",
   mcp_servers: [
     { type: "url", name: "my-tools", url: "https://my-mcp-server.example.com/sse" },
   ],

skills/docx/SKILL.md

@@ -1,590 +1,91 @@
 ---
 name: docx
-description: "Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation."
+description: "Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation."
 license: Proprietary. LICENSE.txt has complete terms
 ---
 
 # DOCX creation, editing, and analysis
 
-## Overview
-
-A .docx file is a ZIP archive containing XML files.
-
-## Quick Reference
+A `.docx` is a ZIP archive of XML files. Choose your approach by task:
 
 | Task | Approach |
-|------|----------|
-| Read/analyze content | `pandoc` or unpack for raw XML |
-| Create new document | Use `docx-js` - see Creating New Documents below |
-| Edit existing document | Unpack → edit XML → repack - see Editing Existing Documents below |
+|---|---|
+| **Create** a new document | Write a `docx` (npm) script — see gotchas below |
+| **Edit** an existing document | `unzip` → edit `word/document.xml` → `zip` (docx-js cannot open existing files) |
+| **Read** content | `pandoc -t markdown file.docx` |
 
-### Converting .doc to .docx
+> Script paths below are relative to this skill's directory.
 
-Legacy `.doc` files must be converted before editing:
+## Creating with docx-js — gotchas
+
+`docx` is preinstalled — do not run `npm install` first; write the script and `require('docx')` directly. Only if that require fails: `npm install docx`. The model knows the API; these are the footguns:
+
+- **Page size defaults to A4.** For US Letter set `page: { size: { width: 12240, height: 15840 } }` (DXA; 1440 = 1″).
+- **Landscape:** pass portrait dimensions and `orientation: PageOrientation.LANDSCAPE` — docx-js swaps width/height internally.
+- **Tables need dual widths:** set `columnWidths` on the table AND `width` on every cell, both in `WidthType.DXA` (PERCENTAGE breaks in Google Docs). Column widths must sum to the table width.
+- **Table shading:** use `ShadingType.CLEAR`, never `SOLID` (renders black).
+- **Lists:** never insert `•` literally; use a `numbering` config with `LevelFormat.BULLET`.
+- **`ImageRun` requires `type:`** (`"png"`, `"jpg"`, …).
+- **`PageBreak` must be inside a `Paragraph`.**
+- **Never use `\n`** — use separate `Paragraph` elements.
+- **TOC:** headings must use built-in `HeadingLevel.*`; custom heading styles need `outlineLevel` set or they won't appear.
+- **Don't use a table as a horizontal rule** — use a paragraph bottom border instead.
+- **Dot-leader / right-aligned-on-same-line:** use `PositionalTab` (`alignment: PositionalTabAlignment.RIGHT`, `leader: PositionalTabLeader.DOT`) inside a `TextRun`, not literal `.` or space padding.
+
+## Verify the output
+
+After writing a `.docx`, render it and look at it:
 
 ```bash
-python scripts/office/soffice.py --headless --convert-to docx document.doc
+python scripts/office/soffice.py --headless --convert-to pdf output.docx
+pdftoppm -jpeg -r 100 output.pdf page
+ls page-*.jpg   # then Read the images
 ```
 
-### Reading Content
+`pdftoppm` zero-pads page numbers to the width of the page count (`page-01.jpg`…`page-12.jpg`).
+
+## Editing existing documents
+
+Legacy `.doc` files must be converted first: `python scripts/office/soffice.py --headless --convert-to docx file.doc`.
 
 ```bash
-# Text extraction with tracked changes
-pandoc --track-changes=all document.docx -o output.md
-
-# Raw XML access
-python scripts/office/unpack.py document.docx unpacked/
+unzip -q doc.docx -d unpacked/
+find unpacked -type l -delete   # strip symlink entries — docx from external parties is untrusted
+python scripts/merge_runs.py unpacked/   # coalesce fragmented runs so text is findable
+# edit unpacked/word/document.xml in place — do NOT reformat or pretty-print
+(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
+python scripts/office/validate.py out.docx --original doc.docx   # XSD checks; --auto-repair fixes common issues
+# redlining? add --author "<the name you redlined under>" to check every edit is tracked
 ```
 
-### Converting to Images
+Word splits text across many `<w:r>` runs (revision ids, spell-check markers), so a phrase you can see in the document often doesn't exist as a contiguous string in the XML. `merge_runs.py` merges adjacent identically-formatted runs in `word/document.xml` without changing content or rendering; it also accepts a `.docx` directly (`python scripts/merge_runs.py doc.docx -o merged.docx`).
+
+**Tracked changes:** when redlining, validate with `--author "<the name you redlined under>"` (needs `--original`) — it reports any text you changed without a `<w:ins>`/`<w:del>` around it, which is easy to do by accident and invisible in the accepted view. Wrap runs in `<w:ins>`/`<w:del>` with `w:id`, `w:author`, `w:date` attributes. Inside `<w:del>`, the text element is `<w:delText>`, not `<w:t>`. A deleted paragraph mark (`<w:pPr><w:rPr><w:del w:id=".." w:author=".." w:date=".."/></w:rPr></w:pPr>`) means "merge this paragraph into the next" — so deleting a paragraph outright is that plus a `<w:del>` around every run. The `<w:del/>` must come before the rPr's other children; their order is schema-enforced.
+
+To produce a clean copy with all tracked changes accepted: `python scripts/accept_changes.py in.docx out.docx`.
+
+Accepting a deleted paragraph mark should join that paragraph to the one below it, so a paragraph whose runs are *all* deleted vanishes. Word does this; `accept_changes.py` and `pandoc --track-changes=accept` don't always. Both fail the same way — they strip the deleted text but leave the emptied paragraph behind, which reads as a stray empty bullet when it was auto-numbered:
+
+- `pandoc --track-changes=accept` never joins the paragraphs.
+- `accept_changes.py` (LibreOffice) joins them correctly, except when the deleted paragraph is followed by an empty spacer paragraph.
+
+An empty bullet in either view is an artifact of that view, not a defect in the document. Check paragraph deletions in the XML.
+
+## Comments
+
+Comments require six cross-linked files. Use the helper — directory mode when you'll also be editing `document.xml` (saves an unzip/rezip cycle), `.docx`-direct mode otherwise:
 
 ```bash
-python scripts/office/soffice.py --headless --convert-to pdf document.docx
-pdftoppm -jpeg -r 150 document.pdf page
+# Against an already-unpacked directory (preferred when also placing markers)
+python scripts/comment.py unpacked/ "Fees & expenses cap is too low"
+python scripts/comment.py unpacked/ "Agreed" --parent 0
+
+# Against a .docx directly
+python scripts/comment.py contract.docx "This cap is too low" -o annotated.docx
 ```
 
-### Accepting Tracked Changes
-
-To produce a clean document with all tracked changes accepted (requires LibreOffice):
-
-```bash
-python scripts/accept_changes.py input.docx output.docx
-```
-
----
-
-## Creating New Documents
-
-Generate .docx files with JavaScript, then validate. Install: `npm install -g docx`
-
-### Setup
-```javascript
-const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
-        Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
-        InternalHyperlink, Bookmark, FootnoteReferenceRun, PositionalTab,
-        PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader,
-        TabStopType, TabStopPosition, Column, SectionType,
-        TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
-        VerticalAlign, PageNumber, PageBreak } = require('docx');
-
-const doc = new Document({ sections: [{ children: [/* content */] }] });
-Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));
-```
-
-### Validation
-After creating the file, validate it. If validation fails, unpack, fix the XML, and repack.
-```bash
-python scripts/office/validate.py doc.docx
-```
-
-### Page Size
-
-```javascript
-// CRITICAL: docx-js defaults to A4, not US Letter
-// Always set page size explicitly for consistent results
-sections: [{
-  properties: {
-    page: {
-      size: {
-        width: 12240,   // 8.5 inches in DXA
-        height: 15840   // 11 inches in DXA
-      },
-      margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1 inch margins
-    }
-  },
-  children: [/* content */]
-}]
-```
-
-**Common page sizes (DXA units, 1440 DXA = 1 inch):**
-
-| Paper | Width | Height | Content Width (1" margins) |
-|-------|-------|--------|---------------------------|
-| US Letter | 12,240 | 15,840 | 9,360 |
-| A4 (default) | 11,906 | 16,838 | 9,026 |
-
-**Landscape orientation:** docx-js swaps width/height internally, so pass portrait dimensions and let it handle the swap:
-```javascript
-size: {
-  width: 12240,   // Pass SHORT edge as width
-  height: 15840,  // Pass LONG edge as height
-  orientation: PageOrientation.LANDSCAPE  // docx-js swaps them in the XML
-},
-// Content width = 15840 - left margin - right margin (uses the long edge)
-```
-
-### Styles (Override Built-in Headings)
-
-Use Arial as the default font (universally supported). Keep titles black for readability.
-
-```javascript
-const doc = new Document({
-  styles: {
-    default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt default
-    paragraphStyles: [
-      // IMPORTANT: Use exact IDs to override built-in styles
-      { id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
-        run: { size: 32, bold: true, font: "Arial" },
-        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // outlineLevel required for TOC
-      { id: "Heading2", name: "Heading 2", basedOn: "Normal", next: "Normal", quickFormat: true,
-        run: { size: 28, bold: true, font: "Arial" },
-        paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },
-    ]
-  },
-  sections: [{
-    children: [
-      new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Title")] }),
-    ]
-  }]
-});
-```
-
-### Lists (NEVER use unicode bullets)
-
-```javascript
-// ❌ WRONG - never manually insert bullet characters
-new Paragraph({ children: [new TextRun("• Item")] })  // BAD
-new Paragraph({ children: [new TextRun("\u2022 Item")] })  // BAD
-
-// ✅ CORRECT - use numbering config with LevelFormat.BULLET
-const doc = new Document({
-  numbering: {
-    config: [
-      { reference: "bullets",
-        levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
-          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
-      { reference: "numbers",
-        levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
-          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
-    ]
-  },
-  sections: [{
-    children: [
-      new Paragraph({ numbering: { reference: "bullets", level: 0 },
-        children: [new TextRun("Bullet item")] }),
-      new Paragraph({ numbering: { reference: "numbers", level: 0 },
-        children: [new TextRun("Numbered item")] }),
-    ]
-  }]
-});
-
-// ⚠️ Each reference creates INDEPENDENT numbering
-// Same reference = continues (1,2,3 then 4,5,6)
-// Different reference = restarts (1,2,3 then 1,2,3)
-```
-
-### Tables
-
-**CRITICAL: Tables need dual widths** - set both `columnWidths` on the table AND `width` on each cell. Without both, tables render incorrectly on some platforms.
-
-```javascript
-// CRITICAL: Always set table width for consistent rendering
-// CRITICAL: Use ShadingType.CLEAR (not SOLID) to prevent black backgrounds
-const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
-const borders = { top: border, bottom: border, left: border, right: border };
-
-new Table({
-  width: { size: 9360, type: WidthType.DXA }, // Always use DXA (percentages break in Google Docs)
-  columnWidths: [4680, 4680], // Must sum to table width (DXA: 1440 = 1 inch)
-  rows: [
-    new TableRow({
-      children: [
-        new TableCell({
-          borders,
-          width: { size: 4680, type: WidthType.DXA }, // Also set on each cell
-          shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR not SOLID
-          margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Cell padding (internal, not added to width)
-          children: [new Paragraph({ children: [new TextRun("Cell")] })]
-        })
-      ]
-    })
-  ]
-})
-```
-
-**Table width calculation:**
-
-Always use `WidthType.DXA` — `WidthType.PERCENTAGE` breaks in Google Docs.
-
-```javascript
-// Table width = sum of columnWidths = content width
-// US Letter with 1" margins: 12240 - 2880 = 9360 DXA
-width: { size: 9360, type: WidthType.DXA },
-columnWidths: [7000, 2360]  // Must sum to table width
-```
-
-**Width rules:**
-- **Always use `WidthType.DXA`** — never `WidthType.PERCENTAGE` (incompatible with Google Docs)
-- Table width must equal the sum of `columnWidths`
-- Cell `width` must match corresponding `columnWidth`
-- Cell `margins` are internal padding - they reduce content area, not add to cell width
-- For full-width tables: use content width (page width minus left and right margins)
-
-### Images
-
-```javascript
-// CRITICAL: type parameter is REQUIRED
-new Paragraph({
-  children: [new ImageRun({
-    type: "png", // Required: png, jpg, jpeg, gif, bmp, svg
-    data: fs.readFileSync("image.png"),
-    transformation: { width: 200, height: 150 },
-    altText: { title: "Title", description: "Desc", name: "Name" } // All three required
-  })]
-})
-```
-
-### Page Breaks
-
-```javascript
-// CRITICAL: PageBreak must be inside a Paragraph
-new Paragraph({ children: [new PageBreak()] })
-
-// Or use pageBreakBefore
-new Paragraph({ pageBreakBefore: true, children: [new TextRun("New page")] })
-```
-
-### Hyperlinks
-
-```javascript
-// External link
-new Paragraph({
-  children: [new ExternalHyperlink({
-    children: [new TextRun({ text: "Click here", style: "Hyperlink" })],
-    link: "https://example.com",
-  })]
-})
-
-// Internal link (bookmark + reference)
-// 1. Create bookmark at destination
-new Paragraph({ heading: HeadingLevel.HEADING_1, children: [
-  new Bookmark({ id: "chapter1", children: [new TextRun("Chapter 1")] }),
-]})
-// 2. Link to it
-new Paragraph({ children: [new InternalHyperlink({
-  children: [new TextRun({ text: "See Chapter 1", style: "Hyperlink" })],
-  anchor: "chapter1",
-})]})
-```
-
-### Footnotes
-
-```javascript
-const doc = new Document({
-  footnotes: {
-    1: { children: [new Paragraph("Source: Annual Report 2024")] },
-    2: { children: [new Paragraph("See appendix for methodology")] },
-  },
-  sections: [{
-    children: [new Paragraph({
-      children: [
-        new TextRun("Revenue grew 15%"),
-        new FootnoteReferenceRun(1),
-        new TextRun(" using adjusted metrics"),
-        new FootnoteReferenceRun(2),
-      ],
-    })]
-  }]
-});
-```
-
-### Tab Stops
-
-```javascript
-// Right-align text on same line (e.g., date opposite a title)
-new Paragraph({
-  children: [
-    new TextRun("Company Name"),
-    new TextRun("\tJanuary 2025"),
-  ],
-  tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
-})
-
-// Dot leader (e.g., TOC-style)
-new Paragraph({
-  children: [
-    new TextRun("Introduction"),
-    new TextRun({ children: [
-      new PositionalTab({
-        alignment: PositionalTabAlignment.RIGHT,
-        relativeTo: PositionalTabRelativeTo.MARGIN,
-        leader: PositionalTabLeader.DOT,
-      }),
-      "3",
-    ]}),
-  ],
-})
-```
-
-### Multi-Column Layouts
-
-```javascript
-// Equal-width columns
-sections: [{
-  properties: {
-    column: {
-      count: 2,          // number of columns
-      space: 720,        // gap between columns in DXA (720 = 0.5 inch)
-      equalWidth: true,
-      separate: true,    // vertical line between columns
-    },
-  },
-  children: [/* content flows naturally across columns */]
-}]
-
-// Custom-width columns (equalWidth must be false)
-sections: [{
-  properties: {
-    column: {
-      equalWidth: false,
-      children: [
-        new Column({ width: 5400, space: 720 }),
-        new Column({ width: 3240 }),
-      ],
-    },
-  },
-  children: [/* content */]
-}]
-```
-
-Force a column break with a new section using `type: SectionType.NEXT_COLUMN`.
-
-### Table of Contents
-
-```javascript
-// CRITICAL: Headings must use HeadingLevel ONLY - no custom styles
-new TableOfContents("Table of Contents", { hyperlink: true, headingStyleRange: "1-3" })
-```
-
-### Headers/Footers
-
-```javascript
-sections: [{
-  properties: {
-    page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 inch
-  },
-  headers: {
-    default: new Header({ children: [new Paragraph({ children: [new TextRun("Header")] })] })
-  },
-  footers: {
-    default: new Footer({ children: [new Paragraph({
-      children: [new TextRun("Page "), new TextRun({ children: [PageNumber.CURRENT] })]
-    })] })
-  },
-  children: [/* content */]
-}]
-```
-
-### Critical Rules for docx-js
-
-- **Set page size explicitly** - docx-js defaults to A4; use US Letter (12240 x 15840 DXA) for US documents
-- **Landscape: pass portrait dimensions** - docx-js swaps width/height internally; pass short edge as `width`, long edge as `height`, and set `orientation: PageOrientation.LANDSCAPE`
-- **Never use `\n`** - use separate Paragraph elements
-- **Never use unicode bullets** - use `LevelFormat.BULLET` with numbering config
-- **PageBreak must be in Paragraph** - standalone creates invalid XML
-- **ImageRun requires `type`** - always specify png/jpg/etc
-- **Always set table `width` with DXA** - never use `WidthType.PERCENTAGE` (breaks in Google Docs)
-- **Tables need dual widths** - `columnWidths` array AND cell `width`, both must match
-- **Table width = sum of columnWidths** - for DXA, ensure they add up exactly
-- **Always add cell margins** - use `margins: { top: 80, bottom: 80, left: 120, right: 120 }` for readable padding
-- **Use `ShadingType.CLEAR`** - never SOLID for table shading
-- **Never use tables as dividers/rules** - cells have minimum height and render as empty boxes (including in headers/footers); use `border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } }` on a Paragraph instead. For two-column footers, use tab stops (see Tab Stops section), not tables
-- **TOC requires HeadingLevel only** - no custom styles on heading paragraphs
-- **Override built-in styles** - use exact IDs: "Heading1", "Heading2", etc.
-- **Include `outlineLevel`** - required for TOC (0 for H1, 1 for H2, etc.)
-
----
-
-## Editing Existing Documents
-
-**Follow all 3 steps in order.**
-
-### Step 1: Unpack
-```bash
-python scripts/office/unpack.py document.docx unpacked/
-```
-Extracts XML, pretty-prints, merges adjacent runs, and converts smart quotes to XML entities (`&#x201C;` etc.) so they survive editing. Use `--merge-runs false` to skip run merging.
-
-### Step 2: Edit XML
-
-Edit files in `unpacked/word/`. See XML Reference below for patterns.
-
-**Use "Claude" as the author** for tracked changes and comments, unless the user explicitly requests use of a different name.
-
-**Use the Edit tool directly for string replacement. Do not write Python scripts.** Scripts introduce unnecessary complexity. The Edit tool shows exactly what is being replaced.
-
-**CRITICAL: Use smart quotes for new content.** When adding text with apostrophes or quotes, use XML entities to produce smart quotes:
-```xml
-<!-- Use these entities for professional typography -->
-<w:t>Here&#x2019;s a quote: &#x201C;Hello&#x201D;</w:t>
-```
-| Entity | Character |
-|--------|-----------|
-| `&#x2018;` | ‘ (left single) |
-| `&#x2019;` | ’ (right single / apostrophe) |
-| `&#x201C;` | “ (left double) |
-| `&#x201D;` | ” (right double) |
-
-**Adding comments:** Use `comment.py` to handle boilerplate across multiple XML files (text must be pre-escaped XML):
-```bash
-python scripts/comment.py unpacked/ 0 "Comment text with &amp; and &#x2019;"
-python scripts/comment.py unpacked/ 1 "Reply text" --parent 0  # reply to comment 0
-python scripts/comment.py unpacked/ 0 "Text" --author "Custom Author"  # custom author name
-```
-Then add markers to document.xml (see Comments in XML Reference).
-
-### Step 3: Pack
-```bash
-python scripts/office/pack.py unpacked/ output.docx --original document.docx
-```
-Validates with auto-repair, condenses XML, and creates DOCX. Use `--validate false` to skip.
-
-**Auto-repair will fix:**
-- `durableId` >= 0x7FFFFFFF (regenerates valid ID)
-- Missing `xml:space="preserve"` on `<w:t>` with whitespace
-
-**Auto-repair won't fix:**
-- Malformed XML, invalid element nesting, missing relationships, schema violations
-
-### Common Pitfalls
-
-- **Replace entire `<w:r>` elements**: When adding tracked changes, replace the whole `<w:r>...</w:r>` block with `<w:del>...<w:ins>...` as siblings. Don't inject tracked change tags inside a run.
-- **Preserve `<w:rPr>` formatting**: Copy the original run's `<w:rPr>` block into your tracked change runs to maintain bold, font size, etc.
-
----
-
-## XML Reference
-
-### Schema Compliance
-
-- **Element order in `<w:pPr>`**: `<w:pStyle>`, `<w:numPr>`, `<w:spacing>`, `<w:ind>`, `<w:jc>`, `<w:rPr>` last
-- **Whitespace**: Add `xml:space="preserve"` to `<w:t>` with leading/trailing spaces
-- **RSIDs**: Must be 8-digit hex (e.g., `00AB1234`)
-
-### Tracked Changes
-
-**Insertion:**
-```xml
-<w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
-  <w:r><w:t>inserted text</w:t></w:r>
-</w:ins>
-```
-
-**Deletion:**
-```xml
-<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
-  <w:r><w:delText>deleted text</w:delText></w:r>
-</w:del>
-```
-
-**Inside `<w:del>`**: Use `<w:delText>` instead of `<w:t>`, and `<w:delInstrText>` instead of `<w:instrText>`.
-
-**Minimal edits** - only mark what changes:
-```xml
-<!-- Change "30 days" to "60 days" -->
-<w:r><w:t>The term is </w:t></w:r>
-<w:del w:id="1" w:author="Claude" w:date="...">
-  <w:r><w:delText>30</w:delText></w:r>
-</w:del>
-<w:ins w:id="2" w:author="Claude" w:date="...">
-  <w:r><w:t>60</w:t></w:r>
-</w:ins>
-<w:r><w:t> days.</w:t></w:r>
-```
-
-**Deleting entire paragraphs/list items** - when removing ALL content from a paragraph, also mark the paragraph mark as deleted so it merges with the next paragraph. Add `<w:del/>` inside `<w:pPr><w:rPr>`:
-```xml
-<w:p>
-  <w:pPr>
-    <w:numPr>...</w:numPr>  <!-- list numbering if present -->
-    <w:rPr>
-      <w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z"/>
-    </w:rPr>
-  </w:pPr>
-  <w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
-    <w:r><w:delText>Entire paragraph content being deleted...</w:delText></w:r>
-  </w:del>
-</w:p>
-```
-Without the `<w:del/>` in `<w:pPr><w:rPr>`, accepting changes leaves an empty paragraph/list item.
-
-**Rejecting another author's insertion** - nest deletion inside their insertion:
-```xml
-<w:ins w:author="Jane" w:id="5">
-  <w:del w:author="Claude" w:id="10">
-    <w:r><w:delText>their inserted text</w:delText></w:r>
-  </w:del>
-</w:ins>
-```
-
-**Restoring another author's deletion** - add insertion after (don't modify their deletion):
-```xml
-<w:del w:author="Jane" w:id="5">
-  <w:r><w:delText>deleted text</w:delText></w:r>
-</w:del>
-<w:ins w:author="Claude" w:id="10">
-  <w:r><w:t>deleted text</w:t></w:r>
-</w:ins>
-```
-
-### Comments
-
-After running `comment.py` (see Step 2), add markers to document.xml. For replies, use `--parent` flag and nest markers inside the parent's.
-
-**CRITICAL: `<w:commentRangeStart>` and `<w:commentRangeEnd>` are siblings of `<w:r>`, never inside `<w:r>`.**
-
-```xml
-<!-- Comment markers are direct children of w:p, never inside w:r -->
-<w:commentRangeStart w:id="0"/>
-<w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
-  <w:r><w:delText>deleted</w:delText></w:r>
-</w:del>
-<w:r><w:t> more text</w:t></w:r>
-<w:commentRangeEnd w:id="0"/>
-<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
-
-<!-- Comment 0 with reply 1 nested inside -->
-<w:commentRangeStart w:id="0"/>
-  <w:commentRangeStart w:id="1"/>
-  <w:r><w:t>text</w:t></w:r>
-  <w:commentRangeEnd w:id="1"/>
-<w:commentRangeEnd w:id="0"/>
-<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
-<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="1"/></w:r>
-```
-
-### Images
-
-1. Add image file to `word/media/`
-2. Add relationship to `word/_rels/document.xml.rels`:
-```xml
-<Relationship Id="rId5" Type=".../image" Target="media/image1.png"/>
-```
-3. Add content type to `[Content_Types].xml`:
-```xml
-<Default Extension="png" ContentType="image/png"/>
-```
-4. Reference in document.xml:
-```xml
-<w:drawing>
-  <wp:inline>
-    <wp:extent cx="914400" cy="914400"/>  <!-- EMUs: 914400 = 1 inch -->
-    <a:graphic>
-      <a:graphicData uri=".../picture">
-        <pic:pic>
-          <pic:blipFill><a:blip r:embed="rId5"/></pic:blipFill>
-        </pic:pic>
-      </a:graphicData>
-    </a:graphic>
-  </wp:inline>
-</w:drawing>
-```
-
----
+The script writes `comments.xml`, `commentsExtended.xml`, `commentsIds.xml`, `commentsExtensible.xml`, the relationships, and the content-type overrides. Comment IDs are auto-assigned. It then prints the `<w:commentRangeStart>`/`<w:commentRangeEnd>`/`<w:commentReference>` snippet to add to `word/document.xml` so the comment anchors to specific text — until you place those markers, the comment exists but is not visible.
 
 ## Dependencies
 
-- **pandoc**: Text extraction
-- **docx**: `npm install -g docx` (new documents)
-- **LibreOffice**: PDF conversion (auto-configured for sandboxed environments via `scripts/office/soffice.py`)
-- **Poppler**: `pdftoppm` for images
+`docx` (npm, preinstalled — install only if `require('docx')` fails) · `pandoc` · LibreOffice (`soffice`) · `pdftoppm` (Poppler)

skills/docx/scripts/comment.py

@@ -1,26 +1,41 @@
-"""Add comments to DOCX documents.
+"""Add comments to a DOCX document.
+
+Accepts either an unpacked directory OR a .docx/.dotx file directly.
 
 Usage:
-    python comment.py unpacked/ 0 "Comment text"
-    python comment.py unpacked/ 1 "Reply text" --parent 0
+    # Against an unpacked directory (writes satellite files in place)
+    python comment.py unpacked/ "Comment text"
+    python comment.py unpacked/ "Reply text" --parent 0
 
-Text should be pre-escaped XML (e.g., & for &, ’ for smart quotes).
+    # Against a .docx directly (extracts, writes satellite files, rezips)
+    python comment.py contract.docx "This cap is too low" -o annotated.docx
+    python comment.py contract.docx "Comment" --id 5      # explicit ID
 
-After running, add markers to document.xml:
-  <w:commentRangeStart w:id="0"/>
+The comment ID is auto-assigned (max existing + 1) unless --id is given.
+Plain text is XML-escaped automatically; if you pass already-escaped text
+(e.g. &amp;, &#x2019;) use --raw to skip escaping.
+
+After running, add markers to word/document.xml so the comment is visible:
+  <w:commentRangeStart w:id="N"/>
   ... commented content ...
-  <w:commentRangeEnd w:id="0"/>
-  <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
+  <w:commentRangeEnd w:id="N"/>
+  <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="N"/></w:r>
 """
 
 import argparse
 import random
 import shutil
 import sys
+import tempfile
+import zipfile
 from datetime import datetime, timezone
 from pathlib import Path
 
 import defusedxml.minidom
+from xml.parsers.expat import ExpatError
+from xml.sax.saxutils import escape as xml_escape
+
+from office.helpers import opc_target, rezip as _rezip, safe_extract as _safe_extract
 
 TEMPLATE_DIR = Path(__file__).parent / "templates"
 NS = {
@@ -44,39 +59,38 @@ COMMENT_XML = """\
         <w:sz w:val="20"/>
         <w:szCs w:val="20"/>
       </w:rPr>
-      <w:t>{text}</w:t>
+      <w:t xml:space="preserve">{text}</w:t>
     </w:r>
   </w:p>
 </w:comment>"""
 
 COMMENT_MARKER_TEMPLATE = """
-Add to document.xml (markers must be direct children of w:p, never inside w:r):
+Add to word/document.xml (markers must be direct children of w:p, never inside w:r):
   <w:commentRangeStart w:id="{cid}"/>
   <w:r>...</w:r>
   <w:commentRangeEnd w:id="{cid}"/>
   <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="{cid}"/></w:r>"""
 
 REPLY_MARKER_TEMPLATE = """
-Nest markers inside parent {pid}'s markers (markers must be direct children of w:p, never inside w:r):
+Nest markers inside parent {pid}'s markers (direct children of w:p, never inside w:r):
   <w:commentRangeStart w:id="{pid}"/><w:commentRangeStart w:id="{cid}"/>
   <w:r>...</w:r>
   <w:commentRangeEnd w:id="{cid}"/><w:commentRangeEnd w:id="{pid}"/>
   <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="{pid}"/></w:r>
   <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="{cid}"/></w:r>"""
 
+SMART_QUOTE_ENTITIES = {
+    "“": "&#x201C;",
+    "”": "&#x201D;",
+    "‘": "&#x2018;",
+    "’": "&#x2019;",
+}
+
 
 def _generate_hex_id() -> str:
     return f"{random.randint(0, 0x7FFFFFFE):08X}"
 
 
-SMART_QUOTE_ENTITIES = {
-    "\u201c": "&#x201C;",  
-    "\u201d": "&#x201D;",  
-    "\u2018": "&#x2018;",  
-    "\u2019": "&#x2019;",  
-}
-
-
 def _encode_smart_quotes(text: str) -> str:
     for char, entity in SMART_QUOTE_ENTITIES.items():
         text = text.replace(char, entity)
@@ -105,6 +119,19 @@ def _find_para_id(comments_path: Path, comment_id: int) -> str | None:
     return None
 
 
+def _next_comment_id(comments_path: Path) -> int:
+    if not comments_path.exists():
+        return 0
+    dom = defusedxml.minidom.parseString(comments_path.read_text(encoding="utf-8"))
+    ids = []
+    for c in dom.getElementsByTagName("w:comment"):
+        try:
+            ids.append(int(c.getAttribute("w:id")))
+        except ValueError:
+            pass
+    return (max(ids) + 1) if ids else 0
+
+
 def _get_next_rid(rels_path: Path) -> int:
     dom = defusedxml.minidom.parseString(rels_path.read_text(encoding="utf-8"))
     max_rid = 0
@@ -120,151 +147,146 @@ def _get_next_rid(rels_path: Path) -> int:
 
 def _has_relationship(rels_path: Path, target: str) -> bool:
     dom = defusedxml.minidom.parseString(rels_path.read_text(encoding="utf-8"))
-    for rel in dom.getElementsByTagName("Relationship"):
-        if rel.getAttribute("Target") == target:
-            return True
-    return False
+    return any(
+        rel.getAttribute("Target") == target
+        for rel in dom.getElementsByTagName("Relationship")
+    )
 
 
 def _has_content_type(ct_path: Path, part_name: str) -> bool:
     dom = defusedxml.minidom.parseString(ct_path.read_text(encoding="utf-8"))
-    for override in dom.getElementsByTagName("Override"):
-        if override.getAttribute("PartName") == part_name:
-            return True
-    return False
+    return any(
+        o.getAttribute("PartName") == part_name
+        for o in dom.getElementsByTagName("Override")
+    )
+
+
+_COMMENT_RELS = [
+    ("http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments", "comments.xml"),
+    ("http://schemas.microsoft.com/office/2011/relationships/commentsExtended", "commentsExtended.xml"),
+    ("http://schemas.microsoft.com/office/2016/09/relationships/commentsIds", "commentsIds.xml"),
+    ("http://schemas.microsoft.com/office/2018/08/relationships/commentsExtensible", "commentsExtensible.xml"),
+]
+_COMMENT_OVERRIDES = [
+    ("/word/comments.xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml"),
+    ("/word/commentsExtended.xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml"),
+    ("/word/commentsIds.xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml"),
+    ("/word/commentsExtensible.xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtensible+xml"),
+]
 
 
 def _ensure_comment_relationships(unpacked_dir: Path) -> None:
     rels_path = unpacked_dir / "word" / "_rels" / "document.xml.rels"
     if not rels_path.exists():
         return
-
-    if _has_relationship(rels_path, "comments.xml"):
-        return  
-
     dom = defusedxml.minidom.parseString(rels_path.read_text(encoding="utf-8"))
     root = dom.documentElement
+    comment_types = {rel_type for rel_type, _ in _COMMENT_RELS}
+    existing = set()
+    for rel in dom.getElementsByTagName("Relationship"):
+        if rel.getAttribute("Type") not in comment_types:
+            continue
+        part = opc_target(
+            rel.getAttribute("Target"),
+            "word/document.xml",
+            rel.getAttribute("TargetMode"),
+        )
+        if part is not None:
+            existing.add(part)
     next_rid = _get_next_rid(rels_path)
-
-    rels = [
-        (
-            "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments",
-            "comments.xml",
-        ),
-        (
-            "http://schemas.microsoft.com/office/2011/relationships/commentsExtended",
-            "commentsExtended.xml",
-        ),
-        (
-            "http://schemas.microsoft.com/office/2016/09/relationships/commentsIds",
-            "commentsIds.xml",
-        ),
-        (
-            "http://schemas.microsoft.com/office/2018/08/relationships/commentsExtensible",
-            "commentsExtensible.xml",
-        ),
-    ]
-
-    for rel_type, target in rels:
+    changed = False
+    for rel_type, target in _COMMENT_RELS:
+        if opc_target(target, "word/document.xml") in existing:
+            continue
         rel = dom.createElement("Relationship")
         rel.setAttribute("Id", f"rId{next_rid}")
         rel.setAttribute("Type", rel_type)
         rel.setAttribute("Target", target)
         root.appendChild(rel)  
         next_rid += 1
-
-    rels_path.write_bytes(dom.toxml(encoding="UTF-8"))
+        changed = True
+    if changed:
+        rels_path.write_bytes(dom.toxml(encoding="UTF-8"))
 
 
 def _ensure_comment_content_types(unpacked_dir: Path) -> None:
     ct_path = unpacked_dir / "[Content_Types].xml"
     if not ct_path.exists():
         return
-
-    if _has_content_type(ct_path, "/word/comments.xml"):
-        return  
-
     dom = defusedxml.minidom.parseString(ct_path.read_text(encoding="utf-8"))
     root = dom.documentElement
-
-    overrides = [
-        (
-            "/word/comments.xml",
-            "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml",
-        ),
-        (
-            "/word/commentsExtended.xml",
-            "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml",
-        ),
-        (
-            "/word/commentsIds.xml",
-            "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml",
-        ),
-        (
-            "/word/commentsExtensible.xml",
-            "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtensible+xml",
-        ),
-    ]
-
-    for part_name, content_type in overrides:
+    existing = {
+        o.getAttribute("PartName")
+        for o in dom.getElementsByTagName("Override")
+    }
+    changed = False
+    for part_name, content_type in _COMMENT_OVERRIDES:
+        if part_name in existing:
+            continue
         override = dom.createElement("Override")
         override.setAttribute("PartName", part_name)
         override.setAttribute("ContentType", content_type)
         root.appendChild(override)  
-
-    ct_path.write_bytes(dom.toxml(encoding="UTF-8"))
+        changed = True
+    if changed:
+        ct_path.write_bytes(dom.toxml(encoding="UTF-8"))
 
 
 def add_comment(
-    unpacked_dir: str,
-    comment_id: int,
+    unpacked_dir: Path | str,
     text: str,
+    comment_id: int | None = None,
     author: str = "Claude",
     initials: str = "C",
     parent_id: int | None = None,
-) -> tuple[str, str]:
-    word = Path(unpacked_dir) / "word"
+    raw: bool = False,
+) -> tuple[int, str, str]:
+    unpacked_dir = Path(unpacked_dir)
+    if not raw:
+        text = xml_escape(text)
+    author = xml_escape(author, {'"': "&quot;"})
+    initials = xml_escape(initials, {'"': "&quot;"})
+    word = unpacked_dir / "word"
     if not word.exists():
-        return "", f"Error: {word} not found"
+        raise FileNotFoundError(f"{word} not found (not an unpacked .docx?)")
+
+    comments = word / "comments.xml"
+    if comment_id is None:
+        comment_id = _next_comment_id(comments)
+
+    parent_para = None
+    if parent_id is not None:
+        parent_para = _find_para_id(comments, parent_id) if comments.exists() else None
+        if not parent_para:
+            raise ValueError(f"parent comment {parent_id} not found")
 
     para_id, durable_id = _generate_hex_id(), _generate_hex_id()
     ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
-    comments = word / "comments.xml"
-    first_comment = not comments.exists()
-    if first_comment:
+    if not comments.exists():
         shutil.copy(TEMPLATE_DIR / "comments.xml", comments)
-        _ensure_comment_relationships(Path(unpacked_dir))
-        _ensure_comment_content_types(Path(unpacked_dir))
+    _ensure_comment_relationships(unpacked_dir)
+    _ensure_comment_content_types(unpacked_dir)
     _append_xml(
         comments,
         "w:comments",
         COMMENT_XML.format(
-            id=comment_id,
-            author=author,
-            date=ts,
-            initials=initials,
-            para_id=para_id,
-            text=text,  
+            id=comment_id, author=author, date=ts, initials=initials,
+            para_id=para_id, text=text,
         ),
     )
 
     ext = word / "commentsExtended.xml"
     if not ext.exists():
         shutil.copy(TEMPLATE_DIR / "commentsExtended.xml", ext)
-    if parent_id is not None:
-        parent_para = _find_para_id(comments, parent_id)
-        if not parent_para:
-            return "", f"Error: Parent comment {parent_id} not found"
+    if parent_para is not None:
         _append_xml(
-            ext,
-            "w15:commentsEx",
+            ext, "w15:commentsEx",
             f'<w15:commentEx w15:paraId="{para_id}" w15:paraIdParent="{parent_para}" w15:done="0"/>',
         )
     else:
         _append_xml(
-            ext,
-            "w15:commentsEx",
+            ext, "w15:commentsEx",
             f'<w15:commentEx w15:paraId="{para_id}" w15:done="0"/>',
         )
 
@@ -272,8 +294,7 @@ def add_comment(
     if not ids.exists():
         shutil.copy(TEMPLATE_DIR / "commentsIds.xml", ids)
     _append_xml(
-        ids,
-        "w16cid:commentsIds",
+        ids, "w16cid:commentsIds",
         f'<w16cid:commentId w16cid:paraId="{para_id}" w16cid:durableId="{durable_id}"/>',
     )
 
@@ -281,38 +302,67 @@ def add_comment(
     if not extensible.exists():
         shutil.copy(TEMPLATE_DIR / "commentsExtensible.xml", extensible)
     _append_xml(
-        extensible,
-        "w16cex:commentsExtensible",
+        extensible, "w16cex:commentsExtensible",
         f'<w16cex:commentExtensible w16cex:durableId="{durable_id}" w16cex:dateUtc="{ts}"/>',
     )
 
     action = "reply" if parent_id is not None else "comment"
-    return para_id, f"Added {action} {comment_id} (para_id={para_id})"
+    return comment_id, para_id, f"Added {action} id={comment_id} (paraId={para_id})"
 
 
-if __name__ == "__main__":
-    p = argparse.ArgumentParser(description="Add comments to DOCX documents")
-    p.add_argument("unpacked_dir", help="Unpacked DOCX directory")
-    p.add_argument("comment_id", type=int, help="Comment ID (must be unique)")
-    p.add_argument("text", help="Comment text")
+def main() -> None:
+    p = argparse.ArgumentParser(description="Add a comment to a DOCX (directory or .docx file).")
+    p.add_argument("input", help="Unpacked DOCX directory OR a .docx/.dotx file")
+    p.add_argument("text", help="Comment text (plain text; XML-escaped automatically)")
+    p.add_argument("--raw", action="store_true",
+                   help="Treat text as pre-escaped XML (skip automatic escaping)")
+    p.add_argument("--id", type=int, dest="comment_id",
+                   help="Comment ID (default: auto-assign as max existing + 1)")
     p.add_argument("--author", default="Claude", help="Author name")
     p.add_argument("--initials", default="C", help="Author initials")
-    p.add_argument("--parent", type=int, help="Parent comment ID (for replies)")
+    p.add_argument("--parent", type=int, help="Parent comment ID (makes this a reply)")
+    p.add_argument("-o", "--output",
+                   help="Output .docx path (only used when input is a .docx; default: overwrite input)")
     args = p.parse_args()
 
-    para_id, msg = add_comment(
-        args.unpacked_dir,
-        args.comment_id,
-        args.text,
-        args.author,
-        args.initials,
-        args.parent,
-    )
-    print(msg)
-    if "Error" in msg:
+    src = Path(args.input)
+
+    try:
+        if src.is_dir():
+            if args.output:
+                print("Warning: --output ignored for directory input", file=sys.stderr)
+            cid, _, msg = add_comment(
+                src, args.text, comment_id=args.comment_id,
+                author=args.author, initials=args.initials,
+                parent_id=args.parent, raw=args.raw,
+            )
+            print(msg)
+        elif src.is_file() and src.suffix.lower() in (".docx", ".dotx"):
+            out = Path(args.output) if args.output else src
+            with tempfile.TemporaryDirectory() as tmp:
+                tmp_path = Path(tmp)
+                with zipfile.ZipFile(src) as zf:
+                    _safe_extract(zf, tmp_path)
+                cid, _, msg = add_comment(
+                    tmp_path, args.text, comment_id=args.comment_id,
+                    author=args.author, initials=args.initials,
+                    parent_id=args.parent, raw=args.raw,
+                )
+                _rezip(tmp_path, out)
+            print(msg)
+            print(f"Wrote {out} (comment defined; add markers to word/document.xml to make it visible)")
+        else:
+            print(f"Error: {src} is neither a directory nor a .docx/.dotx file", file=sys.stderr)
+            sys.exit(1)
+    except (FileNotFoundError, ValueError, zipfile.BadZipFile, ExpatError) as e:
+        print(f"Error: {e}", file=sys.stderr)
         sys.exit(1)
-    cid = args.comment_id
+
     if args.parent is not None:
         print(REPLY_MARKER_TEMPLATE.format(pid=args.parent, cid=cid))
     else:
         print(COMMENT_MARKER_TEMPLATE.format(cid=cid))
+
+
+if __name__ == "__main__":
+    main()

skills/docx/scripts/merge_runs.py

@@ -0,0 +1,310 @@
+"""Merge adjacent identically-formatted runs in a DOCX.
+
+Word fragments paragraph text across many <w:r> elements (revision ids,
+spell-check markers, editing history), which makes find-and-replace on
+word/document.xml unreliable — the string you're looking for is split
+across runs. This coalesces adjacent runs whose formatting (<w:rPr>) is
+identical, strips rsid attributes and proofErr markers, and consolidates the
+text elements — <w:t>, and <w:delText> for text inside a tracked deletion.
+
+Rendering is unchanged. The text you search is what Word draws, which is not
+always the bytes in the file: an element without xml:space="preserve" has its
+edge whitespace trimmed before it reaches the page, so `<w:t>Hello </w:t>`
+followed by `<w:t>world</w:t>` reads "Helloworld" and merges to exactly that.
+
+Runs in two different <w:ins>/<w:del> wrappers are never merged: that would
+rewrite tracked-change structure, collapsing separate revisions into one.
+
+Only word/document.xml is processed (not headers, footers, or footnotes).
+
+Usage:
+    python merge_runs.py unpacked/                  # after unzip, before editing
+    python merge_runs.py document.docx              # rewrite in place
+    python merge_runs.py document.docx -o out.docx
+"""
+
+
+import argparse
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+import defusedxml.minidom
+
+from office.helpers import XML_SPACE, rendered_text, rezip, safe_extract
+
+WORDML_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+
+def merge_runs(input_dir: str) -> tuple[int, str]:
+    doc_xml = Path(input_dir) / "word" / "document.xml"
+
+    if not doc_xml.exists():
+        return 0, f"Error: {doc_xml} not found"
+
+    try:
+        dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding="utf-8"))
+        root = dom.documentElement
+        run_names = _run_tag_names(root)
+
+        _remove_elements(root, "proofErr")
+
+        runs = _find_runs(root, run_names)
+        _strip_rsid_attrs(runs)
+
+        merge_count = 0
+        for container in {run.parentNode for run in runs}:
+            merge_count += _merge_runs_in(container, run_names)
+
+        doc_xml.write_bytes(dom.toxml(encoding="UTF-8"))
+        return merge_count, f"Merged {merge_count} runs"
+
+    except Exception as e:
+        return 0, f"Error: {e}"
+
+
+
+
+def _is_element(node, tag: str) -> bool:
+    name = node.localName or node.tagName
+    return name == tag or name.endswith(f":{tag}")
+
+
+def _run_tag_names(root) -> set[str]:
+    names = set()
+    for attr in root.attributes.values():
+        if attr.value == WORDML_NS:
+            if attr.name == "xmlns":
+                names.add("r")
+            elif attr.name.startswith("xmlns:"):
+                names.add(attr.name.split(":", 1)[1] + ":r")
+    return names or {"w:r", "r"}
+
+
+def _find_elements(root, tag: str) -> list:
+    results = []
+
+    def traverse(node):
+        if node.nodeType == node.ELEMENT_NODE:
+            if _is_element(node, tag):
+                results.append(node)
+            for child in node.childNodes:
+                traverse(child)
+
+    traverse(root)
+    return results
+
+
+def _find_runs(root, run_names: set[str]) -> list:
+    return [e for e in _find_elements(root, "r") if _is_run(e, run_names)]
+
+
+def _get_child(parent, tag: str):
+    return next(iter(_get_children(parent, tag)), None)
+
+
+def _get_children(parent, tag: str) -> list:
+    return [
+        child
+        for child in parent.childNodes
+        if child.nodeType == child.ELEMENT_NODE and _is_element(child, tag)
+    ]
+
+
+def _is_adjacent(elem1, elem2) -> bool:
+    node = elem1.nextSibling
+    while node:
+        if node == elem2:
+            return True
+        if node.nodeType == node.ELEMENT_NODE:
+            return False
+        if node.nodeType == node.TEXT_NODE and node.data.strip(XML_SPACE):
+            return False
+        node = node.nextSibling
+    return False
+
+
+
+
+def _remove_elements(root, tag: str):
+    for elem in _find_elements(root, tag):
+        if elem.parentNode:
+            elem.parentNode.removeChild(elem)
+
+
+def _strip_rsid_attrs(runs: list):
+    for run in runs:
+        for attr in list(run.attributes.values()):
+            if "rsid" in attr.name.lower():
+                run.removeAttribute(attr.name)
+
+
+
+
+def _merge_runs_in(container, run_names: set[str]) -> int:
+    merge_count = 0
+    run = _first_child_run(container, run_names)
+
+    while run:
+        while True:
+            next_elem = _next_element_sibling(run)
+            if next_elem and _is_run(next_elem, run_names) and _can_merge(run, next_elem):
+                _merge_run_content(run, next_elem)
+                container.removeChild(next_elem)
+                merge_count += 1
+            else:
+                break
+
+        _consolidate_text(run)
+        run = _next_sibling_run(run, run_names)
+
+    return merge_count
+
+
+def _first_child_run(container, run_names: set[str]):
+    for child in container.childNodes:
+        if child.nodeType == child.ELEMENT_NODE and _is_run(child, run_names):
+            return child
+    return None
+
+
+def _next_element_sibling(node):
+    sibling = node.nextSibling
+    while sibling:
+        if sibling.nodeType == sibling.ELEMENT_NODE:
+            return sibling
+        sibling = sibling.nextSibling
+    return None
+
+
+def _next_sibling_run(node, run_names: set[str]):
+    sibling = node.nextSibling
+    while sibling:
+        if sibling.nodeType == sibling.ELEMENT_NODE:
+            if _is_run(sibling, run_names):
+                return sibling
+        sibling = sibling.nextSibling
+    return None
+
+
+def _is_run(node, run_names: set[str]) -> bool:
+    return node.tagName in run_names
+
+
+def _can_merge(run1, run2) -> bool:
+    rpr1 = _get_child(run1, "rPr")
+    rpr2 = _get_child(run2, "rPr")
+
+    if (rpr1 is None) != (rpr2 is None):
+        return False
+    if rpr1 is None:
+        return True
+    return rpr1.toxml() == rpr2.toxml()  
+
+
+def _merge_run_content(target, source):
+    for child in list(source.childNodes):
+        if child.nodeType == child.ELEMENT_NODE:
+            name = child.localName or child.tagName
+            if name != "rPr" and not name.endswith(":rPr"):
+                target.appendChild(child)
+
+
+def _element_text(elem) -> str:
+    return "".join(
+        child.data
+        for child in elem.childNodes
+        if child.nodeType in (child.TEXT_NODE, child.CDATA_SECTION_NODE)
+    )
+
+
+def _has_preserve(elem) -> bool:
+    return elem.getAttribute("xml:space") == "preserve"
+
+
+def _rendered_text(elem) -> str:
+    return rendered_text(_element_text(elem), _has_preserve(elem))
+
+
+def _consolidate_text(run):
+    for tag in ("t", "delText"):
+        _consolidate_text_elements(run, tag)
+
+
+def _consolidate_text_elements(run, tag: str):
+    t_elements = _get_children(run, tag)
+
+    for i in range(len(t_elements) - 1, 0, -1):
+        curr, prev = t_elements[i], t_elements[i - 1]
+
+        if _is_adjacent(prev, curr):
+            merged = _rendered_text(prev) + _rendered_text(curr)
+            had_preserve = _has_preserve(prev) or _has_preserve(curr)
+
+            new_text = run.ownerDocument.createTextNode(merged)
+            for node in list(prev.childNodes):
+                if node.nodeType in (node.TEXT_NODE, node.CDATA_SECTION_NODE):
+                    prev.removeChild(node)
+                else:
+                    run.insertBefore(node, curr)
+            prev.appendChild(new_text)
+            for node in list(curr.childNodes):
+                if node.nodeType not in (node.TEXT_NODE, node.CDATA_SECTION_NODE):
+                    run.insertBefore(node, curr)
+
+            if merged != merged.strip(XML_SPACE) or had_preserve:
+                prev.setAttribute("xml:space", "preserve")
+            elif prev.hasAttribute("xml:space"):
+                prev.removeAttribute("xml:space")
+
+            run.removeChild(curr)
+
+
+
+
+def _merge_or_die(path: Path) -> str:
+    _, msg = merge_runs(str(path))
+    if msg.startswith("Error"):
+        print(msg, file=sys.stderr)
+        sys.exit(1)
+    return msg
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(
+        description="Merge adjacent identically-formatted runs in a DOCX (directory or .docx file)."
+    )
+    p.add_argument("input", help="Unpacked DOCX directory OR a .docx/.dotx file")
+    p.add_argument(
+        "-o", "--output",
+        help="Output .docx path (only valid when input is a .docx; default: overwrite input)",
+    )
+    args = p.parse_args()
+
+    src = Path(args.input)
+
+    try:
+        if src.is_dir():
+            if args.output:
+                p.error("--output is only valid for .docx input; directory input is modified in place")
+            print(_merge_or_die(src))
+        elif src.is_file() and src.suffix.lower() in (".docx", ".dotx"):
+            out = Path(args.output) if args.output else src
+            with tempfile.TemporaryDirectory() as tmp:
+                tmp_path = Path(tmp)
+                with zipfile.ZipFile(src) as zf:
+                    safe_extract(zf, tmp_path)
+                msg = _merge_or_die(tmp_path)
+                rezip(tmp_path, out)
+            print(f"{msg}; wrote {out}")
+        else:
+            print(f"Error: {src} is neither a directory nor a .docx/.dotx file", file=sys.stderr)
+            sys.exit(1)
+    except (OSError, ValueError, zipfile.BadZipFile) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

skills/docx/scripts/office/helpers/__init__.py

@@ -0,0 +1,111 @@
+import os
+import posixpath
+import re
+import stat
+import tempfile
+import urllib.parse
+import zipfile
+from pathlib import Path
+
+OOXML_FAMILY = {
+    ".docx": "docx",
+    ".dotx": "docx",
+    ".pptx": "pptx",
+    ".potx": "pptx",
+    ".xlsx": "xlsx",
+    ".xltx": "xlsx",
+}
+
+_SCHEME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.\-]*:")
+
+SLIDE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide"
+
+
+def opc_target(target: str, source_part: str, target_mode: str = "") -> str | None:
+    if not target:
+        return None
+    if target_mode.lower() == "external":
+        return None
+    if _SCHEME_RE.match(target):
+        return None
+
+    target = urllib.parse.unquote(target)
+
+    if "\\" in target:
+        raise ValueError(f"relationship target is not a POSIX part name: {target!r}")
+
+    if target.startswith("/"):
+        joined = target.lstrip("/")
+    else:
+        joined = posixpath.join(posixpath.dirname(source_part), target)
+
+    parts: list[str] = []
+    for segment in posixpath.normpath(joined).split("/"):
+        if segment in ("", "."):
+            continue
+        if segment == "..":
+            if not parts:
+                raise ValueError(f"relationship target escapes the package: {target!r}")
+            parts.pop()
+        else:
+            parts.append(segment)
+
+    if not parts:
+        raise ValueError(f"relationship target resolves to nothing: {target!r}")
+    return "/".join(parts)
+
+
+def rels_source_part(rels_file: Path, unpacked_dir: Path) -> str:
+    owner_dir = rels_file.parent.parent.relative_to(unpacked_dir)
+    return posixpath.join(owner_dir.as_posix(), rels_file.name[: -len(".rels")]).lstrip("./")
+
+
+def part_text(data: bytes) -> str:
+    return data.decode("utf-8", "surrogateescape")
+
+
+XML_SPACE = " \t\r\n"
+
+
+def rendered_text(text: str, preserve: bool) -> str:
+    return text if preserve else text.strip(XML_SPACE)
+
+
+def safe_extract(zf: zipfile.ZipFile, dest: Path) -> None:
+    dest = dest.resolve()
+    for m in zf.infolist():
+        if stat.S_ISLNK(m.external_attr >> 16):
+            raise ValueError(f"symlink archive entry not allowed: {m.filename!r}")
+        target = (dest / m.filename).resolve()
+        if not target.is_relative_to(dest):
+            raise ValueError(f"unsafe archive entry: {m.filename!r}")
+        zf.extract(m, dest)
+
+
+def rezip(src_dir: Path, out_path: Path) -> None:
+    files = sorted(p for p in src_dir.rglob("*") if p.is_file())
+    ct = src_dir / "[Content_Types].xml"
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=out_path.name + ".", suffix=".tmp", dir=out_path.parent
+    )
+    tmp_out = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            with zipfile.ZipFile(fh, "w", zipfile.ZIP_DEFLATED) as zf:
+                if ct.exists():
+                    zf.write(ct, ct.relative_to(src_dir), compress_type=zipfile.ZIP_STORED)
+                for f in files:
+                    if f == ct:
+                        continue
+                    zf.write(f, f.relative_to(src_dir))
+        if out_path.exists():
+            mode = out_path.stat().st_mode & 0o777
+        else:
+            umask = os.umask(0)
+            os.umask(umask)
+            mode = 0o666 & ~umask
+        os.chmod(tmp_out, mode)
+        os.replace(tmp_out, out_path)
+    finally:
+        if tmp_out.exists():
+            tmp_out.unlink()

skills/docx/scripts/office/helpers/merge_runs.py

@@ -1,199 +0,0 @@
-"""Merge adjacent runs with identical formatting in DOCX.
-
-Merges adjacent <w:r> elements that have identical <w:rPr> properties.
-Works on runs in paragraphs and inside tracked changes (<w:ins>, <w:del>).
-
-Also:
-- Removes rsid attributes from runs (revision metadata that doesn't affect rendering)
-- Removes proofErr elements (spell/grammar markers that block merging)
-"""
-
-from pathlib import Path
-
-import defusedxml.minidom
-
-
-def merge_runs(input_dir: str) -> tuple[int, str]:
-    doc_xml = Path(input_dir) / "word" / "document.xml"
-
-    if not doc_xml.exists():
-        return 0, f"Error: {doc_xml} not found"
-
-    try:
-        dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding="utf-8"))
-        root = dom.documentElement
-
-        _remove_elements(root, "proofErr")
-        _strip_run_rsid_attrs(root)
-
-        containers = {run.parentNode for run in _find_elements(root, "r")}
-
-        merge_count = 0
-        for container in containers:
-            merge_count += _merge_runs_in(container)
-
-        doc_xml.write_bytes(dom.toxml(encoding="UTF-8"))
-        return merge_count, f"Merged {merge_count} runs"
-
-    except Exception as e:
-        return 0, f"Error: {e}"
-
-
-
-
-def _find_elements(root, tag: str) -> list:
-    results = []
-
-    def traverse(node):
-        if node.nodeType == node.ELEMENT_NODE:
-            name = node.localName or node.tagName
-            if name == tag or name.endswith(f":{tag}"):
-                results.append(node)
-            for child in node.childNodes:
-                traverse(child)
-
-    traverse(root)
-    return results
-
-
-def _get_child(parent, tag: str):
-    for child in parent.childNodes:
-        if child.nodeType == child.ELEMENT_NODE:
-            name = child.localName or child.tagName
-            if name == tag or name.endswith(f":{tag}"):
-                return child
-    return None
-
-
-def _get_children(parent, tag: str) -> list:
-    results = []
-    for child in parent.childNodes:
-        if child.nodeType == child.ELEMENT_NODE:
-            name = child.localName or child.tagName
-            if name == tag or name.endswith(f":{tag}"):
-                results.append(child)
-    return results
-
-
-def _is_adjacent(elem1, elem2) -> bool:
-    node = elem1.nextSibling
-    while node:
-        if node == elem2:
-            return True
-        if node.nodeType == node.ELEMENT_NODE:
-            return False
-        if node.nodeType == node.TEXT_NODE and node.data.strip():
-            return False
-        node = node.nextSibling
-    return False
-
-
-
-
-def _remove_elements(root, tag: str):
-    for elem in _find_elements(root, tag):
-        if elem.parentNode:
-            elem.parentNode.removeChild(elem)
-
-
-def _strip_run_rsid_attrs(root):
-    for run in _find_elements(root, "r"):
-        for attr in list(run.attributes.values()):
-            if "rsid" in attr.name.lower():
-                run.removeAttribute(attr.name)
-
-
-
-
-def _merge_runs_in(container) -> int:
-    merge_count = 0
-    run = _first_child_run(container)
-
-    while run:
-        while True:
-            next_elem = _next_element_sibling(run)
-            if next_elem and _is_run(next_elem) and _can_merge(run, next_elem):
-                _merge_run_content(run, next_elem)
-                container.removeChild(next_elem)
-                merge_count += 1
-            else:
-                break
-
-        _consolidate_text(run)
-        run = _next_sibling_run(run)
-
-    return merge_count
-
-
-def _first_child_run(container):
-    for child in container.childNodes:
-        if child.nodeType == child.ELEMENT_NODE and _is_run(child):
-            return child
-    return None
-
-
-def _next_element_sibling(node):
-    sibling = node.nextSibling
-    while sibling:
-        if sibling.nodeType == sibling.ELEMENT_NODE:
-            return sibling
-        sibling = sibling.nextSibling
-    return None
-
-
-def _next_sibling_run(node):
-    sibling = node.nextSibling
-    while sibling:
-        if sibling.nodeType == sibling.ELEMENT_NODE:
-            if _is_run(sibling):
-                return sibling
-        sibling = sibling.nextSibling
-    return None
-
-
-def _is_run(node) -> bool:
-    name = node.localName or node.tagName
-    return name == "r" or name.endswith(":r")
-
-
-def _can_merge(run1, run2) -> bool:
-    rpr1 = _get_child(run1, "rPr")
-    rpr2 = _get_child(run2, "rPr")
-
-    if (rpr1 is None) != (rpr2 is None):
-        return False
-    if rpr1 is None:
-        return True
-    return rpr1.toxml() == rpr2.toxml()  
-
-
-def _merge_run_content(target, source):
-    for child in list(source.childNodes):
-        if child.nodeType == child.ELEMENT_NODE:
-            name = child.localName or child.tagName
-            if name != "rPr" and not name.endswith(":rPr"):
-                target.appendChild(child)
-
-
-def _consolidate_text(run):
-    t_elements = _get_children(run, "t")
-
-    for i in range(len(t_elements) - 1, 0, -1):
-        curr, prev = t_elements[i], t_elements[i - 1]
-
-        if _is_adjacent(prev, curr):
-            prev_text = prev.firstChild.data if prev.firstChild else ""
-            curr_text = curr.firstChild.data if curr.firstChild else ""
-            merged = prev_text + curr_text
-
-            if prev.firstChild:
-                prev.firstChild.data = merged
-            else:
-                prev.appendChild(run.ownerDocument.createTextNode(merged))
-
-            if merged.startswith(" ") or merged.endswith(" "):
-                prev.setAttribute("xml:space", "preserve")
-            elif prev.hasAttribute("xml:space"):
-                prev.removeAttribute("xml:space")
-
-            run.removeChild(curr)

skills/docx/scripts/office/helpers/pptx_chart.py

@@ -0,0 +1,170 @@
+"""Find chart XML that PowerPoint refuses but the schema accepts.
+
+Detection only: for either fault more than one repair is valid, and only the
+author knows which was meant.
+"""
+
+
+from __future__ import annotations
+
+import re
+from typing import Mapping
+
+from . import part_text
+
+
+_CHART_PART_RE = re.compile(r"ppt/charts/chart\d+\.xml")
+
+_GROUPING_RE = re.compile(r"""<c:grouping\b[^>]*?\bval=["'](\w+)["']""")
+_DLBL_POS_RE = re.compile(r"""<c:dLblPos\b[^>]*?\bval=["'](\w+)["']""")
+
+def _strip_ext_lst(text: str) -> str:
+    out, cursor = [], 0
+    for lo, hi in _ext_lst_spans(text):
+        out.append(text[cursor:lo])
+        cursor = hi
+    out.append(text[cursor:])
+    return "".join(out)
+
+_BAR_GROUP_RE = re.compile(r"<c:(bar3DChart|barChart)\b[^>]*(?<!/)>.*?</c:\1\s*>", re.DOTALL)
+
+STACKED_GROUPINGS = frozenset({"stacked", "percentStacked"})
+ILLEGAL_ON_STACKED = frozenset({"outEnd"})
+LEGAL_ON_STACKED = ("ctr", "inEnd", "inBase")
+
+
+def _check_stacked_label_positions(part: str, xml: str) -> list[str]:
+    problems: list[str] = []
+    for match in _BAR_GROUP_RE.finditer(xml):
+        block = _strip_ext_lst(match.group(0))
+        group = match.group(1)
+
+        grouping = _GROUPING_RE.search(block)
+        if grouping is None or grouping.group(1) not in STACKED_GROUPINGS:
+            continue
+
+        bad = [p for p in _DLBL_POS_RE.findall(block) if p in ILLEGAL_ON_STACKED]
+        for pos in sorted(set(bad)):
+            problems.append(
+                f'{part}: {bad.count(pos)} data label(s) use dLblPos="{pos}" on a '
+                f"{grouping.group(1)} {group}; PowerPoint allows only "
+                f"{', '.join(LEGAL_ON_STACKED)} there"
+            )
+    return problems
+
+
+
+_ANY_CHART_GROUP_RE = re.compile(r"<c:(\w+Chart)\b[^>]*(?<!/)>.*?</c:\1\s*>", re.DOTALL)
+
+_AXID_RE = re.compile(
+    r"""\s*<c:axId\b[^>]*?\bval=["'](-?\d+)["']\s*(?:/>|>\s*</c:axId\s*>)"""
+)
+
+_AXIS_DECL_RE = re.compile(
+    r"""<c:(catAx|valAx|serAx|dateAx)\b[^>]*(?<!/)>\s*<c:axId\b[^>]*?\bval=["'](-?\d+)["']"""
+)
+
+AXID_LIMIT = {
+    "barChart": 2, "lineChart": 2, "areaChart": 2, "scatterChart": 2,
+    "bubbleChart": 2, "radarChart": 2, "stockChart": 2,
+    "bar3DChart": 3, "line3DChart": 3, "area3DChart": 3,
+    "surfaceChart": 3, "surface3DChart": 3,
+}
+
+AXID_MINIMUM = {
+    "barChart": 2, "lineChart": 2, "areaChart": 2, "scatterChart": 2,
+    "bubbleChart": 2, "radarChart": 2, "stockChart": 2,
+    "bar3DChart": 2, "area3DChart": 2, "surfaceChart": 2,
+    "line3DChart": 3, "surface3DChart": 3,
+}
+
+
+def _declared_axes(xml: str) -> dict[str, list[str]]:
+    axes: dict[str, list[str]] = {}
+    for kind, axid in _AXIS_DECL_RE.findall(xml):
+        axes.setdefault(kind, []).append(axid)
+    return axes
+
+
+def _canonical_ids(axes: dict[str, list[str]], limit: int) -> list[str] | None:
+    category = axes.get("catAx", []) + axes.get("dateAx", [])
+    value = axes.get("valAx", [])
+    series = axes.get("serAx", [])
+    if len(category) != 1 or len(value) != 1 or len(series) > 1:
+        return None
+    ids = [category[0], value[0]]
+    if limit >= 3 and series:
+        ids.append(series[0])
+    return ids
+
+
+def _undeclared_axes(kind: str, block: str, axes: dict[str, list[str]]) -> list[str] | None:
+    if kind not in AXID_LIMIT:
+        return None
+    ids = _AXID_RE.findall(block)
+    declared = {i for group in axes.values() for i in group}
+    if len([i for i in ids if i in declared]) >= 2:
+        return None
+    return ids
+
+
+def _check_chart_axis_references(part: str, xml: str) -> list[str]:
+    axes = _declared_axes(xml)
+    problems: list[str] = []
+    declared = {i for group in axes.values() for i in group}
+    for match in _ANY_CHART_GROUP_RE.finditer(xml):
+        kind, block = match.group(1), match.group(0)
+        ids = _undeclared_axes(kind, block, axes)
+        if ids is None:
+            continue
+        if not ids:
+            problems.append(
+                f"{part}: <c:{kind}> declares no <c:axId> this part can resolve; a chart "
+                f"group needs {AXID_MINIMUM[kind]}, and PowerPoint discards one with fewer"
+            )
+            continue
+        dead = [i for i in ids if i not in declared]
+        canonical = _canonical_ids(axes, AXID_LIMIT[kind])
+        if canonical is not None and len(canonical) >= AXID_MINIMUM[kind]:
+            hint = f"Fix: point them at the axes this part declares ({', '.join(canonical)})"
+        else:
+            hint = ("Fix: the part declares several axes of a kind -- declare the "
+                    "secondary axes the series expects, or drop them")
+        detail = (f"of which {', '.join(dead)} name no declared axis"
+                  if dead else f"only {len(ids)} of which this part declares")
+        problems.append(
+            f"{part}: <c:{kind}> references axId {', '.join(ids)}, {detail}, "
+            f"leaving fewer than two live axes; PowerPoint discards the chart. {hint}"
+        )
+    return problems
+
+
+def _ext_lst_spans(text: str) -> list[tuple[int, int]]:
+    spans: list[tuple[int, int]] = []
+    depth = 0
+    start = 0
+    for match in re.finditer(r"<(/?)c:extLst\b[^>]*?(/?)>", text):
+        closing, self_closing = match.group(1), match.group(2)
+        if self_closing:
+            continue
+        if closing:
+            depth -= 1
+            if depth == 0:
+                spans.append((start, match.end()))
+        else:
+            if depth == 0:
+                start = match.start()
+            depth += 1
+    return spans
+
+
+CHART_CHECKS = (_check_stacked_label_positions, _check_chart_axis_references)
+
+
+def find_chart_problems(files: Mapping[str, bytes]) -> list[str]:
+    problems: list[str] = []
+    for part in sorted(n for n in files if _CHART_PART_RE.fullmatch(n)):
+        xml = part_text(files[part])
+        for check in CHART_CHECKS:
+            problems.extend(check(part, xml))
+    return problems

skills/docx/scripts/office/helpers/pptx_slide.py

@@ -0,0 +1,60 @@
+"""Pick the slide-XML schema errors PowerPoint refuses the file over.
+
+A denylist over lxml's messages, so an unrecognised error class is a miss rather
+than a false alarm.
+"""
+
+
+from __future__ import annotations
+
+import re
+
+SLIDE_PART_RE = re.compile(
+    r"ppt/(slides|slideLayouts|slideMasters|notesSlides|notesMasters|handoutMasters)"
+    r"/[^/]+\.xml"
+)
+
+FATAL_SLIDE_ERRORS: tuple[tuple[re.Pattern[str], str], ...] = (
+    (
+        re.compile(r"\}tableStyleId': This element is not expected"),
+        "two <a:tableStyleId> in one <a:tblPr> (the schema allows one)",
+    ),
+    (
+        re.compile(r"\}srgbClr', attribute 'val'"),
+        "a colour that is not six hex digits",
+    ),
+    (
+        re.compile(r"\}txBody': Missing child element"),
+        "a <p:txBody> with no children",
+    ),
+    (
+        re.compile(r"\}miter', attribute 'lim'"),
+        'a line join with lim="NaN"',
+    ),
+    (
+        re.compile(r"\}uLnTx': This element is not expected"),
+        "<a:uLnTx> in a position the schema forbids",
+    ),
+    (
+        re.compile(r"\}overrideClrMapping': This element is not expected"),
+        "<p:overrideClrMapping> in a position the schema forbids",
+    ),
+    (
+        re.compile(r"\}nvGrpSpPr': Missing child element"),
+        "a <p:nvGrpSpPr> with no children",
+    ),
+)
+
+
+def is_schema_verdict(error: str) -> bool:
+    return error.startswith("Element ")
+
+
+def fatal_slide_errors(errors: set[str]) -> list[str]:
+    out = []
+    for error in sorted(errors):
+        for pattern, meaning in FATAL_SLIDE_ERRORS:
+            if pattern.search(error):
+                out.append(f"{meaning}: {error}")
+                break
+    return out

skills/docx/scripts/office/helpers/pptx_theme.py

@@ -0,0 +1,114 @@
+"""Find masters sharing a theme part in the way PowerPoint refuses to open.
+
+Reports only; the fix is to move <p:notesMasterIdLst> back to directly after
+<p:sldIdLst> in ppt/presentation.xml.
+"""
+
+
+from __future__ import annotations
+
+import posixpath
+import re
+from typing import Mapping
+
+from . import part_text
+
+THEME_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme"
+
+_MASTER_RE = re.compile(
+    r"^ppt/(?P<group>slideMasters|notesMasters|handoutMasters)/"
+    r"(?:slide|notes|handout)Master(?P<num>\d+)\.xml$"
+)
+_GROUP_ORDER = {"slideMasters": 0, "notesMasters": 1, "handoutMasters": 2}
+
+_RELATIONSHIP_RE = re.compile(
+    r"<Relationship\b[^>]*?(?:/>|>.*?</Relationship\s*>)", re.DOTALL
+)
+
+
+def _sort_key(name: str) -> tuple[int, int]:
+    m = _MASTER_RE.match(name)
+    assert m is not None
+    return (_GROUP_ORDER[m.group("group")], int(m.group("num")))
+
+
+def _rels_path(part: str) -> str:
+    directory, base = posixpath.split(part)
+    return f"{directory}/_rels/{base}.rels"
+
+
+def _resolve(rels_path: str, target: str) -> str:
+    if target.startswith("/"):
+        return target.lstrip("/")
+    part_dir = posixpath.dirname(posixpath.dirname(rels_path))
+    return posixpath.normpath(posixpath.join(part_dir, target))
+
+
+def _theme_rel(files: Mapping[str, bytes], master: str):
+    rels_path = _rels_path(master)
+    rels = files.get(rels_path)
+    if rels is None:
+        return None
+    for element in _RELATIONSHIP_RE.findall(part_text(rels)):
+        if f'Type="{THEME_REL_TYPE}"' not in element:
+            continue
+        target = re.search(r'\bTarget="([^"]+)"', element)
+        if target is None:
+            continue
+        return rels_path, element, _resolve(rels_path, target.group(1))
+    return None
+
+
+def _masters(files: Mapping[str, bytes]) -> list[str]:
+    return sorted((n for n in files if _MASTER_RE.match(n)), key=_sort_key)
+
+
+_PRESENTATION = "ppt/presentation.xml"
+_NOTES_MASTERS = "ppt/notesMasters/"
+_IGNORABLE_RE = re.compile(r"<!--.*?-->|<\?.*?\?>", re.DOTALL)
+_AFTER_SLDIDLST_RE = re.compile(
+    r"<p:sldIdLst\b(?:[^>]*/>|[^>]*>.*?</p:sldIdLst\s*>)\s*(<[^>\s/]+)", re.DOTALL
+)
+
+
+def _notes_master_share_is_inert(files: Mapping[str, bytes]) -> bool:
+    data = files.get(_PRESENTATION)
+    if data is None:
+        return False
+    match = _AFTER_SLDIDLST_RE.search(_IGNORABLE_RE.sub("", part_text(data)))
+    return match is not None and match.group(1) == "<p:notesMasterIdLst"
+
+
+def _shares(files: Mapping[str, bytes]):
+    owner: dict[str, str] = {}
+    for master in _masters(files):
+        found = _theme_rel(files, master)
+        if found is None:
+            continue
+        rels_path, element, theme = found
+        if theme not in files:
+            continue  
+        if theme in owner:
+            yield master, rels_path, element, theme, owner[theme]
+        else:
+            owner[theme] = master
+
+
+def _is_inert(master: str, inert_notes: bool) -> bool:
+    return inert_notes and master.startswith(_NOTES_MASTERS)
+
+
+def find_shared_master_themes(files: Mapping[str, bytes]) -> list[str]:
+    return [
+        f"{master} shares {theme} with {first}"
+        for master, _, _, theme, first in _shares(files)
+    ]
+
+
+def live_shared_master_themes(files: Mapping[str, bytes]) -> list[str]:
+    inert_notes = _notes_master_share_is_inert(files)
+    return [
+        f"{master} shares {theme} with {first}"
+        for master, _, _, theme, first in _shares(files)
+        if not _is_inert(master, inert_notes)
+    ]

skills/docx/scripts/office/helpers/simplify_redlines.py

@@ -1,197 +0,0 @@
-"""Simplify tracked changes by merging adjacent w:ins or w:del elements.
-
-Merges adjacent <w:ins> elements from the same author into a single element.
-Same for <w:del> elements. This makes heavily-redlined documents easier to
-work with by reducing the number of tracked change wrappers.
-
-Rules:
-- Only merges w:ins with w:ins, w:del with w:del (same element type)
-- Only merges if same author (ignores timestamp differences)
-- Only merges if truly adjacent (only whitespace between them)
-"""
-
-import xml.etree.ElementTree as ET
-import zipfile
-from pathlib import Path
-
-import defusedxml.minidom
-
-WORD_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
-
-
-def simplify_redlines(input_dir: str) -> tuple[int, str]:
-    doc_xml = Path(input_dir) / "word" / "document.xml"
-
-    if not doc_xml.exists():
-        return 0, f"Error: {doc_xml} not found"
-
-    try:
-        dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding="utf-8"))
-        root = dom.documentElement
-
-        merge_count = 0
-
-        containers = _find_elements(root, "p") + _find_elements(root, "tc")
-
-        for container in containers:
-            merge_count += _merge_tracked_changes_in(container, "ins")
-            merge_count += _merge_tracked_changes_in(container, "del")
-
-        doc_xml.write_bytes(dom.toxml(encoding="UTF-8"))
-        return merge_count, f"Simplified {merge_count} tracked changes"
-
-    except Exception as e:
-        return 0, f"Error: {e}"
-
-
-def _merge_tracked_changes_in(container, tag: str) -> int:
-    merge_count = 0
-
-    tracked = [
-        child
-        for child in container.childNodes
-        if child.nodeType == child.ELEMENT_NODE and _is_element(child, tag)
-    ]
-
-    if len(tracked) < 2:
-        return 0
-
-    i = 0
-    while i < len(tracked) - 1:
-        curr = tracked[i]
-        next_elem = tracked[i + 1]
-
-        if _can_merge_tracked(curr, next_elem):
-            _merge_tracked_content(curr, next_elem)
-            container.removeChild(next_elem)
-            tracked.pop(i + 1)
-            merge_count += 1
-        else:
-            i += 1
-
-    return merge_count
-
-
-def _is_element(node, tag: str) -> bool:
-    name = node.localName or node.tagName
-    return name == tag or name.endswith(f":{tag}")
-
-
-def _get_author(elem) -> str:
-    author = elem.getAttribute("w:author")
-    if not author:
-        for attr in elem.attributes.values():
-            if attr.localName == "author" or attr.name.endswith(":author"):
-                return attr.value
-    return author
-
-
-def _can_merge_tracked(elem1, elem2) -> bool:
-    if _get_author(elem1) != _get_author(elem2):
-        return False
-
-    node = elem1.nextSibling
-    while node and node != elem2:
-        if node.nodeType == node.ELEMENT_NODE:
-            return False
-        if node.nodeType == node.TEXT_NODE and node.data.strip():
-            return False
-        node = node.nextSibling
-
-    return True
-
-
-def _merge_tracked_content(target, source):
-    while source.firstChild:
-        child = source.firstChild
-        source.removeChild(child)
-        target.appendChild(child)
-
-
-def _find_elements(root, tag: str) -> list:
-    results = []
-
-    def traverse(node):
-        if node.nodeType == node.ELEMENT_NODE:
-            name = node.localName or node.tagName
-            if name == tag or name.endswith(f":{tag}"):
-                results.append(node)
-            for child in node.childNodes:
-                traverse(child)
-
-    traverse(root)
-    return results
-
-
-def get_tracked_change_authors(doc_xml_path: Path) -> dict[str, int]:
-    if not doc_xml_path.exists():
-        return {}
-
-    try:
-        tree = ET.parse(doc_xml_path)
-        root = tree.getroot()
-    except ET.ParseError:
-        return {}
-
-    namespaces = {"w": WORD_NS}
-    author_attr = f"{{{WORD_NS}}}author"
-
-    authors: dict[str, int] = {}
-    for tag in ["ins", "del"]:
-        for elem in root.findall(f".//w:{tag}", namespaces):
-            author = elem.get(author_attr)
-            if author:
-                authors[author] = authors.get(author, 0) + 1
-
-    return authors
-
-
-def _get_authors_from_docx(docx_path: Path) -> dict[str, int]:
-    try:
-        with zipfile.ZipFile(docx_path, "r") as zf:
-            if "word/document.xml" not in zf.namelist():
-                return {}
-            with zf.open("word/document.xml") as f:
-                tree = ET.parse(f)
-                root = tree.getroot()
-
-                namespaces = {"w": WORD_NS}
-                author_attr = f"{{{WORD_NS}}}author"
-
-                authors: dict[str, int] = {}
-                for tag in ["ins", "del"]:
-                    for elem in root.findall(f".//w:{tag}", namespaces):
-                        author = elem.get(author_attr)
-                        if author:
-                            authors[author] = authors.get(author, 0) + 1
-                return authors
-    except (zipfile.BadZipFile, ET.ParseError):
-        return {}
-
-
-def infer_author(modified_dir: Path, original_docx: Path, default: str = "Claude") -> str:
-    modified_xml = modified_dir / "word" / "document.xml"
-    modified_authors = get_tracked_change_authors(modified_xml)
-
-    if not modified_authors:
-        return default
-
-    original_authors = _get_authors_from_docx(original_docx)
-
-    new_changes: dict[str, int] = {}
-    for author, count in modified_authors.items():
-        original_count = original_authors.get(author, 0)
-        diff = count - original_count
-        if diff > 0:
-            new_changes[author] = diff
-
-    if not new_changes:
-        return default
-
-    if len(new_changes) == 1:
-        return next(iter(new_changes))
-
-    raise ValueError(
-        f"Multiple authors added new changes: {new_changes}. "
-        "Cannot infer which author to validate."
-    )

skills/docx/scripts/office/pack.py

@@ -1,159 +0,0 @@
-"""Pack a directory into a DOCX, PPTX, or XLSX file.
-
-Validates with auto-repair, condenses XML formatting, and creates the Office file.
-
-Usage:
-    python pack.py <input_directory> <output_file> [--original <file>] [--validate true|false]
-
-Examples:
-    python pack.py unpacked/ output.docx --original input.docx
-    python pack.py unpacked/ output.pptx --validate false
-"""
-
-import argparse
-import sys
-import shutil
-import tempfile
-import zipfile
-from pathlib import Path
-
-import defusedxml.minidom
-
-from validators import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator
-
-def pack(
-    input_directory: str,
-    output_file: str,
-    original_file: str | None = None,
-    validate: bool = True,
-    infer_author_func=None,
-) -> tuple[None, str]:
-    input_dir = Path(input_directory)
-    output_path = Path(output_file)
-    suffix = output_path.suffix.lower()
-
-    if not input_dir.is_dir():
-        return None, f"Error: {input_dir} is not a directory"
-
-    if suffix not in {".docx", ".pptx", ".xlsx"}:
-        return None, f"Error: {output_file} must be a .docx, .pptx, or .xlsx file"
-
-    if validate and original_file:
-        original_path = Path(original_file)
-        if original_path.exists():
-            success, output = _run_validation(
-                input_dir, original_path, suffix, infer_author_func
-            )
-            if output:
-                print(output)
-            if not success:
-                return None, f"Error: Validation failed for {input_dir}"
-
-    with tempfile.TemporaryDirectory() as temp_dir:
-        temp_content_dir = Path(temp_dir) / "content"
-        shutil.copytree(input_dir, temp_content_dir)
-
-        for pattern in ["*.xml", "*.rels"]:
-            for xml_file in temp_content_dir.rglob(pattern):
-                _condense_xml(xml_file)
-
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-        with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zf:
-            for f in temp_content_dir.rglob("*"):
-                if f.is_file():
-                    zf.write(f, f.relative_to(temp_content_dir))
-
-    return None, f"Successfully packed {input_dir} to {output_file}"
-
-
-def _run_validation(
-    unpacked_dir: Path,
-    original_file: Path,
-    suffix: str,
-    infer_author_func=None,
-) -> tuple[bool, str | None]:
-    output_lines = []
-    validators = []
-
-    if suffix == ".docx":
-        author = "Claude"
-        if infer_author_func:
-            try:
-                author = infer_author_func(unpacked_dir, original_file)
-            except ValueError as e:
-                print(f"Warning: {e} Using default author 'Claude'.", file=sys.stderr)
-
-        validators = [
-            DOCXSchemaValidator(unpacked_dir, original_file),
-            RedliningValidator(unpacked_dir, original_file, author=author),
-        ]
-    elif suffix == ".pptx":
-        validators = [PPTXSchemaValidator(unpacked_dir, original_file)]
-
-    if not validators:
-        return True, None
-
-    total_repairs = sum(v.repair() for v in validators)
-    if total_repairs:
-        output_lines.append(f"Auto-repaired {total_repairs} issue(s)")
-
-    success = all(v.validate() for v in validators)
-
-    if success:
-        output_lines.append("All validations PASSED!")
-
-    return success, "\n".join(output_lines) if output_lines else None
-
-
-def _condense_xml(xml_file: Path) -> None:
-    try:
-        with open(xml_file, encoding="utf-8") as f:
-            dom = defusedxml.minidom.parse(f)
-
-        for element in dom.getElementsByTagName("*"):
-            if element.tagName.endswith(":t"):
-                continue
-
-            for child in list(element.childNodes):
-                if (
-                    child.nodeType == child.TEXT_NODE
-                    and child.nodeValue
-                    and child.nodeValue.strip() == ""
-                ) or child.nodeType == child.COMMENT_NODE:
-                    element.removeChild(child)
-
-        xml_file.write_bytes(dom.toxml(encoding="UTF-8"))
-    except Exception as e:
-        print(f"ERROR: Failed to parse {xml_file.name}: {e}", file=sys.stderr)
-        raise
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser(
-        description="Pack a directory into a DOCX, PPTX, or XLSX file"
-    )
-    parser.add_argument("input_directory", help="Unpacked Office document directory")
-    parser.add_argument("output_file", help="Output Office file (.docx/.pptx/.xlsx)")
-    parser.add_argument(
-        "--original",
-        help="Original file for validation comparison",
-    )
-    parser.add_argument(
-        "--validate",
-        type=lambda x: x.lower() == "true",
-        default=True,
-        metavar="true|false",
-        help="Run validation with auto-repair (default: true)",
-    )
-    args = parser.parse_args()
-
-    _, message = pack(
-        args.input_directory,
-        args.output_file,
-        original_file=args.original,
-        validate=args.validate,
-    )
-    print(message)
-
-    if "Error" in message:
-        sys.exit(1)

skills/docx/scripts/office/soffice.py

@@ -4,20 +4,23 @@ sockets may be blocked (e.g., sandboxed VMs).  Detects the restriction
 at runtime and applies an LD_PRELOAD shim if needed.
 
 Usage:
-    from office.soffice import run_soffice, get_soffice_env
+    from office.soffice import run_soffice
 
-    # Option 1 – run soffice directly
     result = run_soffice(["--headless", "--convert-to", "pdf", "input.docx"])
 
-    # Option 2 – get env dict for your own subprocess calls
-    env = get_soffice_env()
-    subprocess.run(["soffice", ...], env=env)
+Call soffice through run_soffice, not through subprocess with get_soffice_env():
+the env dict carries the shim but names no user profile, and a non-root sandbox
+cannot bootstrap the default one -- soffice aborts with "User installation could
+not be completed" and converts nothing. get_soffice_env() stays public for the
+callers that build their own argv (they must pass -env:UserInstallation too).
 """
 
+import contextlib
 import os
 import socket
 import subprocess
 import tempfile
+from collections.abc import Iterable
 from pathlib import Path
 
 
@@ -32,9 +35,15 @@ def get_soffice_env() -> dict:
     return env
 
 
-def run_soffice(args: list[str], **kwargs) -> subprocess.CompletedProcess:
-    env = get_soffice_env()
-    return subprocess.run(["soffice"] + args, env=env, **kwargs)
+def run_soffice(args: Iterable[str], **kwargs) -> subprocess.CompletedProcess:
+    args = list(args)
+    with contextlib.ExitStack() as stack:
+        if not any(str(a).startswith("-env:UserInstallation") for a in args):
+            profile = stack.enter_context(
+                tempfile.TemporaryDirectory(prefix="lo_profile_", ignore_cleanup_errors=True)
+            )
+            args = [f"-env:UserInstallation={Path(profile).as_uri()}"] + args
+        return subprocess.run(["soffice"] + args, env=get_soffice_env(), **kwargs)
 
 
 

skills/docx/scripts/office/unpack.py

@@ -1,132 +0,0 @@
-"""Unpack Office files (DOCX, PPTX, XLSX) for editing.
-
-Extracts the ZIP archive, pretty-prints XML files, and optionally:
-- Merges adjacent runs with identical formatting (DOCX only)
-- Simplifies adjacent tracked changes from same author (DOCX only)
-
-Usage:
-    python unpack.py <office_file> <output_dir> [options]
-
-Examples:
-    python unpack.py document.docx unpacked/
-    python unpack.py presentation.pptx unpacked/
-    python unpack.py document.docx unpacked/ --merge-runs false
-"""
-
-import argparse
-import sys
-import zipfile
-from pathlib import Path
-
-import defusedxml.minidom
-
-from helpers.merge_runs import merge_runs as do_merge_runs
-from helpers.simplify_redlines import simplify_redlines as do_simplify_redlines
-
-SMART_QUOTE_REPLACEMENTS = {
-    "\u201c": "&#x201C;",  
-    "\u201d": "&#x201D;",  
-    "\u2018": "&#x2018;",  
-    "\u2019": "&#x2019;",  
-}
-
-
-def unpack(
-    input_file: str,
-    output_directory: str,
-    merge_runs: bool = True,
-    simplify_redlines: bool = True,
-) -> tuple[None, str]:
-    input_path = Path(input_file)
-    output_path = Path(output_directory)
-    suffix = input_path.suffix.lower()
-
-    if not input_path.exists():
-        return None, f"Error: {input_file} does not exist"
-
-    if suffix not in {".docx", ".pptx", ".xlsx"}:
-        return None, f"Error: {input_file} must be a .docx, .pptx, or .xlsx file"
-
-    try:
-        output_path.mkdir(parents=True, exist_ok=True)
-
-        with zipfile.ZipFile(input_path, "r") as zf:
-            zf.extractall(output_path)
-
-        xml_files = list(output_path.rglob("*.xml")) + list(output_path.rglob("*.rels"))
-        for xml_file in xml_files:
-            _pretty_print_xml(xml_file)
-
-        message = f"Unpacked {input_file} ({len(xml_files)} XML files)"
-
-        if suffix == ".docx":
-            if simplify_redlines:
-                simplify_count, _ = do_simplify_redlines(str(output_path))
-                message += f", simplified {simplify_count} tracked changes"
-
-            if merge_runs:
-                merge_count, _ = do_merge_runs(str(output_path))
-                message += f", merged {merge_count} runs"
-
-        for xml_file in xml_files:
-            _escape_smart_quotes(xml_file)
-
-        return None, message
-
-    except zipfile.BadZipFile:
-        return None, f"Error: {input_file} is not a valid Office file"
-    except Exception as e:
-        return None, f"Error unpacking: {e}"
-
-
-def _pretty_print_xml(xml_file: Path) -> None:
-    try:
-        content = xml_file.read_text(encoding="utf-8")
-        dom = defusedxml.minidom.parseString(content)
-        xml_file.write_bytes(dom.toprettyxml(indent="  ", encoding="utf-8"))
-    except Exception:
-        pass  
-
-
-def _escape_smart_quotes(xml_file: Path) -> None:
-    try:
-        content = xml_file.read_text(encoding="utf-8")
-        for char, entity in SMART_QUOTE_REPLACEMENTS.items():
-            content = content.replace(char, entity)
-        xml_file.write_text(content, encoding="utf-8")
-    except Exception:
-        pass
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser(
-        description="Unpack an Office file (DOCX, PPTX, XLSX) for editing"
-    )
-    parser.add_argument("input_file", help="Office file to unpack")
-    parser.add_argument("output_directory", help="Output directory")
-    parser.add_argument(
-        "--merge-runs",
-        type=lambda x: x.lower() == "true",
-        default=True,
-        metavar="true|false",
-        help="Merge adjacent runs with identical formatting (DOCX only, default: true)",
-    )
-    parser.add_argument(
-        "--simplify-redlines",
-        type=lambda x: x.lower() == "true",
-        default=True,
-        metavar="true|false",
-        help="Merge adjacent tracked changes from same author (DOCX only, default: true)",
-    )
-    args = parser.parse_args()
-
-    _, message = unpack(
-        args.input_file,
-        args.output_directory,
-        merge_runs=args.merge_runs,
-        simplify_redlines=args.simplify_redlines,
-    )
-    print(message)
-
-    if "Error" in message:
-        sys.exit(1)

skills/docx/scripts/office/validate.py

@@ -6,7 +6,7 @@ Usage:
 
 The first argument can be either:
 - An unpacked directory containing the Office document XML files
-- A packed Office file (.docx/.pptx/.xlsx) which will be unpacked to a temp directory
+- A packed Office file (.docx/.pptx/.xlsx or .dotx/.potx/.xltx template) which will be unpacked to a temp directory
 
 Auto-repair fixes:
 - paraId/durableId values that exceed OOXML limits
@@ -19,20 +19,43 @@ import tempfile
 import zipfile
 from pathlib import Path
 
+import defusedxml.ElementTree as ET
+from defusedxml.common import DefusedXmlException
+
+from helpers import OOXML_FAMILY, rezip, safe_extract
 from validators import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator
 
+WORD_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+
+def _fail(message: str):
+    print(f"Error: {message}", file=sys.stderr)
+    sys.exit(2)
+
+
+def _has_tracked_changes(unpacked_dir: Path) -> bool:
+    document = unpacked_dir / "word" / "document.xml"
+    if not document.is_file():
+        return False
+    try:
+        root = ET.parse(document).getroot()
+    except (ET.ParseError, DefusedXmlException):
+        return False  
+    tracked = {f"{{{WORD_NS}}}ins", f"{{{WORD_NS}}}del"}
+    return any(elem.tag in tracked for elem in root.iter())
+
 
 def main():
     parser = argparse.ArgumentParser(description="Validate Office document XML files")
     parser.add_argument(
         "path",
-        help="Path to unpacked directory or packed Office file (.docx/.pptx/.xlsx)",
+        help="Path to unpacked directory or packed Office file (.docx/.pptx/.xlsx or .dotx/.potx/.xltx)",
     )
     parser.add_argument(
         "--original",
         required=False,
         default=None,
-        help="Path to original file (.docx/.pptx/.xlsx). If omitted, all XSD errors are reported and redlining validation is skipped.",
+        help="Path to original file (.docx/.pptx/.xlsx or .dotx/.potx/.xltx). If omitted, all XSD errors are reported and redlining validation is skipped.",
     )
     parser.add_argument(
         "-v",
@@ -43,63 +66,102 @@ def main():
     parser.add_argument(
         "--auto-repair",
         action="store_true",
-        help="Automatically repair common issues (hex IDs, whitespace preservation)",
+        help="Automatically repair common issues (hex IDs, whitespace preservation). "
+        "Modifies the input in place: repairs to a packed file are written back to it.",
     )
     parser.add_argument(
         "--author",
-        default="Claude",
-        help="Author name for redlining validation (default: Claude)",
+        default=None,
+        help="The name you are redlining under. Passing it turns on the "
+        "tracked-change check: any text differing from --original without a "
+        "<w:ins>/<w:del> recording it is reported. Untracked edits carry no "
+        "author, so the check covers them whoever made them — the name marks "
+        "the run as redlining work and is not used to filter. Requires "
+        "--original; docx only.",
     )
     args = parser.parse_args()
 
+    if args.author is not None and not args.original:
+        _fail("--author requires --original")
+
     path = Path(args.path)
-    assert path.exists(), f"Error: {path} does not exist"
+    if not path.exists():
+        _fail(f"{path} does not exist")
 
     original_file = None
     if args.original:
         original_file = Path(args.original)
-        assert original_file.is_file(), f"Error: {original_file} is not a file"
-        assert original_file.suffix.lower() in [".docx", ".pptx", ".xlsx"], (
-            f"Error: {original_file} must be a .docx, .pptx, or .xlsx file"
+        if not original_file.is_file():
+            _fail(f"{original_file} is not a file")
+        if original_file.suffix.lower() not in OOXML_FAMILY:
+            _fail(f"{original_file} must be one of: {', '.join(sorted(OOXML_FAMILY))}")
+
+    family = OOXML_FAMILY.get((original_file or path).suffix.lower())
+    if family is None:
+        _fail(
+            f"Cannot determine file type from {path}. Use --original or provide one of: {', '.join(sorted(OOXML_FAMILY))}."
         )
 
-    file_extension = (original_file or path).suffix.lower()
-    assert file_extension in [".docx", ".pptx", ".xlsx"], (
-        f"Error: Cannot determine file type from {path}. Use --original or provide a .docx/.pptx/.xlsx file."
-    )
+    if args.author is not None and family != "docx":
+        _fail(f"--author only applies to docx files, not {family}")
 
-    if path.is_file() and path.suffix.lower() in [".docx", ".pptx", ".xlsx"]:
-        temp_dir = tempfile.mkdtemp()
-        with zipfile.ZipFile(path, "r") as zf:
-            zf.extractall(temp_dir)
-        unpacked_dir = Path(temp_dir)
+    packed_file = None
+    temp_dir_ctx = None
+    if path.is_file() and path.suffix.lower() in OOXML_FAMILY:
+        packed_file = path
+        temp_dir_ctx = tempfile.TemporaryDirectory()
+        unpacked_dir = Path(temp_dir_ctx.name)
+        try:
+            with zipfile.ZipFile(path, "r") as zf:
+                safe_extract(zf, unpacked_dir)
+        except (zipfile.BadZipFile, ValueError, OSError) as e:
+            _fail(f"cannot unpack {path}: {e}")
     else:
-        assert path.is_dir(), f"Error: {path} is not a directory or Office file"
+        if not path.is_dir():
+            _fail(f"{path} is not a directory or Office file")
         unpacked_dir = path
 
-    match file_extension:
-        case ".docx":
+    match family:
+        case "docx":
             validators = [
                 DOCXSchemaValidator(unpacked_dir, original_file, verbose=args.verbose),
             ]
-            if original_file:
+            if args.author is not None:
                 validators.append(
-                    RedliningValidator(unpacked_dir, original_file, verbose=args.verbose, author=args.author)  
+                    RedliningValidator(unpacked_dir, original_file, verbose=args.verbose)  
                 )
-        case ".pptx":
+            elif original_file and _has_tracked_changes(unpacked_dir):
+                print(
+                    "Note: this document has tracked changes; they were not "
+                    "checked against the original (pass --author to check)."
+                )
+        case "pptx":
             validators = [
                 PPTXSchemaValidator(unpacked_dir, original_file, verbose=args.verbose),
             ]
+        case "xlsx":
+            exts = ", ".join(k for k, v in sorted(OOXML_FAMILY.items()) if v == "xlsx")
+            print(
+                f"No XSD schema validation is performed for xlsx-family files ({exts}). "
+                "For formula-error checking, use scripts/recalc.py instead."
+            )
+            sys.exit(0)
         case _:
-            print(f"Error: Validation not supported for file type {file_extension}")
+            print(f"Error: Validation not supported for file type {family}")
             sys.exit(1)
 
     if args.auto_repair:
         total_repairs = sum(v.repair() for v in validators)
         if total_repairs:
             print(f"Auto-repaired {total_repairs} issue(s)")
+            if packed_file is not None:
+                rezip(unpacked_dir, packed_file)
+                print(f"Wrote repaired file to {packed_file}")
 
-    success = all(v.validate() for v in validators)
+    success = all([v.validate() for v in validators])
+
+    if temp_dir_ctx is not None:
+        temp_dir_ctx.cleanup()
 
     if success:
         print("All validations PASSED!")

skills/docx/scripts/office/validators/base.py

@@ -6,8 +6,20 @@ import re
 from pathlib import Path
 
 import defusedxml.minidom
+from functools import lru_cache
+
 import lxml.etree
 
+from helpers import safe_extract
+
+
+@lru_cache(maxsize=None)
+def _load_schema(schema_path: str):
+    with open(schema_path, "rb") as xsd_file:
+        xsd_doc = lxml.etree.parse(
+            xsd_file, parser=lxml.etree.XMLParser(), base_url=schema_path
+        )
+    return lxml.etree.XMLSchema(xsd_doc)
 
 class BaseSchemaValidator:
 
@@ -119,21 +131,28 @@ class BaseSchemaValidator:
             try:
                 content = xml_file.read_text(encoding="utf-8")
                 dom = defusedxml.minidom.parseString(content)
-                modified = False
+                pending = []  
 
                 for elem in dom.getElementsByTagName("*"):
-                    if elem.tagName.endswith(":t") and elem.firstChild:
-                        text = elem.firstChild.nodeValue
-                        if text and (text.startswith((' ', '\t')) or text.endswith((' ', '\t'))):
+                    local_name = elem.tagName.rsplit(":", 1)[-1]
+                    if local_name in ("t", "delText", "instrText", "delInstrText"):
+                        text = "".join(
+                            child.data
+                            for child in elem.childNodes
+                            if child.nodeType in (child.TEXT_NODE, child.CDATA_SECTION_NODE)
+                        )
+                        ws = (" ", "\t", "\n", "\r")
+                        if text and (text.startswith(ws) or text.endswith(ws)):
                             if elem.getAttribute("xml:space") != "preserve":
                                 elem.setAttribute("xml:space", "preserve")
                                 text_preview = repr(text[:30]) + "..." if len(text) > 30 else repr(text)
-                                print(f"  Repaired: {xml_file.name}: Added xml:space='preserve' to {elem.tagName}: {text_preview}")
-                                repairs += 1
-                                modified = True
+                                pending.append(f"  Repaired: {xml_file.name}: Added xml:space='preserve' to {elem.tagName}: {text_preview}")
 
-                if modified:
+                if pending:
                     xml_file.write_bytes(dom.toxml(encoding="UTF-8"))
+                    for message in pending:
+                        print(message)
+                    repairs += len(pending)
 
             except Exception:
                 pass
@@ -212,6 +231,8 @@ class BaseSchemaValidator:
                     elem.getparent().remove(elem)
 
                 for elem in root.iter():
+                    if not hasattr(elem, "tag") or callable(elem.tag):
+                        continue
                     tag = (
                         elem.tag.split("}")[-1].lower()
                         if "}" in elem.tag
@@ -326,6 +347,8 @@ class BaseSchemaValidator:
                     namespaces={"ns": self.PACKAGE_RELATIONSHIPS_NAMESPACE},
                 ):
                     target = rel.get("Target")
+                    if rel.get("TargetMode") == "External":
+                        continue
                     if target and not target.startswith(
                         ("http", "mailto:")
                     ):  
@@ -423,6 +446,8 @@ class BaseSchemaValidator:
                 r_ns = self.OFFICE_RELATIONSHIPS_NAMESPACE
                 rid_attrs_to_check = ["id", "embed", "link"]
                 for elem in xml_root.iter():
+                    if not hasattr(elem, "tag") or callable(elem.tag):
+                        continue
                     for attr_name in rid_attrs_to_check:
                         rid_attr = elem.get(f"{{{r_ns}}}{attr_name}")
                         if not rid_attr:
@@ -747,18 +772,16 @@ class BaseSchemaValidator:
 
         return xml_doc
 
-    def _validate_single_file_xsd(self, xml_file, base_path):
-        schema_path = self._get_schema_path(xml_file)
+    def _preprocess_for_schema(self, xml_doc, relative_path):
+        return xml_doc
+
+    def _validate_single_file_xsd(self, xml_file, base_path, schema_path=None):
+        schema_path = schema_path or self._get_schema_path(xml_file)
         if not schema_path:
             return None, None  
 
         try:
-            with open(schema_path, "rb") as xsd_file:
-                parser = lxml.etree.XMLParser()
-                xsd_doc = lxml.etree.parse(
-                    xsd_file, parser=parser, base_url=str(schema_path)
-                )
-                schema = lxml.etree.XMLSchema(xsd_doc)
+            schema = _load_schema(str(schema_path))
 
             with open(xml_file, "r") as f:
                 xml_doc = lxml.etree.parse(f)
@@ -773,6 +796,8 @@ class BaseSchemaValidator:
             ):
                 xml_doc = self._clean_ignorable_namespaces(xml_doc)
 
+            xml_doc = self._preprocess_for_schema(xml_doc, relative_path)
+
             if schema.validate(xml_doc):
                 return True, set()
             else:
@@ -784,7 +809,7 @@ class BaseSchemaValidator:
         except Exception as e:
             return False, {str(e)}
 
-    def _get_original_file_errors(self, xml_file):
+    def _get_original_file_errors(self, xml_file, schema_path=None):
         if self.original_file is None:
             return set()
 
@@ -798,8 +823,11 @@ class BaseSchemaValidator:
         with tempfile.TemporaryDirectory() as temp_dir:
             temp_path = Path(temp_dir)
 
-            with zipfile.ZipFile(self.original_file, "r") as zip_ref:
-                zip_ref.extractall(temp_path)
+            try:
+                with zipfile.ZipFile(self.original_file, "r") as zip_ref:
+                    safe_extract(zip_ref, temp_path)
+            except (zipfile.BadZipFile, ValueError, OSError):
+                return set()
 
             original_xml_file = temp_path / relative_path
 
@@ -807,7 +835,7 @@ class BaseSchemaValidator:
                 return set()
 
             is_valid, errors = self._validate_single_file_xsd(
-                original_xml_file, temp_path
+                original_xml_file, temp_path, schema_path=schema_path
             )
             return errors if errors else set()
 

skills/docx/scripts/office/validators/docx.py

@@ -6,10 +6,13 @@ import random
 import re
 import tempfile
 import zipfile
+from pathlib import Path
 
 import defusedxml.minidom
 import lxml.etree
 
+from helpers import safe_extract
+
 from .base import BaseSchemaValidator
 
 
@@ -186,7 +189,7 @@ class DOCXSchemaValidator(BaseSchemaValidator):
         try:
             with tempfile.TemporaryDirectory() as temp_dir:
                 with zipfile.ZipFile(original, "r") as zip_ref:
-                    zip_ref.extractall(temp_dir)
+                    safe_extract(zip_ref, Path(temp_dir))
 
                 doc_xml_path = temp_dir + "/word/document.xml"
                 root = lxml.etree.parse(doc_xml_path).getroot()
@@ -241,9 +244,12 @@ class DOCXSchemaValidator(BaseSchemaValidator):
             return True
 
     def compare_paragraph_counts(self):
-        original_count = self.count_paragraphs_in_original()
         new_count = self.count_paragraphs_in_unpacked()
+        if self.original_file is None:
+            print(f"\nParagraphs: {new_count}")
+            return
 
+        original_count = self.count_paragraphs_in_original()
         diff = new_count - original_count
         diff_str = f"+{diff}" if diff > 0 else str(diff)
         print(f"\nParagraphs: {original_count} → {new_count} ({diff_str})")
@@ -260,9 +266,15 @@ class DOCXSchemaValidator(BaseSchemaValidator):
             try:
                 for elem in lxml.etree.parse(str(xml_file)).iter():
                     if val := elem.get(para_id_attr):
-                        if self._parse_id_value(val, base=16) >= 0x80000000:
+                        try:
+                            if self._parse_id_value(val, base=16) >= 0x80000000:
+                                errors.append(
+                                    f"  {xml_file.name}:{elem.sourceline}: paraId={val} >= 0x80000000"
+                                )
+                        except ValueError:
                             errors.append(
-                                f"  {xml_file.name}:{elem.sourceline}: paraId={val} >= 0x80000000"
+                                f"  {xml_file.name}:{elem.sourceline}: "
+                                f"paraId={val} is not valid hex"
                             )
 
                     if val := elem.get(durable_id_attr):
@@ -279,13 +291,19 @@ class DOCXSchemaValidator(BaseSchemaValidator):
                                     f"durableId={val} must be decimal in numbering.xml"
                                 )
                         else:
-                            if self._parse_id_value(val, base=16) >= 0x7FFFFFFF:
+                            try:
+                                if self._parse_id_value(val, base=16) >= 0x7FFFFFFF:
+                                    errors.append(
+                                        f"  {xml_file.name}:{elem.sourceline}: "
+                                        f"durableId={val} >= 0x7FFFFFFF"
+                                    )
+                            except ValueError:
                                 errors.append(
                                     f"  {xml_file.name}:{elem.sourceline}: "
-                                    f"durableId={val} >= 0x7FFFFFFF"
+                                    f"durableId={val} is not valid hex"
                                 )
-            except Exception:
-                pass
+            except lxml.etree.XMLSyntaxError:
+                continue  
 
         if errors:
             print(f"FAILED - {len(errors)} ID constraint violations:")
@@ -389,52 +407,54 @@ class DOCXSchemaValidator(BaseSchemaValidator):
         return repairs
 
     def repair_durableId(self) -> int:
+        DURABLE_ID_ATTRS = ("w16cid:durableId", "w16cex:durableId")
         repairs = 0
+        renames: dict = {}  
 
         for xml_file in self.xml_files:
             try:
                 content = xml_file.read_text(encoding="utf-8")
                 dom = defusedxml.minidom.parseString(content)
+                is_numbering = xml_file.name == "numbering.xml"
+                base = 10 if is_numbering else 16
+                pending = []  
+                seen_in_file = set()
                 modified = False
 
                 for elem in dom.getElementsByTagName("*"):
-                    if not elem.hasAttribute("w16cid:durableId"):
-                        continue
+                    for attr_name in DURABLE_ID_ATTRS:
+                        if not elem.hasAttribute(attr_name):
+                            continue
 
-                    durable_id = elem.getAttribute("w16cid:durableId")
-                    needs_repair = False
-
-                    if xml_file.name == "numbering.xml":
+                        durable_id = elem.getAttribute(attr_name)
                         try:
-                            needs_repair = (
-                                self._parse_id_value(durable_id, base=10) >= 0x7FFFFFFF
-                            )
-                        except ValueError:
-                            needs_repair = True
-                    else:
-                        try:
-                            needs_repair = (
-                                self._parse_id_value(durable_id, base=16) >= 0x7FFFFFFF
-                            )
+                            key = self._parse_id_value(durable_id, base=base)
+                            needs_repair = key >= 0x7FFFFFFF
                         except ValueError:
+                            key = durable_id
                             needs_repair = True
 
-                    if needs_repair:
-                        value = random.randint(1, 0x7FFFFFFE)
-                        if xml_file.name == "numbering.xml":
-                            new_id = str(value)  
-                        else:
-                            new_id = f"{value:08X}"  
+                        if needs_repair:
+                            if key in seen_in_file:
+                                value = random.randint(1, 0x7FFFFFFE)
+                            else:
+                                seen_in_file.add(key)
+                                if key not in renames:
+                                    renames[key] = random.randint(1, 0x7FFFFFFE)
+                                value = renames[key]
+                            new_id = str(value) if is_numbering else f"{value:08X}"
 
-                        elem.setAttribute("w16cid:durableId", new_id)
-                        print(
-                            f"  Repaired: {xml_file.name}: durableId {durable_id} → {new_id}"
-                        )
-                        repairs += 1
-                        modified = True
+                            elem.setAttribute(attr_name, new_id)
+                            pending.append(
+                                f"  Repaired: {xml_file.name}: durableId {durable_id} → {new_id}"
+                            )
+                            modified = True
 
                 if modified:
                     xml_file.write_bytes(dom.toxml(encoding="UTF-8"))
+                    for message in pending:
+                        print(message)
+                    repairs += len(pending)
 
             except Exception:
                 pass

skills/docx/scripts/office/validators/pptx.py

@@ -3,6 +3,9 @@ Validator for PowerPoint presentation XML files against XSD schemas.
 """
 
 import re
+from pathlib import Path
+
+from helpers import opc_target, rels_source_part, safe_extract
 
 from .base import BaseSchemaValidator
 
@@ -57,8 +60,171 @@ class PPTXSchemaValidator(BaseSchemaValidator):
         if not self.validate_no_duplicate_slide_layouts():
             all_valid = False
 
+        if not self.validate_master_theme_uniqueness():
+            all_valid = False
+
+        if not self.validate_charts():
+            all_valid = False
+
+        if not self.validate_slides():
+            all_valid = False
+
         return all_valid
 
+    def _package_map(self) -> dict:
+        wanted = []
+        wanted += list(self.unpacked_dir.glob("[[]Content_Types[]].xml"))
+        wanted += list(self.unpacked_dir.glob("ppt/presentation.xml"))
+        wanted += list(self.unpacked_dir.glob("ppt/theme/*.xml"))
+        wanted += list(self.unpacked_dir.glob("ppt/theme/_rels/*.rels"))
+        wanted += list(self.unpacked_dir.glob("ppt/charts/chart*.xml"))
+        for group in ("slideMasters", "notesMasters", "handoutMasters"):
+            wanted += list(self.unpacked_dir.glob(f"ppt/{group}/*.xml"))
+            wanted += list(self.unpacked_dir.glob(f"ppt/{group}/_rels/*.rels"))
+        return {
+            p.relative_to(self.unpacked_dir).as_posix(): p.read_bytes()
+            for p in wanted
+            if p.is_file()
+        }
+
+    def validate_master_theme_uniqueness(self):
+        from helpers.pptx_theme import _NOTES_MASTERS, live_shared_master_themes
+
+        shared = live_shared_master_themes(self._package_map())
+        if shared:
+            print(f"FAILED - Found {len(shared)} master(s) sharing a theme part:")
+            for message in shared:
+                print(f"  {message}")
+            if any(m.startswith(_NOTES_MASTERS) for m in shared):
+                print("  Fix: in ppt/presentation.xml, move <p:notesMasterIdLst> back to "
+                      "directly after <p:sldIdLst>. PowerPoint reads that happily.")
+            else:
+                print("  Fix: give each master its own theme part.")
+            return False
+
+        if self.verbose:
+            print("PASSED - No master shares a theme part in a way PowerPoint refuses")
+        return True
+
+    def validate_charts(self):
+        from helpers.pptx_chart import find_chart_problems
+
+        problems = find_chart_problems(self._package_map())
+        if problems:
+            print(f"FAILED - Found {len(problems)} chart problem(s) PowerPoint rejects:")
+            for message in problems:
+                print(f"  {message}")
+            return False
+
+        if self.verbose:
+            print("PASSED - Charts satisfy the constraints PowerPoint enforces")
+        return True
+
+    def _original_slide_defects(self, schema) -> set[str]:
+        import tempfile
+        import zipfile
+
+        from helpers.pptx_slide import SLIDE_PART_RE, fatal_slide_errors
+
+        if self.original_file is None:
+            return set()
+
+        found: set[str] = set()
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_path = Path(temp_dir)
+            try:
+                with zipfile.ZipFile(self.original_file, "r") as zf:
+                    safe_extract(zf, temp_path)
+            except (zipfile.BadZipFile, ValueError, OSError):
+                return set()  
+
+            for part in sorted(temp_path.rglob("*.xml")):
+                relative = part.relative_to(temp_path).as_posix()
+                if not SLIDE_PART_RE.fullmatch(relative):
+                    continue
+                ok, errors = self._validate_single_file_xsd(
+                    part.resolve(), temp_path.resolve(), schema_path=schema
+                )
+                if ok is None or ok or not errors:
+                    continue
+                found |= set(fatal_slide_errors(set(errors)))
+        return found
+
+    def validate_slides(self):
+        from helpers.pptx_slide import (
+            SLIDE_PART_RE,
+            fatal_slide_errors,
+            is_schema_verdict,
+        )
+
+        schema = self.schemas_dir / self.SCHEMA_MAPPINGS["ppt"]
+        inherited = self._original_slide_defects(schema)
+        problems: list[str] = []
+        broken: list[str] = []
+
+        for xml_file in self.xml_files:
+            relative = xml_file.relative_to(self.unpacked_dir).as_posix()
+            if not SLIDE_PART_RE.fullmatch(relative):
+                continue
+            ok, errors = self._validate_single_file_xsd(
+                xml_file.resolve(), self.unpacked_dir.resolve(), schema_path=schema
+            )
+            if ok is None or not errors:
+                continue
+
+            unreadable = [f"{relative}: {e}" for e in errors if not is_schema_verdict(e)]
+            if unreadable:
+                broken.extend(unreadable)
+                continue
+            if ok:
+                continue
+
+            for message in fatal_slide_errors(set(errors)):
+                if message in inherited:
+                    continue  
+                problems.append(f"{relative}: {message}")
+
+        if broken:
+            print(f"FAILED - Could not check {len(broken)} slide part(s):")
+            for message in sorted(broken):
+                print(f"  {message[:240]}")
+
+        if problems:
+            print(f"FAILED - Found {len(problems)} slide problem(s) PowerPoint rejects:")
+            for message in sorted(problems):
+                print(f"  {message[:240]}")
+
+        if broken or problems:
+            return False
+
+        if self.verbose:
+            print("PASSED - Slide XML has none of the defects PowerPoint refuses")
+        return True
+
+    def _get_schema_path(self, xml_file):
+        if xml_file.parent.name == "charts" and xml_file.name.startswith("chart"):
+            return None
+        return super()._get_schema_path(xml_file)
+
+    def _preprocess_for_schema(self, xml_doc, relative_path):
+        if relative_path.as_posix() != "ppt/presentation.xml":
+            return xml_doc
+
+        root = xml_doc.getroot()
+        ns = f"{{{self.PRESENTATIONML_NAMESPACE}}}"
+        notes = root.find(f"{ns}notesMasterIdLst")
+        slides = root.find(f"{ns}sldIdLst")
+        if notes is None or slides is None:
+            return xml_doc
+
+        children = list(root)
+        if children.index(notes) < children.index(slides):
+            return xml_doc  
+
+        root.remove(notes)
+        root.insert(list(root).index(slides), notes)
+        return xml_doc
+
     def validate_uuid_ids(self):
         import lxml.etree
 
@@ -229,17 +395,17 @@ class PPTXSchemaValidator(BaseSchemaValidator):
                 ):
                     rel_type = rel.get("Type", "")
                     if "notesSlide" in rel_type:
-                        target = rel.get("Target", "")
-                        if target:
-                            normalized_target = target.replace("../", "")
-
+                        part = opc_target(
+                            rel.get("Target", ""),
+                            rels_source_part(rels_file, self.unpacked_dir),
+                            rel.get("TargetMode", ""),
+                        )
+                        if part:
                             slide_name = rels_file.stem.replace(
                                 ".xml", ""
                             )  
 
-                            if normalized_target not in notes_slide_references:
-                                notes_slide_references[normalized_target] = []
-                            notes_slide_references[normalized_target].append(
+                            notes_slide_references.setdefault(part, []).append(
                                 (slide_name, rels_file)
                             )
 

skills/docx/scripts/office/validators/redlining.py

@@ -1,5 +1,14 @@
 """
 Validator for tracked changes in Word documents.
+
+Detects untracked edits in word/document.xml: text that differs from the
+original without a <w:ins>/<w:del> wrapper recording it. The tracked changes
+that are new relative to the original are undone, and the result is compared
+against the original; whatever text still differs was edited without being
+tracked.
+
+Only the document body is compared. Headers, footers, footnotes and endnotes
+are separate parts and are not checked.
 """
 
 import subprocess
@@ -7,14 +16,18 @@ import tempfile
 import zipfile
 from pathlib import Path
 
+import defusedxml.ElementTree as ET
+from defusedxml.common import DefusedXmlException
+
+from helpers import rendered_text, safe_extract
+
 
 class RedliningValidator:
 
-    def __init__(self, unpacked_dir, original_docx, verbose=False, author="Claude"):
+    def __init__(self, unpacked_dir, original_docx, verbose=False):
         self.unpacked_dir = Path(unpacked_dir)
         self.original_docx = Path(original_docx)
         self.verbose = verbose
-        self.author = author
         self.namespaces = {
             "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
         }
@@ -28,40 +41,12 @@ class RedliningValidator:
             print(f"FAILED - Modified document.xml not found at {modified_file}")
             return False
 
-        try:
-            import xml.etree.ElementTree as ET
-
-            tree = ET.parse(modified_file)
-            root = tree.getroot()
-
-            del_elements = root.findall(".//w:del", self.namespaces)
-            ins_elements = root.findall(".//w:ins", self.namespaces)
-
-            author_del_elements = [
-                elem
-                for elem in del_elements
-                if elem.get(f"{{{self.namespaces['w']}}}author") == self.author
-            ]
-            author_ins_elements = [
-                elem
-                for elem in ins_elements
-                if elem.get(f"{{{self.namespaces['w']}}}author") == self.author
-            ]
-
-            if not author_del_elements and not author_ins_elements:
-                if self.verbose:
-                    print(f"PASSED - No tracked changes by {self.author} found.")
-                return True
-
-        except Exception:
-            pass
-
         with tempfile.TemporaryDirectory() as temp_dir:
             temp_path = Path(temp_dir)
 
             try:
                 with zipfile.ZipFile(self.original_docx, "r") as zip_ref:
-                    zip_ref.extractall(temp_path)
+                    safe_extract(zip_ref, temp_path)
             except Exception as e:
                 print(f"FAILED - Error unpacking original docx: {e}")
                 return False
@@ -74,18 +59,16 @@ class RedliningValidator:
                 return False
 
             try:
-                import xml.etree.ElementTree as ET
-
                 modified_tree = ET.parse(modified_file)
                 modified_root = modified_tree.getroot()
                 original_tree = ET.parse(original_file)
                 original_root = original_tree.getroot()
-            except ET.ParseError as e:
+            except (ET.ParseError, DefusedXmlException) as e:
                 print(f"FAILED - Error parsing XML files: {e}")
                 return False
 
-            self._remove_author_tracked_changes(original_root)
-            self._remove_author_tracked_changes(modified_root)
+            new_changes = self._new_tracked_changes(original_root, modified_root)
+            self._remove_tracked_changes(modified_root, new_changes)
 
             modified_text = self._extract_text_content(modified_root)
             original_text = self._extract_text_content(original_root)
@@ -98,20 +81,91 @@ class RedliningValidator:
                 return False
 
             if self.verbose:
-                print(f"PASSED - All changes by {self.author} are properly tracked")
+                print(
+                    f"PASSED - All {len(new_changes)} change(s) against the original "
+                    "are properly tracked"
+                )
             return True
 
+    def _tracked_change_elements(self, root):
+        ins_tag = f"{{{self.namespaces['w']}}}ins"
+        del_tag = f"{{{self.namespaces['w']}}}del"
+        return [elem for elem in root.iter() if elem.tag in (ins_tag, del_tag)]
+
+    def _rendered_text(self, elem):
+        preserve = elem.get("{http://www.w3.org/XML/1998/namespace}space") == "preserve"
+        return rendered_text(elem.text or "", preserve)
+
+    def _text_elements(self, elem):
+        w = self.namespaces["w"]
+        return [
+            node
+            for node in elem.iter()
+            if node.tag in (f"{{{w}}}t", f"{{{w}}}delText")
+        ]
+
+    def _tracked_change_key(self, elem):
+        w = self.namespaces["w"]
+        text = "".join(self._rendered_text(node) for node in self._text_elements(elem))
+        return (elem.tag, elem.get(f"{{{w}}}author"), elem.get(f"{{{w}}}date"), text)
+
+    def _new_tracked_changes(self, original_root, modified_root):
+        original = self._tracked_change_elements(original_root)
+        modified = self._tracked_change_elements(modified_root)
+
+        pool = {}
+        for elem in original:
+            pool.setdefault(self._tracked_change_key(elem), []).append(elem)
+
+        matched, leftover = set(), []
+        for elem in modified:
+            bucket = pool.get(self._tracked_change_key(elem))
+            if bucket:
+                matched.add(bucket.pop())
+            else:
+                leftover.append(elem)
+
+        def group(elem):
+            return self._tracked_change_key(elem)[:3]
+
+        def text_of(elems):
+            return "".join(self._tracked_change_key(e)[3] for e in elems)
+
+        unmatched_original = {}
+        for elem in original:
+            if elem not in matched:
+                unmatched_original.setdefault(group(elem), []).append(elem)
+
+        by_group = {}
+        for elem in leftover:
+            by_group.setdefault(group(elem), []).append(elem)
+
+        new = set()
+        for key, elems in by_group.items():
+            rebuilt = text_of(elems)
+            if rebuilt and rebuilt == text_of(unmatched_original.get(key, [])):
+                continue  
+            new.update(elems)
+        return new
+
     def _generate_detailed_diff(self, original_text, modified_text):
         error_parts = [
-            f"FAILED - Document text doesn't match after removing {self.author}'s tracked changes",
+            "FAILED - Document text doesn't match after removing the tracked changes",
             "",
             "Likely causes:",
             "  1. Modified text inside another author's <w:ins> or <w:del> tags",
             "  2. Made edits without proper tracked changes",
             "  3. Didn't nest <w:del> inside <w:ins> when deleting another's insertion",
+            "  4. Rewrote another author's <w:ins>/<w:del> and changed its text on",
+            "     the way. A tracked change from the original is recognised by its",
+            "     author, date and text; anything that doesn't reproduce one exactly",
+            "     reads as new, and the text it carried is reported missing.",
             "",
             "For pre-redlined documents, use correct patterns:",
             "  - To reject another's INSERTION: Nest <w:del> inside their <w:ins>",
+            "  - To reject PART of one: nest <w:del> around only the runs you reject.",
+            "    Their <w:ins> may be split around it, so long as the pieces keep",
+            "    their author and date and still spell out the same text.",
             "  - To restore another's DELETION: Add new <w:ins> AFTER their <w:del>",
             "",
         ]
@@ -195,15 +249,14 @@ class RedliningValidator:
 
         return None
 
-    def _remove_author_tracked_changes(self, root):
+    def _remove_tracked_changes(self, root, targets):
         ins_tag = f"{{{self.namespaces['w']}}}ins"
         del_tag = f"{{{self.namespaces['w']}}}del"
-        author_attr = f"{{{self.namespaces['w']}}}author"
 
         for parent in root.iter():
             to_remove = []
             for child in parent:
-                if child.tag == ins_tag and child.get(author_attr) == self.author:
+                if child.tag == ins_tag and child in targets:
                     to_remove.append(child)
             for elem in to_remove:
                 parent.remove(elem)
@@ -214,7 +267,7 @@ class RedliningValidator:
         for parent in root.iter():
             to_process = []
             for child in parent:
-                if child.tag == del_tag and child.get(author_attr) == self.author:
+                if child.tag == del_tag and child in targets:
                     to_process.append((child, list(parent).index(child)))
 
             for del_elem, del_index in reversed(to_process):
@@ -234,8 +287,7 @@ class RedliningValidator:
         for p_elem in root.findall(f".//{p_tag}"):
             text_parts = []
             for t_elem in p_elem.findall(f".//{t_tag}"):
-                if t_elem.text:
-                    text_parts.append(t_elem.text)
+                text_parts.append(self._rendered_text(t_elem))
             paragraph_text = "".join(text_parts)
             if paragraph_text:
                 paragraphs.append(paragraph_text)

skills/pptx/SKILL.md

@@ -1,52 +1,81 @@
 ---
 name: pptx
-description: "Use this skill any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions \"deck,\" \"slides,\" \"presentation,\" or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this skill."
+description: "Use this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions \"deck,\" \"slides,\" \"presentation,\" or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill."
 license: Proprietary. LICENSE.txt has complete terms
 ---
 
-# PPTX Skill
+# PPTX creation, editing, and analysis
 
-## Quick Reference
+A `.pptx` is a ZIP archive of XML files. Choose your approach by task:
 
-| Task | Guide |
-|------|-------|
-| Read/analyze content | `python -m markitdown presentation.pptx` |
-| Edit or create from template | Read [editing.md](editing.md) |
-| Create from scratch | Read [pptxgenjs.md](pptxgenjs.md) |
+| Task | Approach |
+|---|---|
+| **Create** a new deck | Write a `pptxgenjs` script — see gotchas below |
+| **Edit** an existing deck, or build from a template | unzip → edit `ppt/slides/slideN.xml` → zip |
+| **Read** content | `markitdown deck.pptx` (one block per slide under `<!-- Slide number: N -->` markers); visual grid: `python scripts/thumbnail.py deck.pptx` |
 
----
+## Scripts
 
-## Reading Content
+Paths are relative to this skill's directory. Everything else is plain Python, `node`, or shell.
+
+| Script | What it does |
+|---|---|
+| `scripts/thumbnail.py deck.pptx [prefix]` | Labeled grid of every slide, for picking template layouts. `.pptx` only. Pass `prefix` — it defaults to `thumbnails`, which overwrites the grids of any other deck done in the same directory |
+| `scripts/add_slide.py unpacked/ slide2.xml [--after slideN.xml]` | Duplicate a slide (or a `slideLayoutN.xml`) with all the package bookkeeping. Also takes a `.pptx` directly with `-o out.pptx` |
+| `scripts/clean.py unpacked/` | Delete slides, media, and rels no longer referenced. Run **after** `<p:sldIdLst>` is final |
+| `scripts/office/validate.py deck.pptx [--original src.pptx]` | Schema, relationship, content-type, chart and slide checks; each failure names its fix. Pass `--original` for any template-derived deck — it baselines the schema checks against the template, so the template's own XSD errors don't read as yours |
+| `scripts/office/soffice.py --headless --convert-to pdf deck.pptx` | LibreOffice wrapper — bare `soffice` hangs in this sandbox |
+
+## Creating with pptxgenjs — gotchas
+
+`pptxgenjs` is preinstalled — do not run `npm install` first; write the script and `require('pptxgenjs')` directly. Only if that require fails: `npm install pptxgenjs`. The model knows the API; these are the footguns:
+
+- **Set `pres.layout` before adding slides.** The default canvas is `LAYOUT_16x9` = **10" × 5.625"**, not 13.3" wide. Coordinates past the edge are written, not clamped — the shape just isn't on the slide. (`LAYOUT_WIDE` is 13.3" × 7.5".)
+- **Hex colors: never `#`, never 8 digits.** `color: "FF0000"`. Both `"#FF0000"` and alpha baked into the hex (`"00000020"`) **corrupt the file**. For translucency: `transparency: 0-100` on fills and images, `opacity: 0.0-1.0` on shadows — each is silently ignored on the other.
+- **pptxgenjs mutates option objects in place** (converts values to EMU on first use). Never share one `shadow`/options object across two `add*` calls — build a fresh object each time.
+- **Shadow `offset` must be ≥ 0** — a negative offset corrupts the file. To cast a shadow upward, use `angle: 270` with a positive offset.
+- **`letterSpacing` is silently ignored** — the real option is `charSpacing`.
+- **Lists:** `bullet: true` on each item, never a literal `•` (renders double bullets). Set `breakLine: true` on every array item except the last. Space bulleted paragraphs with `paraSpaceAfter`, not `lineSpacing` (huge gaps).
+- **One `new pptxgen()` per output file** — never reuse an instance.
+- **`rectRadius` only works on `ROUNDED_RECTANGLE`**, not `RECTANGLE`.
+- **Gradient fills aren't supported** — use a gradient image as the background instead.
+- **Text boxes have built-in internal padding** — set `margin: 0` whenever text must align with a shape, line, or icon at the same x.
+- **Speaker notes go in `slide.addNotes("...")`** (plain text, once per slide), never in a text box on the slide.
+- **Keep charts native.** Use `addChart()` for everything PowerPoint can chart (pass an array of `{type, data, options}` for combos). For PowerPoint-native features the library doesn't expose (trendlines, error bars), compute the extra series yourself or post-process the generated OOXML — do not fall back to a rendered image. Only chart types PowerPoint has no native form for (Sankey, network, chord) go in as images.
+- **Default charts render bare** — no title, no data labels, dated palette. Set `showTitle` + `title`, `showValue: true` + `dataLabelPosition`, `chartColors: [...]` from your palette, and quiet the frame (`catAxisLabelColor`/`valAxisLabelColor`, `valGridLine: { color, size }`, `catGridLine: { style: "none" }`, `showLegend: false` for a single series).
+- **On a stacked bar or column chart, `dataLabelPosition` must be `ctr`, `inEnd`, or `inBase`.** `outEnd` **corrupts the file**.
+- **A combo series using `secondaryValAxis`/`secondaryCatAxis` needs both `valAxes` and `catAxes` on the chart options, two entries each.** Without them pptxgenjs writes axis *ids* it never declares, and PowerPoint **discards that chart** and reports the file as corrupt. Supplying only `valAxes` is not enough.
+- **After `writeFile()`, run `python scripts/office/validate.py deck.pptx`.** It reports the two chart faults above and the slide-XML defects PowerPoint refuses, and names the fix for each. Fix them in your generator, not by hand-editing the packed XML.
+- **Never reorder the children of `<p:presentation>`.** pptxgenjs writes `<p:notesMasterIdLst>` right after `<p:sldIdLst>` and points both masters at one theme part. PowerPoint reads that happily — move the element and the same deck becomes unopenable.
+- **Icons:** render `react-icons` to SVG (`ReactDOMServer.renderToStaticMarkup`), rasterize with `sharp` at ≥256px, and insert via `addImage({ data: "image/png;base64," + buf.toString("base64") })` — the `image/png;base64,` prefix is required (`react-icons`, `react`, `react-dom`, and `sharp` are preinstalled — `npm install react-icons react react-dom sharp` only if a require fails).
+
+## Editing existing decks and templates
+
+Pick layouts first: `python scripts/thumbnail.py template.pptx template-thumbs` writes a labeled grid of every slide and prints the file(s) it created — `template-thumbs.jpg`, split into `template-thumbs-N.jpg` past 12 slides. **Always pass that second argument, named after the deck.** It defaults to `thumbnails`, so two decks thumbnailed in one directory silently overwrite each other's grids — the first deck's are simply gone (template analysis only — visual QA needs the full-resolution renders from [Converting to Images](#converting-to-images); it only accepts `.pptx`, so copy a `.potx` to a `.pptx` name first). Use it with `markitdown` to map each content section onto a template slide, and vary the layouts — don't put every section on the same title-and-bullets slide.
 
 ```bash
-# Text extraction
-python -m markitdown presentation.pptx
-
-# Visual overview
-python scripts/thumbnail.py presentation.pptx
-
-# Raw XML
-python scripts/office/unpack.py presentation.pptx unpacked/
+python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" deck.pptx
+python scripts/add_slide.py unpacked/ slide2.xml --after slide2.xml   # duplicate a slide (or slideLayoutN.xml); prints the new slide's path
+# reorder / delete slides = edit <p:sldIdLst> in ppt/presentation.xml
+python scripts/clean.py unpacked/                                     # after deletions: removes orphaned slides, media, rels
+# edit slide content in ppt/slides/slideN.xml
+(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .)           # zip from INSIDE the dir; rm first or deleted parts survive
+python scripts/office/validate.py out.pptx --original deck.pptx
 ```
 
----
+- **Do all structural work — add, delete, reorder — before editing any slide's content.** `add_slide.py` copies a slide file verbatim, so duplicating after you edit clones the edited content; and `clean.py` deletes any slide missing from `<p:sldIdLst>`, including one you just wrote.
+- **Never copy a slide file by hand** — `add_slide.py` does every registration a new slide needs and reports what it made (`Created ppt/slides/slide17.xml from slide2.xml`). It also works directly on a file: `add_slide.py deck.pptx slide2.xml -o out.pptx` — **pass `-o`, or it rewrites the input deck in place.** A duplicated slide still *references* its source's chart/SmartArt/embedded-object parts rather than cloning them, so editing one slide's chart changes the other's.
+- **If you use `python-pptx`**, three things it won't do: duplicate a slide (its only entry point is `add_slide(layout)`), preserve formatting through `text_frame.text = "..."` (that collapses the paragraph to a single unstyled run — assign `run.text` instead), or read the SVG/EMF most template art uses (`add_picture` raises `UnidentifiedImageError`).
+- Legacy `.ppt` must be converted first: `python scripts/office/soffice.py --headless --convert-to pptx file.ppt`. `.potx` templates unpack and pack identically — keep the `.potx` extension on the output.
+- To reuse a template icon or image, duplicate a slide or layout that already contains it.
 
-## Editing Workflow
+When filling in a template:
 
-**Read [editing.md](editing.md) for full details.**
-
-1. Analyze template with `thumbnail.py`
-2. Unpack → manipulate slides → edit content → clean → pack
-
----
-
-## Creating from Scratch
-
-**Read [pptxgenjs.md](pptxgenjs.md) for full details.**
-
-Use when no template or reference presentation is available.
-
----
+- If you script an XML transform, parse with `defusedxml.minidom` — round-tripping OOXML through `xml.etree.ElementTree` rewrites namespace prefixes and corrupts the deck.
+- **Template slots ≠ source items.** If the template shows 4 team members and you have 3, delete the 4th member's entire group (image + text boxes), not just its text — then check for orphaned visuals in QA.
+- One `<a:p>` per list item — never concatenate items into a single paragraph. Copy the sibling `<a:pPr>` to preserve spacing, and put `b="1"` on the `<a:rPr>` of titles, section headers, and inline labels (`Status:`, `Owner:`).
+- Let bullets inherit from the layout; only add `<a:buChar>`, `<a:buAutoNum>` (numbered), or `<a:buNone>` to override — never a literal `•` in the text.
+- Text with leading or trailing spaces needs `xml:space="preserve"` on its `<a:t>`.
 
 ## Design Ideas
 
@@ -57,7 +86,7 @@ Use when no template or reference presentation is available.
 - **Pick a bold, content-informed color palette**: The palette should feel designed for THIS topic. If swapping your colors into a completely different presentation would still "work," you haven't made specific enough choices.
 - **Dominance over equality**: One color should dominate (60-70% visual weight), with 1-2 supporting tones and one sharp accent. Never give all colors equal weight.
 - **Dark/light contrast**: Dark backgrounds for title + conclusion slides, light for content ("sandwich" structure). Or commit to dark throughout for a premium feel.
-- **Commit to a visual motif**: Pick ONE distinctive element and repeat it — rounded image frames, icons in colored circles, thick single-side borders. Carry it across every slide.
+- **Commit to a visual motif**: Pick ONE distinctive element and repeat it — rounded image frames, icons in colored circles. Carry it across every slide. **Do not use a color bar or accent stripe as your motif** (see Avoid list).
 
 ### Color Palettes
 
@@ -97,18 +126,13 @@ Choose colors that match your topic — don't default to generic blue. Use these
 
 ### Typography
 
-**Choose an interesting font pairing** — don't default to Arial. Pick a header font with personality and pair it with a clean body font.
+**Font names you write into the .pptx are rendered by the user's PowerPoint, not by this environment.** Your visual QA renders via LibreOffice, which substitutes fonts it doesn't have — and for some fonts the substitute has different widths, so your QA preview can show text overflow (or fit) that the real deck won't have. To keep your QA trustworthy:
 
-| Header Font | Body Font |
-|-------------|-----------|
-| Georgia | Calibri |
-| Arial Black | Arial |
-| Calibri | Calibri Light |
-| Cambria | Calibri |
-| Trebuchet MS | Calibri |
-| Impact | Arial |
-| Palatino | Garamond |
-| Consolas | Calibri |
+- **Safe fonts** (render true-to-width in QA *and* ship with Office): **Arial, Calibri, Cambria, Times New Roman, Courier New, Bookman Old Style, Century Schoolbook**. Use these for body text and anything where fit matters.
+- **Headers with personality at zero QA risk**: pair a safe-list serif header (Cambria, Bookman Old Style, Century Schoolbook) with a safe-list sans body (Calibri or Arial). You get visual contrast without giving up reliable overflow checks.
+- **If the user asks for a font outside the safe list** (e.g. Georgia or Trebuchet MS): use it where the user asked, but size those containers with extra slack (~10%) and don't trust QA text-fit on those elements — the preview of that font is approximate. If the user hasn't specified, prefer safe-list fonts for body text.
+- **QA-unreliable fonts** (substitute has different widths — overflow checks can be wrong): Georgia, Trebuchet MS, Impact, Arial Black, Garamond, Consolas, Palatino Linotype. Calibri Light substitution varies by environment; treat as QA-unreliable. Fine for titles/accents with slack; don't trust QA text-fit on these.
+- **Never default to Aptos** — Office's post-2023 default has no metric-compatible substitute here *and* is missing from older Office installs, so it's unreliable on both ends.
 
 | Element | Size |
 |---------|------|
@@ -135,19 +159,18 @@ Choose colors that match your topic — don't default to generic blue. Use these
 - **Don't forget text box padding** — when aligning lines or shapes with text edges, set `margin: 0` on the text box or offset the shape to account for padding
 - **Don't use low-contrast elements** — icons AND text need strong contrast against the background; avoid light text on light backgrounds or dark text on dark backgrounds
 - **NEVER use accent lines under titles** — these are a hallmark of AI-generated slides; use whitespace or background color instead
-
----
+- **NEVER add decorative color bars or accent stripes** — this includes: header/footer bars spanning the slide width, vertical sidebar stripes down one edge of the slide, thin accent stripes along one edge of a card or content block, and "single-side borders" on rectangles. These read as AI-generated filler. If you want to set a card apart, use a subtle background tint, a drop shadow, or an icon — not an edge stripe.
+- **Don't default to cream/beige backgrounds** — when no background is specified, use white (`FFFFFF`) or the user's brand palette; avoid warm-neutral defaults like `F5F5DC`, `FAF0E6`, `FAEBD7`, `FFF8E1`
+- **Don't ship text that overflows its shape** — if text doesn't fit, reduce font size, split across slides, or enlarge the container; never leave content cut off or spilling past bounds
 
 ## QA (Required)
 
-**Assume there are problems. Your job is to find them.**
-
-Your first render is almost never correct. Approach QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you weren't looking hard enough.
+Your first render usually has a few real issues — overlaps, overflow, misalignment. Find and fix those, re-render only the slides you changed, and stop.
 
 ### Content QA
 
 ```bash
-python -m markitdown output.pptx
+markitdown output.pptx
 ```
 
 Check for missing content, typos, wrong order.
@@ -155,78 +178,61 @@ Check for missing content, typos, wrong order.
 **When using templates, check for leftover placeholder text:**
 
 ```bash
-python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|this.*(page|slide).*layout"
+markitdown output.pptx | grep -iE "\bx{3,}\b|lorem|ipsum|\bTODO|\[insert|this.*(page|slide).*layout"
 ```
 
 If grep returns results, fix them before declaring success.
 
+### File QA (required)
+
+```bash
+python scripts/office/validate.py output.pptx                      # built from scratch
+python scripts/office/validate.py output.pptx --original src.pptx  # built from a template
+```
+
+**If the deck came from a template, always pass `--original`.** A template may itself
+contain parts the XSD rejects, so a bare run can report failures you never caused — and
+a genuine regression can hide among them. `--original` baselines
+the schema and slide checks against the template, suppressing errors it already had.
+The structural checks — relationships, content types, charts — ignore `--original` and
+report template-inherited problems either way, so read those on their own merits.
+
+pptxgenjs emits chart XML PowerPoint refuses to open, and every other tool
+accepts: python-pptx opens those decks, LibreOffice renders them, the XSD
+passes them. Every failure names its fix. Fix it in the generator and rebuild.
+
 ### Visual QA
 
-**⚠️ USE SUBAGENTS** — even for 2-3 slides. You've been staring at the code and will see what you expect, not what's there. Subagents have fresh eyes.
+Convert the slides to images (see [Converting to Images](#converting-to-images)) and inspect every one. After staring at the generating code you tend to see what you expect rather than what rendered, so look at the images fresh (a subagent works well for this if you have one). User-visible defects to look for:
 
-Convert slides to images (see [Converting to Images](#converting-to-images)), then use this prompt:
-
-```
-Visually inspect these slides. Assume there are issues — find them.
-
-Look for:
+- **Text overflow or text cut off at a box or slide boundary — check this first.** It is the most common defect and always user-visible. (For a font the previewer renders unreliably per Typography, the preview is approximate: trust the ~10% slack you left, not its apparent fit.)
 - Overlapping elements (text through shapes, lines through words, stacked elements)
-- Text overflow or cut off at edges/box boundaries
-- Decorative lines positioned for single-line text but title wrapped to two lines
 - Source citations or footers colliding with content above
 - Elements too close (< 0.3" gaps) or cards/sections nearly touching
 - Uneven gaps (large empty area in one place, cramped in another)
 - Insufficient margin from slide edges (< 0.5")
 - Columns or similar elements not aligned consistently
 - Low-contrast text (e.g., light gray text on cream-colored background)
+- Template decoration mispositioned after text replacement — e.g., a title underline positioned for one line, but the replaced title wrapped to two
 - Low-contrast icons (e.g., dark icons on dark backgrounds without a contrasting circle)
 - Text boxes too narrow causing excessive wrapping
 - Leftover placeholder content
 
-For each slide, list issues or areas of concern, even if minor.
-
-Read and analyze these images:
-1. /path/to/slide-01.jpg (Expected: [brief description])
-2. /path/to/slide-02.jpg (Expected: [brief description])
-
-Report ALL issues found, including minor ones.
-```
-
-### Verification Loop
-
-1. Generate slides → Convert to images → Inspect
-2. **List issues found** (if none found, look again more critically)
-3. Fix issues
-4. **Re-verify affected slides** — one fix often creates another problem
-5. Repeat until a full pass reveals no new issues
-
-**Do not declare success until you've completed at least one fix-and-verify cycle.**
-
----
-
 ## Converting to Images
 
 Convert presentations to individual slide images for visual inspection:
 
 ```bash
 python scripts/office/soffice.py --headless --convert-to pdf output.pptx
+rm -f slide-*.jpg
 pdftoppm -jpeg -r 150 output.pdf slide
+ls -1 "$PWD"/slide-*.jpg
 ```
 
-This creates `slide-01.jpg`, `slide-02.jpg`, etc.
+**Pass the absolute paths printed above directly to the view tool.** The `rm` clears stale images from prior runs. `pdftoppm` zero-pads based on page count: `slide-1.jpg` for decks under 10 pages, `slide-01.jpg` for 10-99, `slide-001.jpg` for 100+.
 
-To re-render specific slides after fixes:
-
-```bash
-pdftoppm -jpeg -r 150 -f N -l N output.pdf slide-fixed
-```
-
----
+**After fixes, rerun all four commands above** — the PDF must be regenerated from the edited `.pptx` before `pdftoppm` can reflect your changes.
 
 ## Dependencies
 
-- `pip install "markitdown[pptx]"` - text extraction
-- `pip install Pillow` - thumbnail grids
-- `npm install -g pptxgenjs` - creating from scratch
-- LibreOffice (`soffice`) - PDF conversion (auto-configured for sandboxed environments via `scripts/office/soffice.py`)
-- Poppler (`pdftoppm`) - PDF to images
+`pptxgenjs` (npm, preinstalled — install only if `require('pptxgenjs')` fails) · `markitdown[pptx]`, `Pillow`, `defusedxml`, `lxml` (pip — text dump, thumbnail, clean, validate) · LibreOffice (`soffice`, auto-configured for sandboxed environments via `scripts/office/soffice.py`) · `pdftoppm` (Poppler)

skills/pptx/editing.md

@@ -1,205 +0,0 @@
-# Editing Presentations
-
-## Template-Based Workflow
-
-When using an existing presentation as a template:
-
-1. **Analyze existing slides**:
-   ```bash
-   python scripts/thumbnail.py template.pptx
-   python -m markitdown template.pptx
-   ```
-   Review `thumbnails.jpg` to see layouts, and markitdown output to see placeholder text.
-
-2. **Plan slide mapping**: For each content section, choose a template slide.
-
-   ⚠️ **USE VARIED LAYOUTS** — monotonous presentations are a common failure mode. Don't default to basic title + bullet slides. Actively seek out:
-   - Multi-column layouts (2-column, 3-column)
-   - Image + text combinations
-   - Full-bleed images with text overlay
-   - Quote or callout slides
-   - Section dividers
-   - Stat/number callouts
-   - Icon grids or icon + text rows
-
-   **Avoid:** Repeating the same text-heavy layout for every slide.
-
-   Match content type to layout style (e.g., key points → bullet slide, team info → multi-column, testimonials → quote slide).
-
-3. **Unpack**: `python scripts/office/unpack.py template.pptx unpacked/`
-
-4. **Build presentation** (do this yourself, not with subagents):
-   - Delete unwanted slides (remove from `<p:sldIdLst>`)
-   - Duplicate slides you want to reuse (`add_slide.py`)
-   - Reorder slides in `<p:sldIdLst>`
-   - **Complete all structural changes before step 5**
-
-5. **Edit content**: Update text in each `slide{N}.xml`.
-   **Use subagents here if available** — slides are separate XML files, so subagents can edit in parallel.
-
-6. **Clean**: `python scripts/clean.py unpacked/`
-
-7. **Pack**: `python scripts/office/pack.py unpacked/ output.pptx --original template.pptx`
-
----
-
-## Scripts
-
-| Script | Purpose |
-|--------|---------|
-| `unpack.py` | Extract and pretty-print PPTX |
-| `add_slide.py` | Duplicate slide or create from layout |
-| `clean.py` | Remove orphaned files |
-| `pack.py` | Repack with validation |
-| `thumbnail.py` | Create visual grid of slides |
-
-### unpack.py
-
-```bash
-python scripts/office/unpack.py input.pptx unpacked/
-```
-
-Extracts PPTX, pretty-prints XML, escapes smart quotes.
-
-### add_slide.py
-
-```bash
-python scripts/add_slide.py unpacked/ slide2.xml      # Duplicate slide
-python scripts/add_slide.py unpacked/ slideLayout2.xml # From layout
-```
-
-Prints `<p:sldId>` to add to `<p:sldIdLst>` at desired position.
-
-### clean.py
-
-```bash
-python scripts/clean.py unpacked/
-```
-
-Removes slides not in `<p:sldIdLst>`, unreferenced media, orphaned rels.
-
-### pack.py
-
-```bash
-python scripts/office/pack.py unpacked/ output.pptx --original input.pptx
-```
-
-Validates, repairs, condenses XML, re-encodes smart quotes.
-
-### thumbnail.py
-
-```bash
-python scripts/thumbnail.py input.pptx [output_prefix] [--cols N]
-```
-
-Creates `thumbnails.jpg` with slide filenames as labels. Default 3 columns, max 12 per grid.
-
-**Use for template analysis only** (choosing layouts). For visual QA, use `soffice` + `pdftoppm` to create full-resolution individual slide images—see SKILL.md.
-
----
-
-## Slide Operations
-
-Slide order is in `ppt/presentation.xml` → `<p:sldIdLst>`.
-
-**Reorder**: Rearrange `<p:sldId>` elements.
-
-**Delete**: Remove `<p:sldId>`, then run `clean.py`.
-
-**Add**: Use `add_slide.py`. Never manually copy slide files—the script handles notes references, Content_Types.xml, and relationship IDs that manual copying misses.
-
----
-
-## Editing Content
-
-**Subagents:** If available, use them here (after completing step 4). Each slide is a separate XML file, so subagents can edit in parallel. In your prompt to subagents, include:
-- The slide file path(s) to edit
-- **"Use the Edit tool for all changes"**
-- The formatting rules and common pitfalls below
-
-For each slide:
-1. Read the slide's XML
-2. Identify ALL placeholder content—text, images, charts, icons, captions
-3. Replace each placeholder with final content
-
-**Use the Edit tool, not sed or Python scripts.** The Edit tool forces specificity about what to replace and where, yielding better reliability.
-
-### Formatting Rules
-
-- **Bold all headers, subheadings, and inline labels**: Use `b="1"` on `<a:rPr>`. This includes:
-  - Slide titles
-  - Section headers within a slide
-  - Inline labels like (e.g.: "Status:", "Description:") at the start of a line
-- **Never use unicode bullets (•)**: Use proper list formatting with `<a:buChar>` or `<a:buAutoNum>`
-- **Bullet consistency**: Let bullets inherit from the layout. Only specify `<a:buChar>` or `<a:buNone>`.
-
----
-
-## Common Pitfalls
-
-### Template Adaptation
-
-When source content has fewer items than the template:
-- **Remove excess elements entirely** (images, shapes, text boxes), don't just clear text
-- Check for orphaned visuals after clearing text content
-- Run visual QA to catch mismatched counts
-
-When replacing text with different length content:
-- **Shorter replacements**: Usually safe
-- **Longer replacements**: May overflow or wrap unexpectedly
-- Test with visual QA after text changes
-- Consider truncating or splitting content to fit the template's design constraints
-
-**Template slots ≠ Source items**: If template has 4 team members but source has 3 users, delete the 4th member's entire group (image + text boxes), not just the text.
-
-### Multi-Item Content
-
-If source has multiple items (numbered lists, multiple sections), create separate `<a:p>` elements for each — **never concatenate into one string**.
-
-**❌ WRONG** — all items in one paragraph:
-```xml
-<a:p>
-  <a:r><a:rPr .../><a:t>Step 1: Do the first thing. Step 2: Do the second thing.</a:t></a:r>
-</a:p>
-```
-
-**✅ CORRECT** — separate paragraphs with bold headers:
-```xml
-<a:p>
-  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
-  <a:r><a:rPr lang="en-US" sz="2799" b="1" .../><a:t>Step 1</a:t></a:r>
-</a:p>
-<a:p>
-  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
-  <a:r><a:rPr lang="en-US" sz="2799" .../><a:t>Do the first thing.</a:t></a:r>
-</a:p>
-<a:p>
-  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
-  <a:r><a:rPr lang="en-US" sz="2799" b="1" .../><a:t>Step 2</a:t></a:r>
-</a:p>
-<!-- continue pattern -->
-```
-
-Copy `<a:pPr>` from the original paragraph to preserve line spacing. Use `b="1"` on headers.
-
-### Smart Quotes
-
-Handled automatically by unpack/pack. But the Edit tool converts smart quotes to ASCII.
-
-**When adding new text with quotes, use XML entities:**
-
-```xml
-<a:t>the &#x201C;Agreement&#x201D;</a:t>
-```
-
-| Character | Name | Unicode | XML Entity |
-|-----------|------|---------|------------|
-| `“` | Left double quote | U+201C | `&#x201C;` |
-| `”` | Right double quote | U+201D | `&#x201D;` |
-| `‘` | Left single quote | U+2018 | `&#x2018;` |
-| `’` | Right single quote | U+2019 | `&#x2019;` |
-
-### Other
-
-- **Whitespace**: Use `xml:space="preserve"` on `<a:t>` with leading/trailing spaces
-- **XML parsing**: Use `defusedxml.minidom`, not `xml.etree.ElementTree` (corrupts namespaces)

skills/pptx/pptxgenjs.md

@@ -1,420 +0,0 @@
-# PptxGenJS Tutorial
-
-## Setup & Basic Structure
-
-```javascript
-const pptxgen = require("pptxgenjs");
-
-let pres = new pptxgen();
-pres.layout = 'LAYOUT_16x9';  // or 'LAYOUT_16x10', 'LAYOUT_4x3', 'LAYOUT_WIDE'
-pres.author = 'Your Name';
-pres.title = 'Presentation Title';
-
-let slide = pres.addSlide();
-slide.addText("Hello World!", { x: 0.5, y: 0.5, fontSize: 36, color: "363636" });
-
-pres.writeFile({ fileName: "Presentation.pptx" });
-```
-
-## Layout Dimensions
-
-Slide dimensions (coordinates in inches):
-- `LAYOUT_16x9`: 10" × 5.625" (default)
-- `LAYOUT_16x10`: 10" × 6.25"
-- `LAYOUT_4x3`: 10" × 7.5"
-- `LAYOUT_WIDE`: 13.3" × 7.5"
-
----
-
-## Text & Formatting
-
-```javascript
-// Basic text
-slide.addText("Simple Text", {
-  x: 1, y: 1, w: 8, h: 2, fontSize: 24, fontFace: "Arial",
-  color: "363636", bold: true, align: "center", valign: "middle"
-});
-
-// Character spacing (use charSpacing, not letterSpacing which is silently ignored)
-slide.addText("SPACED TEXT", { x: 1, y: 1, w: 8, h: 1, charSpacing: 6 });
-
-// Rich text arrays
-slide.addText([
-  { text: "Bold ", options: { bold: true } },
-  { text: "Italic ", options: { italic: true } }
-], { x: 1, y: 3, w: 8, h: 1 });
-
-// Multi-line text (requires breakLine: true)
-slide.addText([
-  { text: "Line 1", options: { breakLine: true } },
-  { text: "Line 2", options: { breakLine: true } },
-  { text: "Line 3" }  // Last item doesn't need breakLine
-], { x: 0.5, y: 0.5, w: 8, h: 2 });
-
-// Text box margin (internal padding)
-slide.addText("Title", {
-  x: 0.5, y: 0.3, w: 9, h: 0.6,
-  margin: 0  // Use 0 when aligning text with other elements like shapes or icons
-});
-```
-
-**Tip:** Text boxes have internal margin by default. Set `margin: 0` when you need text to align precisely with shapes, lines, or icons at the same x-position.
-
----
-
-## Lists & Bullets
-
-```javascript
-// ✅ CORRECT: Multiple bullets
-slide.addText([
-  { text: "First item", options: { bullet: true, breakLine: true } },
-  { text: "Second item", options: { bullet: true, breakLine: true } },
-  { text: "Third item", options: { bullet: true } }
-], { x: 0.5, y: 0.5, w: 8, h: 3 });
-
-// ❌ WRONG: Never use unicode bullets
-slide.addText("• First item", { ... });  // Creates double bullets
-
-// Sub-items and numbered lists
-{ text: "Sub-item", options: { bullet: true, indentLevel: 1 } }
-{ text: "First", options: { bullet: { type: "number" }, breakLine: true } }
-```
-
----
-
-## Shapes
-
-```javascript
-slide.addShape(pres.shapes.RECTANGLE, {
-  x: 0.5, y: 0.8, w: 1.5, h: 3.0,
-  fill: { color: "FF0000" }, line: { color: "000000", width: 2 }
-});
-
-slide.addShape(pres.shapes.OVAL, { x: 4, y: 1, w: 2, h: 2, fill: { color: "0000FF" } });
-
-slide.addShape(pres.shapes.LINE, {
-  x: 1, y: 3, w: 5, h: 0, line: { color: "FF0000", width: 3, dashType: "dash" }
-});
-
-// With transparency
-slide.addShape(pres.shapes.RECTANGLE, {
-  x: 1, y: 1, w: 3, h: 2,
-  fill: { color: "0088CC", transparency: 50 }
-});
-
-// Rounded rectangle (rectRadius only works with ROUNDED_RECTANGLE, not RECTANGLE)
-// ⚠️ Don't pair with rectangular accent overlays — they won't cover rounded corners. Use RECTANGLE instead.
-slide.addShape(pres.shapes.ROUNDED_RECTANGLE, {
-  x: 1, y: 1, w: 3, h: 2,
-  fill: { color: "FFFFFF" }, rectRadius: 0.1
-});
-
-// With shadow
-slide.addShape(pres.shapes.RECTANGLE, {
-  x: 1, y: 1, w: 3, h: 2,
-  fill: { color: "FFFFFF" },
-  shadow: { type: "outer", color: "000000", blur: 6, offset: 2, angle: 135, opacity: 0.15 }
-});
-```
-
-Shadow options:
-
-| Property | Type | Range | Notes |
-|----------|------|-------|-------|
-| `type` | string | `"outer"`, `"inner"` | |
-| `color` | string | 6-char hex (e.g. `"000000"`) | No `#` prefix, no 8-char hex — see Common Pitfalls |
-| `blur` | number | 0-100 pt | |
-| `offset` | number | 0-200 pt | **Must be non-negative** — negative values corrupt the file |
-| `angle` | number | 0-359 degrees | Direction the shadow falls (135 = bottom-right, 270 = upward) |
-| `opacity` | number | 0.0-1.0 | Use this for transparency, never encode in color string |
-
-To cast a shadow upward (e.g. on a footer bar), use `angle: 270` with a positive offset — do **not** use a negative offset.
-
-**Note**: Gradient fills are not natively supported. Use a gradient image as a background instead.
-
----
-
-## Images
-
-### Image Sources
-
-```javascript
-// From file path
-slide.addImage({ path: "images/chart.png", x: 1, y: 1, w: 5, h: 3 });
-
-// From URL
-slide.addImage({ path: "https://example.com/image.jpg", x: 1, y: 1, w: 5, h: 3 });
-
-// From base64 (faster, no file I/O)
-slide.addImage({ data: "image/png;base64,iVBORw0KGgo...", x: 1, y: 1, w: 5, h: 3 });
-```
-
-### Image Options
-
-```javascript
-slide.addImage({
-  path: "image.png",
-  x: 1, y: 1, w: 5, h: 3,
-  rotate: 45,              // 0-359 degrees
-  rounding: true,          // Circular crop
-  transparency: 50,        // 0-100
-  flipH: true,             // Horizontal flip
-  flipV: false,            // Vertical flip
-  altText: "Description",  // Accessibility
-  hyperlink: { url: "https://example.com" }
-});
-```
-
-### Image Sizing Modes
-
-```javascript
-// Contain - fit inside, preserve ratio
-{ sizing: { type: 'contain', w: 4, h: 3 } }
-
-// Cover - fill area, preserve ratio (may crop)
-{ sizing: { type: 'cover', w: 4, h: 3 } }
-
-// Crop - cut specific portion
-{ sizing: { type: 'crop', x: 0.5, y: 0.5, w: 2, h: 2 } }
-```
-
-### Calculate Dimensions (preserve aspect ratio)
-
-```javascript
-const origWidth = 1978, origHeight = 923, maxHeight = 3.0;
-const calcWidth = maxHeight * (origWidth / origHeight);
-const centerX = (10 - calcWidth) / 2;
-
-slide.addImage({ path: "image.png", x: centerX, y: 1.2, w: calcWidth, h: maxHeight });
-```
-
-### Supported Formats
-
-- **Standard**: PNG, JPG, GIF (animated GIFs work in Microsoft 365)
-- **SVG**: Works in modern PowerPoint/Microsoft 365
-
----
-
-## Icons
-
-Use react-icons to generate SVG icons, then rasterize to PNG for universal compatibility.
-
-### Setup
-
-```javascript
-const React = require("react");
-const ReactDOMServer = require("react-dom/server");
-const sharp = require("sharp");
-const { FaCheckCircle, FaChartLine } = require("react-icons/fa");
-
-function renderIconSvg(IconComponent, color = "#000000", size = 256) {
-  return ReactDOMServer.renderToStaticMarkup(
-    React.createElement(IconComponent, { color, size: String(size) })
-  );
-}
-
-async function iconToBase64Png(IconComponent, color, size = 256) {
-  const svg = renderIconSvg(IconComponent, color, size);
-  const pngBuffer = await sharp(Buffer.from(svg)).png().toBuffer();
-  return "image/png;base64," + pngBuffer.toString("base64");
-}
-```
-
-### Add Icon to Slide
-
-```javascript
-const iconData = await iconToBase64Png(FaCheckCircle, "#4472C4", 256);
-
-slide.addImage({
-  data: iconData,
-  x: 1, y: 1, w: 0.5, h: 0.5  // Size in inches
-});
-```
-
-**Note**: Use size 256 or higher for crisp icons. The size parameter controls the rasterization resolution, not the display size on the slide (which is set by `w` and `h` in inches).
-
-### Icon Libraries
-
-Install: `npm install -g react-icons react react-dom sharp`
-
-Popular icon sets in react-icons:
-- `react-icons/fa` - Font Awesome
-- `react-icons/md` - Material Design
-- `react-icons/hi` - Heroicons
-- `react-icons/bi` - Bootstrap Icons
-
----
-
-## Slide Backgrounds
-
-```javascript
-// Solid color
-slide.background = { color: "F1F1F1" };
-
-// Color with transparency
-slide.background = { color: "FF3399", transparency: 50 };
-
-// Image from URL
-slide.background = { path: "https://example.com/bg.jpg" };
-
-// Image from base64
-slide.background = { data: "image/png;base64,iVBORw0KGgo..." };
-```
-
----
-
-## Tables
-
-```javascript
-slide.addTable([
-  ["Header 1", "Header 2"],
-  ["Cell 1", "Cell 2"]
-], {
-  x: 1, y: 1, w: 8, h: 2,
-  border: { pt: 1, color: "999999" }, fill: { color: "F1F1F1" }
-});
-
-// Advanced with merged cells
-let tableData = [
-  [{ text: "Header", options: { fill: { color: "6699CC" }, color: "FFFFFF", bold: true } }, "Cell"],
-  [{ text: "Merged", options: { colspan: 2 } }]
-];
-slide.addTable(tableData, { x: 1, y: 3.5, w: 8, colW: [4, 4] });
-```
-
----
-
-## Charts
-
-```javascript
-// Bar chart
-slide.addChart(pres.charts.BAR, [{
-  name: "Sales", labels: ["Q1", "Q2", "Q3", "Q4"], values: [4500, 5500, 6200, 7100]
-}], {
-  x: 0.5, y: 0.6, w: 6, h: 3, barDir: 'col',
-  showTitle: true, title: 'Quarterly Sales'
-});
-
-// Line chart
-slide.addChart(pres.charts.LINE, [{
-  name: "Temp", labels: ["Jan", "Feb", "Mar"], values: [32, 35, 42]
-}], { x: 0.5, y: 4, w: 6, h: 3, lineSize: 3, lineSmooth: true });
-
-// Pie chart
-slide.addChart(pres.charts.PIE, [{
-  name: "Share", labels: ["A", "B", "Other"], values: [35, 45, 20]
-}], { x: 7, y: 1, w: 5, h: 4, showPercent: true });
-```
-
-### Better-Looking Charts
-
-Default charts look dated. Apply these options for a modern, clean appearance:
-
-```javascript
-slide.addChart(pres.charts.BAR, chartData, {
-  x: 0.5, y: 1, w: 9, h: 4, barDir: "col",
-
-  // Custom colors (match your presentation palette)
-  chartColors: ["0D9488", "14B8A6", "5EEAD4"],
-
-  // Clean background
-  chartArea: { fill: { color: "FFFFFF" }, roundedCorners: true },
-
-  // Muted axis labels
-  catAxisLabelColor: "64748B",
-  valAxisLabelColor: "64748B",
-
-  // Subtle grid (value axis only)
-  valGridLine: { color: "E2E8F0", size: 0.5 },
-  catGridLine: { style: "none" },
-
-  // Data labels on bars
-  showValue: true,
-  dataLabelPosition: "outEnd",
-  dataLabelColor: "1E293B",
-
-  // Hide legend for single series
-  showLegend: false,
-});
-```
-
-**Key styling options:**
-- `chartColors: [...]` - hex colors for series/segments
-- `chartArea: { fill, border, roundedCorners }` - chart background
-- `catGridLine/valGridLine: { color, style, size }` - grid lines (`style: "none"` to hide)
-- `lineSmooth: true` - curved lines (line charts)
-- `legendPos: "r"` - legend position: "b", "t", "l", "r", "tr"
-
----
-
-## Slide Masters
-
-```javascript
-pres.defineSlideMaster({
-  title: 'TITLE_SLIDE', background: { color: '283A5E' },
-  objects: [{
-    placeholder: { options: { name: 'title', type: 'title', x: 1, y: 2, w: 8, h: 2 } }
-  }]
-});
-
-let titleSlide = pres.addSlide({ masterName: "TITLE_SLIDE" });
-titleSlide.addText("My Title", { placeholder: "title" });
-```
-
----
-
-## Common Pitfalls
-
-⚠️ These issues cause file corruption, visual bugs, or broken output. Avoid them.
-
-1. **NEVER use "#" with hex colors** - causes file corruption
-   ```javascript
-   color: "FF0000"      // ✅ CORRECT
-   color: "#FF0000"     // ❌ WRONG
-   ```
-
-2. **NEVER encode opacity in hex color strings** - 8-char colors (e.g., `"00000020"`) corrupt the file. Use the `opacity` property instead.
-   ```javascript
-   shadow: { type: "outer", blur: 6, offset: 2, color: "00000020" }          // ❌ CORRUPTS FILE
-   shadow: { type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.12 }  // ✅ CORRECT
-   ```
-
-3. **Use `bullet: true`** - NEVER unicode symbols like "•" (creates double bullets)
-
-4. **Use `breakLine: true`** between array items or text runs together
-
-5. **Avoid `lineSpacing` with bullets** - causes excessive gaps; use `paraSpaceAfter` instead
-
-6. **Each presentation needs fresh instance** - don't reuse `pptxgen()` objects
-
-7. **NEVER reuse option objects across calls** - PptxGenJS mutates objects in-place (e.g. converting shadow values to EMU). Sharing one object between multiple calls corrupts the second shape.
-   ```javascript
-   const shadow = { type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 };
-   slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });  // ❌ second call gets already-converted values
-   slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
-
-   const makeShadow = () => ({ type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 });
-   slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });  // ✅ fresh object each time
-   slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
-   ```
-
-8. **Don't use `ROUNDED_RECTANGLE` with accent borders** - rectangular overlay bars won't cover rounded corners. Use `RECTANGLE` instead.
-   ```javascript
-   // ❌ WRONG: Accent bar doesn't cover rounded corners
-   slide.addShape(pres.shapes.ROUNDED_RECTANGLE, { x: 1, y: 1, w: 3, h: 1.5, fill: { color: "FFFFFF" } });
-   slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 0.08, h: 1.5, fill: { color: "0891B2" } });
-
-   // ✅ CORRECT: Use RECTANGLE for clean alignment
-   slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 3, h: 1.5, fill: { color: "FFFFFF" } });
-   slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 0.08, h: 1.5, fill: { color: "0891B2" } });
-   ```
-
----
-
-## Quick Reference
-
-- **Shapes**: RECTANGLE, OVAL, LINE, ROUNDED_RECTANGLE
-- **Charts**: BAR, LINE, PIE, DOUGHNUT, SCATTER, BUBBLE, RADAR
-- **Layouts**: LAYOUT_16x9 (10"×5.625"), LAYOUT_16x10, LAYOUT_4x3, LAYOUT_WIDE
-- **Alignment**: "left", "center", "right"
-- **Chart data labels**: "outEnd", "inEnd", "center"

skills/pptx/scripts/add_slide.py

@@ -1,51 +1,41 @@
-"""Add a new slide to an unpacked PPTX directory.
+"""Add a slide to a PPTX: duplicate an existing slide or instantiate a layout.
 
-Usage: python add_slide.py <unpacked_dir> <source>
+Does all of the package bookkeeping, so the deck stays valid:
+  - writes the new ppt/slides/slideN.xml (and its .rels, minus any
+    notesSlide reference, so the source's speaker notes aren't shared)
+  - registers it in [Content_Types].xml
+  - adds a slide relationship with a fresh rId to presentation.xml.rels
+  - inserts <p:sldId id="..." r:id="..."/> with a fresh id into
+    <p:sldIdLst> — at the end, or after --after SLIDE
 
-The source can be:
-  - A slide file (e.g., slide2.xml) - duplicates the slide
-  - A layout file (e.g., slideLayout2.xml) - creates from layout
+Works on an unpacked directory (during an editing session) or directly on a
+.pptx/.potx file (extracted to a temp dir, then rezipped atomically; the
+temp dir is discarded, so unpack the output if you still need to edit the
+new slide's content).
 
-Examples:
-    python add_slide.py unpacked/ slide2.xml
-    # Duplicates slide2, creates slide5.xml
+Usage:
+    python add_slide.py unpacked/ slide2.xml                 # duplicate slide2
+    python add_slide.py unpacked/ slideLayout3.xml           # new slide from a layout
+    python add_slide.py unpacked/ slide2.xml --after slide2.xml
+    python add_slide.py deck.pptx slide2.xml                 # rewrite deck.pptx in place
+    python add_slide.py deck.pptx slide2.xml -o out.pptx
 
-    python add_slide.py unpacked/ slideLayout2.xml
-    # Creates slide5.xml from slideLayout2.xml
-
-To see available layouts: ls unpacked/ppt/slideLayouts/
-
-Prints the <p:sldId> element to add to presentation.xml.
+A duplicated slide still holds the source's content: edit ppt/slides/slideN.xml
+(printed on success) to change it. To list layouts: ls <dir>/ppt/slideLayouts/
 """
 
+import argparse
 import re
 import shutil
 import sys
+from typing import NoReturn
+import tempfile
+import zipfile
 from pathlib import Path
 
+from office.helpers import rezip, safe_extract
 
-def get_next_slide_number(slides_dir: Path) -> int:
-    existing = [int(m.group(1)) for f in slides_dir.glob("slide*.xml")
-                if (m := re.match(r"slide(\d+)\.xml", f.name))]
-    return max(existing) + 1 if existing else 1
-
-
-def create_slide_from_layout(unpacked_dir: Path, layout_file: str) -> None:
-    slides_dir = unpacked_dir / "ppt" / "slides"
-    rels_dir = slides_dir / "_rels"
-    layouts_dir = unpacked_dir / "ppt" / "slideLayouts"
-
-    layout_path = layouts_dir / layout_file
-    if not layout_path.exists():
-        print(f"Error: {layout_path} not found", file=sys.stderr)
-        sys.exit(1)
-
-    next_num = get_next_slide_number(slides_dir)
-    dest = f"slide{next_num}.xml"
-    dest_slide = slides_dir / dest
-    dest_rels = rels_dir / f"{dest}.rels"
-
-    slide_xml = '''<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+MINIMAL_SLIDE_XML = '''<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <p:sld xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main">
   <p:cSld>
     <p:spTree>
@@ -68,98 +58,25 @@ def create_slide_from_layout(unpacked_dir: Path, layout_file: str) -> None:
     <a:masterClrMapping/>
   </p:clrMapOvr>
 </p:sld>'''
-    dest_slide.write_text(slide_xml, encoding="utf-8")
 
-    rels_dir.mkdir(exist_ok=True)
-    rels_xml = f'''<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
-  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout" Target="../slideLayouts/{layout_file}"/>
-</Relationships>'''
-    dest_rels.write_text(rels_xml, encoding="utf-8")
+SHARED_PART_TYPES = ("chart", "diagramData", "oleObject", "package")
 
-    _add_to_content_types(unpacked_dir, dest)
+NOTES_SLIDE_TYPE_RE = re.compile(r"""Type=["'][^"']*/relationships/notesSlide["']""")
+RELATIONSHIP_RE = re.compile(r"<Relationship\b[^>]*?(?:/>|>.*?</Relationship\s*>)", re.DOTALL)
 
-    rid = _add_to_presentation_rels(unpacked_dir, dest)
-
-    next_slide_id = _get_next_slide_id(unpacked_dir)
-
-    print(f"Created {dest} from {layout_file}")
-    print(f'Add to presentation.xml <p:sldIdLst>: <p:sldId id="{next_slide_id}" r:id="{rid}"/>')
+SLIDE_ID_MIN = 256
+SLIDE_ID_MAX = 2147483647
 
 
-def duplicate_slide(unpacked_dir: Path, source: str) -> None:
-    slides_dir = unpacked_dir / "ppt" / "slides"
-    rels_dir = slides_dir / "_rels"
-
-    source_slide = slides_dir / source
-
-    if not source_slide.exists():
-        print(f"Error: {source_slide} not found", file=sys.stderr)
-        sys.exit(1)
-
-    next_num = get_next_slide_number(slides_dir)
-    dest = f"slide{next_num}.xml"
-    dest_slide = slides_dir / dest
-
-    source_rels = rels_dir / f"{source}.rels"
-    dest_rels = rels_dir / f"{dest}.rels"
-
-    shutil.copy2(source_slide, dest_slide)
-
-    if source_rels.exists():
-        shutil.copy2(source_rels, dest_rels)
-
-        rels_content = dest_rels.read_text(encoding="utf-8")
-        rels_content = re.sub(
-            r'\s*<Relationship[^>]*Type="[^"]*notesSlide"[^>]*/>\s*',
-            "\n",
-            rels_content,
-        )
-        dest_rels.write_text(rels_content, encoding="utf-8")
-
-    _add_to_content_types(unpacked_dir, dest)
-
-    rid = _add_to_presentation_rels(unpacked_dir, dest)
-
-    next_slide_id = _get_next_slide_id(unpacked_dir)
-
-    print(f"Created {dest} from {source}")
-    print(f'Add to presentation.xml <p:sldIdLst>: <p:sldId id="{next_slide_id}" r:id="{rid}"/>')
+def _die(msg: str) -> NoReturn:
+    print(f"Error: {msg}", file=sys.stderr)
+    sys.exit(1)
 
 
-def _add_to_content_types(unpacked_dir: Path, dest: str) -> None:
-    content_types_path = unpacked_dir / "[Content_Types].xml"
-    content_types = content_types_path.read_text(encoding="utf-8")
-
-    new_override = f'<Override PartName="/ppt/slides/{dest}" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slide+xml"/>'
-
-    if f"/ppt/slides/{dest}" not in content_types:
-        content_types = content_types.replace("</Types>", f"  {new_override}\n</Types>")
-        content_types_path.write_text(content_types, encoding="utf-8")
-
-
-def _add_to_presentation_rels(unpacked_dir: Path, dest: str) -> str:
-    pres_rels_path = unpacked_dir / "ppt" / "_rels" / "presentation.xml.rels"
-    pres_rels = pres_rels_path.read_text(encoding="utf-8")
-
-    rids = [int(m) for m in re.findall(r'Id="rId(\d+)"', pres_rels)]
-    next_rid = max(rids) + 1 if rids else 1
-    rid = f"rId{next_rid}"
-
-    new_rel = f'<Relationship Id="{rid}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide" Target="slides/{dest}"/>'
-
-    if f"slides/{dest}" not in pres_rels:
-        pres_rels = pres_rels.replace("</Relationships>", f"  {new_rel}\n</Relationships>")
-        pres_rels_path.write_text(pres_rels, encoding="utf-8")
-
-    return rid
-
-
-def _get_next_slide_id(unpacked_dir: Path) -> int:
-    pres_path = unpacked_dir / "ppt" / "presentation.xml"
-    pres_content = pres_path.read_text(encoding="utf-8")
-    slide_ids = [int(m) for m in re.findall(r'<p:sldId[^>]*id="(\d+)"', pres_content)]
-    return max(slide_ids) + 1 if slide_ids else 256
+def get_next_slide_number(slides_dir: Path) -> int:
+    existing = [int(m.group(1)) for f in slides_dir.glob("slide*.xml")
+                if (m := re.match(r"slide(\d+)\.xml", f.name))]
+    return max(existing) + 1 if existing else 1
 
 
 def parse_source(source: str) -> tuple[str, str | None]:
@@ -169,27 +86,282 @@ def parse_source(source: str) -> tuple[str, str | None]:
     return ("slide", None)
 
 
-if __name__ == "__main__":
-    if len(sys.argv) != 3:
-        print("Usage: python add_slide.py <unpacked_dir> <source>", file=sys.stderr)
-        print("", file=sys.stderr)
-        print("Source can be:", file=sys.stderr)
-        print("  slide2.xml        - duplicate an existing slide", file=sys.stderr)
-        print("  slideLayout2.xml  - create from a layout template", file=sys.stderr)
-        print("", file=sys.stderr)
-        print("To see available layouts: ls <unpacked_dir>/ppt/slideLayouts/", file=sys.stderr)
-        sys.exit(1)
+def create_slide_from_layout(unpacked_dir: Path, layout_file: str, after: str | None = None) -> str:
+    slides_dir = unpacked_dir / "ppt" / "slides"
+    rels_dir = slides_dir / "_rels"
+    layout_path = unpacked_dir / "ppt" / "slideLayouts" / layout_file
 
-    unpacked_dir = Path(sys.argv[1])
-    source = sys.argv[2]
+    if not layout_path.exists():
+        _die(f"{layout_path} not found")
 
-    if not unpacked_dir.exists():
-        print(f"Error: {unpacked_dir} not found", file=sys.stderr)
-        sys.exit(1)
+    next_num = get_next_slide_number(slides_dir)
+    dest = f"slide{next_num}.xml"
+    after_rid = _precheck_registration(unpacked_dir, after, dest)
+    slides_dir.mkdir(parents=True, exist_ok=True)
 
-    source_type, layout_file = parse_source(source)
+    (slides_dir / dest).write_text(MINIMAL_SLIDE_XML, encoding="utf-8")
 
-    if source_type == "layout" and layout_file is not None:
-        create_slide_from_layout(unpacked_dir, layout_file)
+    rels_dir.mkdir(exist_ok=True)
+    rels_xml = f'''<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout" Target="../slideLayouts/{layout_file}"/>
+</Relationships>'''
+    (rels_dir / f"{dest}.rels").write_text(rels_xml, encoding="utf-8")
+
+    _register_slide(unpacked_dir, dest, layout_file, after_rid)
+    return dest
+
+
+def duplicate_slide(unpacked_dir: Path, source: str, after: str | None = None) -> str:
+    slides_dir = unpacked_dir / "ppt" / "slides"
+    rels_dir = slides_dir / "_rels"
+    source_slide = slides_dir / source
+
+    if not source_slide.exists():
+        _die(f"{source_slide} not found")
+
+    next_num = get_next_slide_number(slides_dir)
+    dest = f"slide{next_num}.xml"
+    after_rid = _precheck_registration(unpacked_dir, after, dest)
+
+    shutil.copy2(source_slide, slides_dir / dest)
+
+    source_rels = rels_dir / f"{source}.rels"
+    shared_parts: list[str] = []
+    if source_rels.exists():
+        dest_rels = rels_dir / f"{dest}.rels"
+        shutil.copy2(source_rels, dest_rels)
+        rels_content = dest_rels.read_text(encoding="utf-8")
+        rels_content = RELATIONSHIP_RE.sub(
+            lambda m: "" if NOTES_SLIDE_TYPE_RE.search(m.group(0)) else m.group(0),
+            rels_content,
+        )
+        dest_rels.write_text(rels_content, encoding="utf-8")
+        shared_parts = sorted({
+            t for t in re.findall(r'Type="[^"]*/relationships/(\w+)"', rels_content)
+            if t in SHARED_PART_TYPES
+        })
+
+    _register_slide(unpacked_dir, dest, source, after_rid)
+    if shared_parts:
+        print(
+            f"Note: {dest} shares its {', '.join(shared_parts)} part(s) with {source} "
+            f"(they are referenced, not copied) — editing those parts changes both slides"
+        )
+    return dest
+
+
+def _precheck_registration(unpacked_dir: Path, after: str | None, dest: str) -> str | None:
+    pres_path = unpacked_dir / "ppt" / "presentation.xml"
+    if not pres_path.exists():
+        _die(f"{pres_path} not found — is this an unpacked PPTX?")
+    xml = pres_path.read_text(encoding="utf-8")
+
+    has_slot = (
+        "</p:sldIdLst>" in xml
+        or re.search(r"<p:sldIdLst\s*/>", xml)
+        or "</p:sldMasterIdLst>" in xml
+    )
+    if not has_slot:
+        _die("presentation.xml has no <p:sldIdLst> (or <p:sldMasterIdLst> to anchor a new one)")
+
+    stale = []
+    content_types = unpacked_dir / "[Content_Types].xml"
+    if content_types.exists() and f'PartName="/ppt/slides/{dest}"' in content_types.read_text(encoding="utf-8"):
+        stale.append("[Content_Types].xml")
+    pres_rels = unpacked_dir / "ppt" / "_rels" / "presentation.xml.rels"
+    if pres_rels.exists() and _find_slide_relationship(
+        pres_rels.read_text(encoding="utf-8"), dest
+    ):
+        stale.append("presentation.xml.rels")
+    if stale:
+        _die(
+            f"{dest} is still registered in {' and '.join(stale)} but absent from ppt/slides/ — "
+            f"run clean.py first"
+        )
+
+    if not after:
+        return None
+    after_rid = _rid_for_slide(unpacked_dir, after)
+    if not re.search(rf'<p:sldId\b[^>]*r:id="{re.escape(after_rid)}"[^>]*>', xml):
+        _die(f"{after} ({after_rid}) is not listed in <p:sldIdLst>")
+    return after_rid
+
+
+def _register_slide(unpacked_dir: Path, dest: str, source_desc: str, after_rid: str | None) -> None:
+    _add_to_content_types(unpacked_dir, dest)
+    rid = _add_to_presentation_rels(unpacked_dir, dest)
+    slide_id = _get_next_slide_id(unpacked_dir)
+    pos, total = _insert_into_sld_id_lst(unpacked_dir, slide_id, rid, after_rid)
+
+    print(f"Created ppt/slides/{dest} from {source_desc}")
+    print(
+        f'Inserted <p:sldId id="{slide_id}" r:id="{rid}"/> into <p:sldIdLst> '
+        f"at position {pos} of {total}"
+    )
+
+
+def _add_to_content_types(unpacked_dir: Path, dest: str) -> None:
+    content_types_path = unpacked_dir / "[Content_Types].xml"
+    content_types = content_types_path.read_text(encoding="utf-8")
+
+    new_override = f'<Override PartName="/ppt/slides/{dest}" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slide+xml"/>'
+
+    if f'PartName="/ppt/slides/{dest}"' not in content_types:
+        content_types = content_types.replace("</Types>", f"  {new_override}\n</Types>")
+        content_types_path.write_text(content_types, encoding="utf-8")
+
+
+def _add_to_presentation_rels(unpacked_dir: Path, dest: str) -> str:
+    pres_rels_path = unpacked_dir / "ppt" / "_rels" / "presentation.xml.rels"
+    pres_rels = pres_rels_path.read_text(encoding="utf-8")
+
+    existing = _find_slide_relationship(pres_rels, dest)
+    if existing:
+        return existing
+
+    pres_xml = (unpacked_dir / "ppt" / "presentation.xml").read_text(encoding="utf-8")
+    used = {int(n) for n in re.findall(r'\bId="rId(\d+)"', pres_rels)}
+    used |= {int(n) for n in re.findall(r'\br:id="rId(\d+)"', pres_xml)}
+    rid = f"rId{max(used) + 1 if used else 1}"
+
+    new_rel = f'<Relationship Id="{rid}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide" Target="slides/{dest}"/>'
+    pres_rels = pres_rels.replace("</Relationships>", f"  {new_rel}\n</Relationships>")
+    pres_rels_path.write_text(pres_rels, encoding="utf-8")
+
+    return rid
+
+
+def _find_slide_relationship(pres_rels: str, slide_name: str) -> str | None:
+    for m in re.finditer(r"<Relationship\b[^>]*>", pres_rels):
+        element = m.group(0)
+        if re.search(rf'Target="(?:/ppt/)?slides/{re.escape(slide_name)}"', element):
+            id_match = re.search(r'\bId="([^"]+)"', element)
+            if id_match:
+                return id_match.group(1)
+    return None
+
+
+def _get_next_slide_id(unpacked_dir: Path) -> int:
+    pres_content = (unpacked_dir / "ppt" / "presentation.xml").read_text(encoding="utf-8")
+    used = {int(m) for m in re.findall(r'<p:sldId[^>]*\bid="(\d+)"', pres_content)}
+
+    candidate = max((i for i in used if i >= SLIDE_ID_MIN), default=SLIDE_ID_MIN - 1) + 1
+    if candidate <= SLIDE_ID_MAX and candidate not in used:
+        return candidate
+    for i in range(SLIDE_ID_MIN, SLIDE_ID_MAX + 1):
+        if i not in used:
+            return i
+    _die("no slide id available in [256, 2147483647] — the deck is full")
+
+
+def _insert_into_sld_id_lst(
+    unpacked_dir: Path, slide_id: int, rid: str, after_rid: str | None = None
+) -> tuple[int, int]:
+    pres_path = unpacked_dir / "ppt" / "presentation.xml"
+    xml = pres_path.read_text(encoding="utf-8")
+    entry = f'<p:sldId id="{slide_id}" r:id="{rid}"/>'
+
+    if f'r:id="{rid}"' in xml:
+        _die(f"presentation.xml already references {rid}; refusing to add a duplicate")
+
+    if after_rid:
+        open_tag = re.search(rf'<p:sldId\b[^>]*r:id="{re.escape(after_rid)}"[^>]*>', xml)
+        if not open_tag:
+            _die(f"{after_rid} is not listed in <p:sldIdLst>")
+        end = open_tag.end()
+        if not open_tag.group(0).endswith("/>"):
+            close = xml.find("</p:sldId>", end)
+            if close == -1:
+                _die(f"unclosed <p:sldId> for {after_rid} in presentation.xml")
+            end = close + len("</p:sldId>")
+        xml = xml[:end] + entry + xml[end:]
+    elif "</p:sldIdLst>" in xml:
+        xml = xml.replace("</p:sldIdLst>", f"{entry}</p:sldIdLst>", 1)
+    elif re.search(r"<p:sldIdLst\s*/>", xml):
+        xml = re.sub(r"<p:sldIdLst\s*/>", f"<p:sldIdLst>{entry}</p:sldIdLst>", xml, count=1)
+    elif "</p:sldMasterIdLst>" in xml:
+        xml = xml.replace(
+            "</p:sldMasterIdLst>", f"</p:sldMasterIdLst><p:sldIdLst>{entry}</p:sldIdLst>", 1
+        )
     else:
-        duplicate_slide(unpacked_dir, source)
+        _die("presentation.xml has no <p:sldIdLst> (or <p:sldMasterIdLst> to anchor a new one)")
+
+    pres_path.write_text(xml, encoding="utf-8")
+
+    lst = re.search(r"<p:sldIdLst>(.*)</p:sldIdLst>", xml, re.DOTALL)
+    entries = re.findall(r"<p:sldId\b[^>]*>", lst.group(1)) if lst else []
+    position = next(
+        (i for i, e in enumerate(entries, 1) if f'r:id="{rid}"' in e), len(entries)
+    )
+    return position, len(entries)
+
+
+def _rid_for_slide(unpacked_dir: Path, slide_name: str) -> str:
+    pres_rels_path = unpacked_dir / "ppt" / "_rels" / "presentation.xml.rels"
+    rid = _find_slide_relationship(pres_rels_path.read_text(encoding="utf-8"), slide_name)
+    if not rid:
+        _die(f"{slide_name} has no relationship in presentation.xml.rels")
+    return rid
+
+
+def add_slide(unpacked_dir: Path, source: str, after: str | None = None) -> str:
+    source_type, layout_file = parse_source(source)
+    if source_type == "layout" and layout_file is not None:
+        return create_slide_from_layout(unpacked_dir, layout_file, after)
+    return duplicate_slide(unpacked_dir, source, after)
+
+
+def add_slide_to_package(
+    package: Path, source: str, after: str | None = None, output: Path | None = None
+) -> str:
+    out = output or package
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_path = Path(tmp)
+        with zipfile.ZipFile(package) as zf:
+            safe_extract(zf, tmp_path)
+        dest = add_slide(tmp_path, source, after)
+        rezip(tmp_path, out)
+    print(f"Wrote {out} — the new slide is ppt/slides/{dest} inside it (unpack to edit its content)")
+    return dest
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Add a slide to a PPTX: duplicate a slide or instantiate a layout. "
+        "Registers content types, relationships, and <p:sldIdLst>."
+    )
+    parser.add_argument("target", help="Unpacked PPTX directory OR a .pptx/.potx file")
+    parser.add_argument(
+        "source",
+        help="slideN.xml to duplicate, or slideLayoutN.xml to create from a layout "
+        "(list layouts with: ls <dir>/ppt/slideLayouts/)",
+    )
+    parser.add_argument(
+        "--after",
+        metavar="SLIDE",
+        help="insert after this slide, e.g. slide2.xml (default: append at the end)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        help="output file (only with a .pptx/.potx target; default: rewrite the input in place)",
+    )
+    args = parser.parse_args()
+
+    target = Path(args.target)
+    if target.is_dir():
+        if args.output:
+            parser.error("--output is only valid for .pptx/.potx input; a directory is modified in place")
+        add_slide(target, args.source, args.after)
+    elif target.is_file() and target.suffix.lower() in (".pptx", ".potx"):
+        try:
+            add_slide_to_package(target, args.source, args.after, Path(args.output) if args.output else None)
+        except (OSError, ValueError, zipfile.BadZipFile) as e:
+            _die(str(e))
+    else:
+        _die(f"{target} is neither a directory nor a .pptx/.potx file")
+
+
+if __name__ == "__main__":
+    main()

skills/pptx/scripts/clean.py

@@ -15,13 +15,30 @@ This script removes:
 - Content-Type overrides for deleted files
 """
 
+import posixpath
+import re
 import sys
 from pathlib import Path
 
 import defusedxml.minidom
 
+from office.helpers import SLIDE_REL_TYPE, opc_target, rels_source_part
 
-import re
+
+def _slide_rids(pres_rels_path: Path, unpacked_dir: Path) -> dict[str, str]:
+    source_part = rels_source_part(pres_rels_path, unpacked_dir)
+    rels_dom = defusedxml.minidom.parse(str(pres_rels_path))
+
+    rids: dict[str, str] = {}
+    for rel in rels_dom.getElementsByTagName("Relationship"):
+        if rel.getAttribute("Type") != SLIDE_REL_TYPE:
+            continue
+        part = opc_target(
+            rel.getAttribute("Target"), source_part, rel.getAttribute("TargetMode")
+        )
+        if part is not None:
+            rids[rel.getAttribute("Id")] = part
+    return rids
 
 
 def get_slides_in_sldidlst(unpacked_dir: Path) -> set[str]:
@@ -31,19 +48,20 @@ def get_slides_in_sldidlst(unpacked_dir: Path) -> set[str]:
     if not pres_path.exists() or not pres_rels_path.exists():
         return set()
 
-    rels_dom = defusedxml.minidom.parse(str(pres_rels_path))
-    rid_to_slide = {}
-    for rel in rels_dom.getElementsByTagName("Relationship"):
-        rid = rel.getAttribute("Id")
-        target = rel.getAttribute("Target")
-        rel_type = rel.getAttribute("Type")
-        if "slide" in rel_type and target.startswith("slides/"):
-            rid_to_slide[rid] = target.replace("slides/", "")
+    rid_to_slide = _slide_rids(pres_rels_path, unpacked_dir)
 
     pres_content = pres_path.read_text(encoding="utf-8")
     referenced_rids = set(re.findall(r'<p:sldId[^>]*r:id="([^"]+)"', pres_content))
 
-    return {rid_to_slide[rid] for rid in referenced_rids if rid in rid_to_slide}
+    return {
+        posixpath.basename(rid_to_slide[rid])
+        for rid in referenced_rids
+        if rid in rid_to_slide
+    }
+
+
+class RefusedToClean(Exception):
+    """The package does not look the way a readable package should."""
 
 
 def remove_orphaned_slides(unpacked_dir: Path) -> list[str]:
@@ -55,9 +73,25 @@ def remove_orphaned_slides(unpacked_dir: Path) -> list[str]:
         return []
 
     referenced_slides = get_slides_in_sldidlst(unpacked_dir)
+    on_disk = sorted(slides_dir.glob("slide*.xml"))
+
+    if on_disk and not any(s.name in referenced_slides for s in on_disk):
+        listed = re.findall(
+            r'<p:sldId[^>]*r:id="([^"]+)"',
+            (unpacked_dir / "ppt" / "presentation.xml").read_text(encoding="utf-8")
+            if (unpacked_dir / "ppt" / "presentation.xml").exists()
+            else "",
+        )
+        if listed:
+            raise RefusedToClean(
+                f"<p:sldIdLst> lists {len(listed)} slide(s) and none of the "
+                f"{len(on_disk)} slide(s) on disk match any of them. Refusing to "
+                f"delete them all — this is a parse failure, not an empty deck."
+            )
+
     removed = []
 
-    for slide_file in slides_dir.glob("slide*.xml"):
+    for slide_file in on_disk:
         if slide_file.name not in referenced_slides:
             rel_path = slide_file.relative_to(unpacked_dir)
             slide_file.unlink()
@@ -70,16 +104,21 @@ def remove_orphaned_slides(unpacked_dir: Path) -> list[str]:
 
     if removed and pres_rels_path.exists():
         rels_dom = defusedxml.minidom.parse(str(pres_rels_path))
+        source_part = rels_source_part(pres_rels_path, unpacked_dir)
         changed = False
 
         for rel in list(rels_dom.getElementsByTagName("Relationship")):
-            target = rel.getAttribute("Target")
-            if target.startswith("slides/"):
-                slide_name = target.replace("slides/", "")
-                if slide_name not in referenced_slides:
-                    if rel.parentNode:
-                        rel.parentNode.removeChild(rel)
-                        changed = True
+            if rel.getAttribute("Type") != SLIDE_REL_TYPE:
+                continue
+            part = opc_target(
+                rel.getAttribute("Target"), source_part, rel.getAttribute("TargetMode")
+            )
+            if part is None:
+                continue
+            if posixpath.basename(part) not in referenced_slides:
+                if rel.parentNode:
+                    rel.parentNode.removeChild(rel)
+                    changed = True
 
         if changed:
             with open(pres_rels_path, "wb") as f:
@@ -103,24 +142,18 @@ def remove_trash_directory(unpacked_dir: Path) -> list[str]:
     return removed
 
 
-def get_slide_referenced_files(unpacked_dir: Path) -> set:
+def _referenced_by(rels_files, unpacked_dir: Path) -> set:
     referenced = set()
-    slides_rels_dir = unpacked_dir / "ppt" / "slides" / "_rels"
 
-    if not slides_rels_dir.exists():
-        return referenced
-
-    for rels_file in slides_rels_dir.glob("*.rels"):
+    for rels_file in rels_files:
+        source_part = rels_source_part(rels_file, unpacked_dir)
         dom = defusedxml.minidom.parse(str(rels_file))
         for rel in dom.getElementsByTagName("Relationship"):
-            target = rel.getAttribute("Target")
-            if not target:
-                continue
-            target_path = (rels_file.parent.parent / target).resolve()
-            try:
-                referenced.add(target_path.relative_to(unpacked_dir.resolve()))
-            except ValueError:
-                pass
+            part = opc_target(
+                rel.getAttribute("Target"), source_part, rel.getAttribute("TargetMode")
+            )
+            if part is not None:
+                referenced.add(Path(part))
 
     return referenced
 
@@ -128,7 +161,6 @@ def get_slide_referenced_files(unpacked_dir: Path) -> set:
 def remove_orphaned_rels_files(unpacked_dir: Path) -> list[str]:
     resource_dirs = ["charts", "diagrams", "drawings"]
     removed = []
-    slide_referenced = get_slide_referenced_files(unpacked_dir)
 
     for dir_name in resource_dirs:
         rels_dir = unpacked_dir / "ppt" / dir_name / "_rels"
@@ -137,35 +169,15 @@ def remove_orphaned_rels_files(unpacked_dir: Path) -> list[str]:
 
         for rels_file in rels_dir.glob("*.rels"):
             resource_file = rels_dir.parent / rels_file.name.replace(".rels", "")
-            try:
-                resource_rel_path = resource_file.resolve().relative_to(unpacked_dir.resolve())
-            except ValueError:
-                continue
-
-            if not resource_file.exists() or resource_rel_path not in slide_referenced:
+            if not resource_file.exists():
                 rels_file.unlink()
-                rel_path = rels_file.relative_to(unpacked_dir)
-                removed.append(str(rel_path))
+                removed.append(str(rels_file.relative_to(unpacked_dir)))
 
     return removed
 
 
 def get_referenced_files(unpacked_dir: Path) -> set:
-    referenced = set()
-
-    for rels_file in unpacked_dir.rglob("*.rels"):
-        dom = defusedxml.minidom.parse(str(rels_file))
-        for rel in dom.getElementsByTagName("Relationship"):
-            target = rel.getAttribute("Target")
-            if not target:
-                continue
-            target_path = (rels_file.parent.parent / target).resolve()
-            try:
-                referenced.add(target_path.relative_to(unpacked_dir.resolve()))
-            except ValueError:
-                pass
-
-    return referenced
+    return _referenced_by(sorted(unpacked_dir.rglob("*.rels")), unpacked_dir)
 
 
 def remove_orphaned_files(unpacked_dir: Path, referenced: set) -> list[str]:
@@ -241,6 +253,12 @@ def update_content_types(unpacked_dir: Path, removed_files: list[str]) -> None:
 def clean_unused_files(unpacked_dir: Path) -> list[str]:
     all_removed = []
 
+    if list(unpacked_dir.rglob("*.rels")) and not get_referenced_files(unpacked_dir):
+        raise RefusedToClean(
+            "no relationship in this package names a part we can resolve. "
+            "Refusing to treat every file as unreferenced."
+        )
+
     slides_removed = remove_orphaned_slides(unpacked_dir)
     all_removed.extend(slides_removed)
 
@@ -276,7 +294,12 @@ if __name__ == "__main__":
         print(f"Error: {unpacked_dir} not found", file=sys.stderr)
         sys.exit(1)
 
-    removed = clean_unused_files(unpacked_dir)
+    try:
+        removed = clean_unused_files(unpacked_dir)
+    except (RefusedToClean, ValueError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        print("Nothing was deleted.", file=sys.stderr)
+        sys.exit(1)
 
     if removed:
         print(f"Removed {len(removed)} unreferenced files:")

skills/pptx/scripts/office/helpers/__init__.py

@@ -0,0 +1,111 @@
+import os
+import posixpath
+import re
+import stat
+import tempfile
+import urllib.parse
+import zipfile
+from pathlib import Path
+
+OOXML_FAMILY = {
+    ".docx": "docx",
+    ".dotx": "docx",
+    ".pptx": "pptx",
+    ".potx": "pptx",
+    ".xlsx": "xlsx",
+    ".xltx": "xlsx",
+}
+
+_SCHEME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.\-]*:")
+
+SLIDE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide"
+
+
+def opc_target(target: str, source_part: str, target_mode: str = "") -> str | None:
+    if not target:
+        return None
+    if target_mode.lower() == "external":
+        return None
+    if _SCHEME_RE.match(target):
+        return None
+
+    target = urllib.parse.unquote(target)
+
+    if "\\" in target:
+        raise ValueError(f"relationship target is not a POSIX part name: {target!r}")
+
+    if target.startswith("/"):
+        joined = target.lstrip("/")
+    else:
+        joined = posixpath.join(posixpath.dirname(source_part), target)
+
+    parts: list[str] = []
+    for segment in posixpath.normpath(joined).split("/"):
+        if segment in ("", "."):
+            continue
+        if segment == "..":
+            if not parts:
+                raise ValueError(f"relationship target escapes the package: {target!r}")
+            parts.pop()
+        else:
+            parts.append(segment)
+
+    if not parts:
+        raise ValueError(f"relationship target resolves to nothing: {target!r}")
+    return "/".join(parts)
+
+
+def rels_source_part(rels_file: Path, unpacked_dir: Path) -> str:
+    owner_dir = rels_file.parent.parent.relative_to(unpacked_dir)
+    return posixpath.join(owner_dir.as_posix(), rels_file.name[: -len(".rels")]).lstrip("./")
+
+
+def part_text(data: bytes) -> str:
+    return data.decode("utf-8", "surrogateescape")
+
+
+XML_SPACE = " \t\r\n"
+
+
+def rendered_text(text: str, preserve: bool) -> str:
+    return text if preserve else text.strip(XML_SPACE)
+
+
+def safe_extract(zf: zipfile.ZipFile, dest: Path) -> None:
+    dest = dest.resolve()
+    for m in zf.infolist():
+        if stat.S_ISLNK(m.external_attr >> 16):
+            raise ValueError(f"symlink archive entry not allowed: {m.filename!r}")
+        target = (dest / m.filename).resolve()
+        if not target.is_relative_to(dest):
+            raise ValueError(f"unsafe archive entry: {m.filename!r}")
+        zf.extract(m, dest)
+
+
+def rezip(src_dir: Path, out_path: Path) -> None:
+    files = sorted(p for p in src_dir.rglob("*") if p.is_file())
+    ct = src_dir / "[Content_Types].xml"
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=out_path.name + ".", suffix=".tmp", dir=out_path.parent
+    )
+    tmp_out = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            with zipfile.ZipFile(fh, "w", zipfile.ZIP_DEFLATED) as zf:
+                if ct.exists():
+                    zf.write(ct, ct.relative_to(src_dir), compress_type=zipfile.ZIP_STORED)
+                for f in files:
+                    if f == ct:
+                        continue
+                    zf.write(f, f.relative_to(src_dir))
+        if out_path.exists():
+            mode = out_path.stat().st_mode & 0o777
+        else:
+            umask = os.umask(0)
+            os.umask(umask)
+            mode = 0o666 & ~umask
+        os.chmod(tmp_out, mode)
+        os.replace(tmp_out, out_path)
+    finally:
+        if tmp_out.exists():
+            tmp_out.unlink()

skills/pptx/scripts/office/helpers/merge_runs.py

@@ -1,199 +0,0 @@
-"""Merge adjacent runs with identical formatting in DOCX.
-
-Merges adjacent <w:r> elements that have identical <w:rPr> properties.
-Works on runs in paragraphs and inside tracked changes (<w:ins>, <w:del>).
-
-Also:
-- Removes rsid attributes from runs (revision metadata that doesn't affect rendering)
-- Removes proofErr elements (spell/grammar markers that block merging)
-"""
-
-from pathlib import Path
-
-import defusedxml.minidom
-
-
-def merge_runs(input_dir: str) -> tuple[int, str]:
-    doc_xml = Path(input_dir) / "word" / "document.xml"
-
-    if not doc_xml.exists():
-        return 0, f"Error: {doc_xml} not found"
-
-    try:
-        dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding="utf-8"))
-        root = dom.documentElement
-
-        _remove_elements(root, "proofErr")
-        _strip_run_rsid_attrs(root)
-
-        containers = {run.parentNode for run in _find_elements(root, "r")}
-
-        merge_count = 0
-        for container in containers:
-            merge_count += _merge_runs_in(container)
-
-        doc_xml.write_bytes(dom.toxml(encoding="UTF-8"))
-        return merge_count, f"Merged {merge_count} runs"
-
-    except Exception as e:
-        return 0, f"Error: {e}"
-
-
-
-
-def _find_elements(root, tag: str) -> list:
-    results = []
-
-    def traverse(node):
-        if node.nodeType == node.ELEMENT_NODE:
-            name = node.localName or node.tagName
-            if name == tag or name.endswith(f":{tag}"):
-                results.append(node)
-            for child in node.childNodes:
-                traverse(child)
-
-    traverse(root)
-    return results
-
-
-def _get_child(parent, tag: str):
-    for child in parent.childNodes:
-        if child.nodeType == child.ELEMENT_NODE:
-            name = child.localName or child.tagName
-            if name == tag or name.endswith(f":{tag}"):
-                return child
-    return None
-
-
-def _get_children(parent, tag: str) -> list:
-    results = []
-    for child in parent.childNodes:
-        if child.nodeType == child.ELEMENT_NODE:
-            name = child.localName or child.tagName
-            if name == tag or name.endswith(f":{tag}"):
-                results.append(child)
-    return results
-
-
-def _is_adjacent(elem1, elem2) -> bool:
-    node = elem1.nextSibling
-    while node:
-        if node == elem2:
-            return True
-        if node.nodeType == node.ELEMENT_NODE:
-            return False
-        if node.nodeType == node.TEXT_NODE and node.data.strip():
-            return False
-        node = node.nextSibling
-    return False
-
-
-
-
-def _remove_elements(root, tag: str):
-    for elem in _find_elements(root, tag):
-        if elem.parentNode:
-            elem.parentNode.removeChild(elem)
-
-
-def _strip_run_rsid_attrs(root):
-    for run in _find_elements(root, "r"):
-        for attr in list(run.attributes.values()):
-            if "rsid" in attr.name.lower():
-                run.removeAttribute(attr.name)
-
-
-
-
-def _merge_runs_in(container) -> int:
-    merge_count = 0
-    run = _first_child_run(container)
-
-    while run:
-        while True:
-            next_elem = _next_element_sibling(run)
-            if next_elem and _is_run(next_elem) and _can_merge(run, next_elem):
-                _merge_run_content(run, next_elem)
-                container.removeChild(next_elem)
-                merge_count += 1
-            else:
-                break
-
-        _consolidate_text(run)
-        run = _next_sibling_run(run)
-
-    return merge_count
-
-
-def _first_child_run(container):
-    for child in container.childNodes:
-        if child.nodeType == child.ELEMENT_NODE and _is_run(child):
-            return child
-    return None
-
-
-def _next_element_sibling(node):
-    sibling = node.nextSibling
-    while sibling:
-        if sibling.nodeType == sibling.ELEMENT_NODE:
-            return sibling
-        sibling = sibling.nextSibling
-    return None
-
-
-def _next_sibling_run(node):
-    sibling = node.nextSibling
-    while sibling:
-        if sibling.nodeType == sibling.ELEMENT_NODE:
-            if _is_run(sibling):
-                return sibling
-        sibling = sibling.nextSibling
-    return None
-
-
-def _is_run(node) -> bool:
-    name = node.localName or node.tagName
-    return name == "r" or name.endswith(":r")
-
-
-def _can_merge(run1, run2) -> bool:
-    rpr1 = _get_child(run1, "rPr")
-    rpr2 = _get_child(run2, "rPr")
-
-    if (rpr1 is None) != (rpr2 is None):
-        return False
-    if rpr1 is None:
-        return True
-    return rpr1.toxml() == rpr2.toxml()  
-
-
-def _merge_run_content(target, source):
-    for child in list(source.childNodes):
-        if child.nodeType == child.ELEMENT_NODE:
-            name = child.localName or child.tagName
-            if name != "rPr" and not name.endswith(":rPr"):
-                target.appendChild(child)
-
-
-def _consolidate_text(run):
-    t_elements = _get_children(run, "t")
-
-    for i in range(len(t_elements) - 1, 0, -1):
-        curr, prev = t_elements[i], t_elements[i - 1]
-
-        if _is_adjacent(prev, curr):
-            prev_text = prev.firstChild.data if prev.firstChild else ""
-            curr_text = curr.firstChild.data if curr.firstChild else ""
-            merged = prev_text + curr_text
-
-            if prev.firstChild:
-                prev.firstChild.data = merged
-            else:
-                prev.appendChild(run.ownerDocument.createTextNode(merged))
-
-            if merged.startswith(" ") or merged.endswith(" "):
-                prev.setAttribute("xml:space", "preserve")
-            elif prev.hasAttribute("xml:space"):
-                prev.removeAttribute("xml:space")
-
-            run.removeChild(curr)

skills/pptx/scripts/office/helpers/pptx_chart.py

@@ -0,0 +1,170 @@
+"""Find chart XML that PowerPoint refuses but the schema accepts.
+
+Detection only: for either fault more than one repair is valid, and only the
+author knows which was meant.
+"""
+
+
+from __future__ import annotations
+
+import re
+from typing import Mapping
+
+from . import part_text
+
+
+_CHART_PART_RE = re.compile(r"ppt/charts/chart\d+\.xml")
+
+_GROUPING_RE = re.compile(r"""<c:grouping\b[^>]*?\bval=["'](\w+)["']""")
+_DLBL_POS_RE = re.compile(r"""<c:dLblPos\b[^>]*?\bval=["'](\w+)["']""")
+
+def _strip_ext_lst(text: str) -> str:
+    out, cursor = [], 0
+    for lo, hi in _ext_lst_spans(text):
+        out.append(text[cursor:lo])
+        cursor = hi
+    out.append(text[cursor:])
+    return "".join(out)
+
+_BAR_GROUP_RE = re.compile(r"<c:(bar3DChart|barChart)\b[^>]*(?<!/)>.*?</c:\1\s*>", re.DOTALL)
+
+STACKED_GROUPINGS = frozenset({"stacked", "percentStacked"})
+ILLEGAL_ON_STACKED = frozenset({"outEnd"})
+LEGAL_ON_STACKED = ("ctr", "inEnd", "inBase")
+
+
+def _check_stacked_label_positions(part: str, xml: str) -> list[str]:
+    problems: list[str] = []
+    for match in _BAR_GROUP_RE.finditer(xml):
+        block = _strip_ext_lst(match.group(0))
+        group = match.group(1)
+
+        grouping = _GROUPING_RE.search(block)
+        if grouping is None or grouping.group(1) not in STACKED_GROUPINGS:
+            continue
+
+        bad = [p for p in _DLBL_POS_RE.findall(block) if p in ILLEGAL_ON_STACKED]
+        for pos in sorted(set(bad)):
+            problems.append(
+                f'{part}: {bad.count(pos)} data label(s) use dLblPos="{pos}" on a '
+                f"{grouping.group(1)} {group}; PowerPoint allows only "
+                f"{', '.join(LEGAL_ON_STACKED)} there"
+            )
+    return problems
+
+
+
+_ANY_CHART_GROUP_RE = re.compile(r"<c:(\w+Chart)\b[^>]*(?<!/)>.*?</c:\1\s*>", re.DOTALL)
+
+_AXID_RE = re.compile(
+    r"""\s*<c:axId\b[^>]*?\bval=["'](-?\d+)["']\s*(?:/>|>\s*</c:axId\s*>)"""
+)
+
+_AXIS_DECL_RE = re.compile(
+    r"""<c:(catAx|valAx|serAx|dateAx)\b[^>]*(?<!/)>\s*<c:axId\b[^>]*?\bval=["'](-?\d+)["']"""
+)
+
+AXID_LIMIT = {
+    "barChart": 2, "lineChart": 2, "areaChart": 2, "scatterChart": 2,
+    "bubbleChart": 2, "radarChart": 2, "stockChart": 2,
+    "bar3DChart": 3, "line3DChart": 3, "area3DChart": 3,
+    "surfaceChart": 3, "surface3DChart": 3,
+}
+
+AXID_MINIMUM = {
+    "barChart": 2, "lineChart": 2, "areaChart": 2, "scatterChart": 2,
+    "bubbleChart": 2, "radarChart": 2, "stockChart": 2,
+    "bar3DChart": 2, "area3DChart": 2, "surfaceChart": 2,
+    "line3DChart": 3, "surface3DChart": 3,
+}
+
+
+def _declared_axes(xml: str) -> dict[str, list[str]]:
+    axes: dict[str, list[str]] = {}
+    for kind, axid in _AXIS_DECL_RE.findall(xml):
+        axes.setdefault(kind, []).append(axid)
+    return axes
+
+
+def _canonical_ids(axes: dict[str, list[str]], limit: int) -> list[str] | None:
+    category = axes.get("catAx", []) + axes.get("dateAx", [])
+    value = axes.get("valAx", [])
+    series = axes.get("serAx", [])
+    if len(category) != 1 or len(value) != 1 or len(series) > 1:
+        return None
+    ids = [category[0], value[0]]
+    if limit >= 3 and series:
+        ids.append(series[0])
+    return ids
+
+
+def _undeclared_axes(kind: str, block: str, axes: dict[str, list[str]]) -> list[str] | None:
+    if kind not in AXID_LIMIT:
+        return None
+    ids = _AXID_RE.findall(block)
+    declared = {i for group in axes.values() for i in group}
+    if len([i for i in ids if i in declared]) >= 2:
+        return None
+    return ids
+
+
+def _check_chart_axis_references(part: str, xml: str) -> list[str]:
+    axes = _declared_axes(xml)
+    problems: list[str] = []
+    declared = {i for group in axes.values() for i in group}
+    for match in _ANY_CHART_GROUP_RE.finditer(xml):
+        kind, block = match.group(1), match.group(0)
+        ids = _undeclared_axes(kind, block, axes)
+        if ids is None:
+            continue
+        if not ids:
+            problems.append(
+                f"{part}: <c:{kind}> declares no <c:axId> this part can resolve; a chart "
+                f"group needs {AXID_MINIMUM[kind]}, and PowerPoint discards one with fewer"
+            )
+            continue
+        dead = [i for i in ids if i not in declared]
+        canonical = _canonical_ids(axes, AXID_LIMIT[kind])
+        if canonical is not None and len(canonical) >= AXID_MINIMUM[kind]:
+            hint = f"Fix: point them at the axes this part declares ({', '.join(canonical)})"
+        else:
+            hint = ("Fix: the part declares several axes of a kind -- declare the "
+                    "secondary axes the series expects, or drop them")
+        detail = (f"of which {', '.join(dead)} name no declared axis"
+                  if dead else f"only {len(ids)} of which this part declares")
+        problems.append(
+            f"{part}: <c:{kind}> references axId {', '.join(ids)}, {detail}, "
+            f"leaving fewer than two live axes; PowerPoint discards the chart. {hint}"
+        )
+    return problems
+
+
+def _ext_lst_spans(text: str) -> list[tuple[int, int]]:
+    spans: list[tuple[int, int]] = []
+    depth = 0
+    start = 0
+    for match in re.finditer(r"<(/?)c:extLst\b[^>]*?(/?)>", text):
+        closing, self_closing = match.group(1), match.group(2)
+        if self_closing:
+            continue
+        if closing:
+            depth -= 1
+            if depth == 0:
+                spans.append((start, match.end()))
+        else:
+            if depth == 0:
+                start = match.start()
+            depth += 1
+    return spans
+
+
+CHART_CHECKS = (_check_stacked_label_positions, _check_chart_axis_references)
+
+
+def find_chart_problems(files: Mapping[str, bytes]) -> list[str]:
+    problems: list[str] = []
+    for part in sorted(n for n in files if _CHART_PART_RE.fullmatch(n)):
+        xml = part_text(files[part])
+        for check in CHART_CHECKS:
+            problems.extend(check(part, xml))
+    return problems

skills/pptx/scripts/office/helpers/pptx_slide.py

@@ -0,0 +1,60 @@
+"""Pick the slide-XML schema errors PowerPoint refuses the file over.
+
+A denylist over lxml's messages, so an unrecognised error class is a miss rather
+than a false alarm.
+"""
+
+
+from __future__ import annotations
+
+import re
+
+SLIDE_PART_RE = re.compile(
+    r"ppt/(slides|slideLayouts|slideMasters|notesSlides|notesMasters|handoutMasters)"
+    r"/[^/]+\.xml"
+)
+
+FATAL_SLIDE_ERRORS: tuple[tuple[re.Pattern[str], str], ...] = (
+    (
+        re.compile(r"\}tableStyleId': This element is not expected"),
+        "two <a:tableStyleId> in one <a:tblPr> (the schema allows one)",
+    ),
+    (
+        re.compile(r"\}srgbClr', attribute 'val'"),
+        "a colour that is not six hex digits",
+    ),
+    (
+        re.compile(r"\}txBody': Missing child element"),
+        "a <p:txBody> with no children",
+    ),
+    (
+        re.compile(r"\}miter', attribute 'lim'"),
+        'a line join with lim="NaN"',
+    ),
+    (
+        re.compile(r"\}uLnTx': This element is not expected"),
+        "<a:uLnTx> in a position the schema forbids",
+    ),
+    (
+        re.compile(r"\}overrideClrMapping': This element is not expected"),
+        "<p:overrideClrMapping> in a position the schema forbids",
+    ),
+    (
+        re.compile(r"\}nvGrpSpPr': Missing child element"),
+        "a <p:nvGrpSpPr> with no children",
+    ),
+)
+
+
+def is_schema_verdict(error: str) -> bool:
+    return error.startswith("Element ")
+
+
+def fatal_slide_errors(errors: set[str]) -> list[str]:
+    out = []
+    for error in sorted(errors):
+        for pattern, meaning in FATAL_SLIDE_ERRORS:
+            if pattern.search(error):
+                out.append(f"{meaning}: {error}")
+                break
+    return out

skills/pptx/scripts/office/helpers/pptx_theme.py

@@ -0,0 +1,114 @@
+"""Find masters sharing a theme part in the way PowerPoint refuses to open.
+
+Reports only; the fix is to move <p:notesMasterIdLst> back to directly after
+<p:sldIdLst> in ppt/presentation.xml.
+"""
+
+
+from __future__ import annotations
+
+import posixpath
+import re
+from typing import Mapping
+
+from . import part_text
+
+THEME_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme"
+
+_MASTER_RE = re.compile(
+    r"^ppt/(?P<group>slideMasters|notesMasters|handoutMasters)/"
+    r"(?:slide|notes|handout)Master(?P<num>\d+)\.xml$"
+)
+_GROUP_ORDER = {"slideMasters": 0, "notesMasters": 1, "handoutMasters": 2}
+
+_RELATIONSHIP_RE = re.compile(
+    r"<Relationship\b[^>]*?(?:/>|>.*?</Relationship\s*>)", re.DOTALL
+)
+
+
+def _sort_key(name: str) -> tuple[int, int]:
+    m = _MASTER_RE.match(name)
+    assert m is not None
+    return (_GROUP_ORDER[m.group("group")], int(m.group("num")))
+
+
+def _rels_path(part: str) -> str:
+    directory, base = posixpath.split(part)
+    return f"{directory}/_rels/{base}.rels"
+
+
+def _resolve(rels_path: str, target: str) -> str:
+    if target.startswith("/"):
+        return target.lstrip("/")
+    part_dir = posixpath.dirname(posixpath.dirname(rels_path))
+    return posixpath.normpath(posixpath.join(part_dir, target))
+
+
+def _theme_rel(files: Mapping[str, bytes], master: str):
+    rels_path = _rels_path(master)
+    rels = files.get(rels_path)
+    if rels is None:
+        return None
+    for element in _RELATIONSHIP_RE.findall(part_text(rels)):
+        if f'Type="{THEME_REL_TYPE}"' not in element:
+            continue
+        target = re.search(r'\bTarget="([^"]+)"', element)
+        if target is None:
+            continue
+        return rels_path, element, _resolve(rels_path, target.group(1))
+    return None
+
+
+def _masters(files: Mapping[str, bytes]) -> list[str]:
+    return sorted((n for n in files if _MASTER_RE.match(n)), key=_sort_key)
+
+
+_PRESENTATION = "ppt/presentation.xml"
+_NOTES_MASTERS = "ppt/notesMasters/"
+_IGNORABLE_RE = re.compile(r"<!--.*?-->|<\?.*?\?>", re.DOTALL)
+_AFTER_SLDIDLST_RE = re.compile(
+    r"<p:sldIdLst\b(?:[^>]*/>|[^>]*>.*?</p:sldIdLst\s*>)\s*(<[^>\s/]+)", re.DOTALL
+)
+
+
+def _notes_master_share_is_inert(files: Mapping[str, bytes]) -> bool:
+    data = files.get(_PRESENTATION)
+    if data is None:
+        return False
+    match = _AFTER_SLDIDLST_RE.search(_IGNORABLE_RE.sub("", part_text(data)))
+    return match is not None and match.group(1) == "<p:notesMasterIdLst"
+
+
+def _shares(files: Mapping[str, bytes]):
+    owner: dict[str, str] = {}
+    for master in _masters(files):
+        found = _theme_rel(files, master)
+        if found is None:
+            continue
+        rels_path, element, theme = found
+        if theme not in files:
+            continue  
+        if theme in owner:
+            yield master, rels_path, element, theme, owner[theme]
+        else:
+            owner[theme] = master
+
+
+def _is_inert(master: str, inert_notes: bool) -> bool:
+    return inert_notes and master.startswith(_NOTES_MASTERS)
+
+
+def find_shared_master_themes(files: Mapping[str, bytes]) -> list[str]:
+    return [
+        f"{master} shares {theme} with {first}"
+        for master, _, _, theme, first in _shares(files)
+    ]
+
+
+def live_shared_master_themes(files: Mapping[str, bytes]) -> list[str]:
+    inert_notes = _notes_master_share_is_inert(files)
+    return [
+        f"{master} shares {theme} with {first}"
+        for master, _, _, theme, first in _shares(files)
+        if not _is_inert(master, inert_notes)
+    ]

skills/pptx/scripts/office/helpers/simplify_redlines.py

@@ -1,197 +0,0 @@
-"""Simplify tracked changes by merging adjacent w:ins or w:del elements.
-
-Merges adjacent <w:ins> elements from the same author into a single element.
-Same for <w:del> elements. This makes heavily-redlined documents easier to
-work with by reducing the number of tracked change wrappers.
-
-Rules:
-- Only merges w:ins with w:ins, w:del with w:del (same element type)
-- Only merges if same author (ignores timestamp differences)
-- Only merges if truly adjacent (only whitespace between them)
-"""
-
-import xml.etree.ElementTree as ET
-import zipfile
-from pathlib import Path
-
-import defusedxml.minidom
-
-WORD_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
-
-
-def simplify_redlines(input_dir: str) -> tuple[int, str]:
-    doc_xml = Path(input_dir) / "word" / "document.xml"
-
-    if not doc_xml.exists():
-        return 0, f"Error: {doc_xml} not found"
-
-    try:
-        dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding="utf-8"))
-        root = dom.documentElement
-
-        merge_count = 0
-
-        containers = _find_elements(root, "p") + _find_elements(root, "tc")
-
-        for container in containers:
-            merge_count += _merge_tracked_changes_in(container, "ins")
-            merge_count += _merge_tracked_changes_in(container, "del")
-
-        doc_xml.write_bytes(dom.toxml(encoding="UTF-8"))
-        return merge_count, f"Simplified {merge_count} tracked changes"
-
-    except Exception as e:
-        return 0, f"Error: {e}"
-
-
-def _merge_tracked_changes_in(container, tag: str) -> int:
-    merge_count = 0
-
-    tracked = [
-        child
-        for child in container.childNodes
-        if child.nodeType == child.ELEMENT_NODE and _is_element(child, tag)
-    ]
-
-    if len(tracked) < 2:
-        return 0
-
-    i = 0
-    while i < len(tracked) - 1:
-        curr = tracked[i]
-        next_elem = tracked[i + 1]
-
-        if _can_merge_tracked(curr, next_elem):
-            _merge_tracked_content(curr, next_elem)
-            container.removeChild(next_elem)
-            tracked.pop(i + 1)
-            merge_count += 1
-        else:
-            i += 1
-
-    return merge_count
-
-
-def _is_element(node, tag: str) -> bool:
-    name = node.localName or node.tagName
-    return name == tag or name.endswith(f":{tag}")
-
-
-def _get_author(elem) -> str:
-    author = elem.getAttribute("w:author")
-    if not author:
-        for attr in elem.attributes.values():
-            if attr.localName == "author" or attr.name.endswith(":author"):
-                return attr.value
-    return author
-
-
-def _can_merge_tracked(elem1, elem2) -> bool:
-    if _get_author(elem1) != _get_author(elem2):
-        return False
-
-    node = elem1.nextSibling
-    while node and node != elem2:
-        if node.nodeType == node.ELEMENT_NODE:
-            return False
-        if node.nodeType == node.TEXT_NODE and node.data.strip():
-            return False
-        node = node.nextSibling
-
-    return True
-
-
-def _merge_tracked_content(target, source):
-    while source.firstChild:
-        child = source.firstChild
-        source.removeChild(child)
-        target.appendChild(child)
-
-
-def _find_elements(root, tag: str) -> list:
-    results = []
-
-    def traverse(node):
-        if node.nodeType == node.ELEMENT_NODE:
-            name = node.localName or node.tagName
-            if name == tag or name.endswith(f":{tag}"):
-                results.append(node)
-            for child in node.childNodes:
-                traverse(child)
-
-    traverse(root)
-    return results
-
-
-def get_tracked_change_authors(doc_xml_path: Path) -> dict[str, int]:
-    if not doc_xml_path.exists():
-        return {}
-
-    try:
-        tree = ET.parse(doc_xml_path)
-        root = tree.getroot()
-    except ET.ParseError:
-        return {}
-
-    namespaces = {"w": WORD_NS}
-    author_attr = f"{{{WORD_NS}}}author"
-
-    authors: dict[str, int] = {}
-    for tag in ["ins", "del"]:
-        for elem in root.findall(f".//w:{tag}", namespaces):
-            author = elem.get(author_attr)
-            if author:
-                authors[author] = authors.get(author, 0) + 1
-
-    return authors
-
-
-def _get_authors_from_docx(docx_path: Path) -> dict[str, int]:
-    try:
-        with zipfile.ZipFile(docx_path, "r") as zf:
-            if "word/document.xml" not in zf.namelist():
-                return {}
-            with zf.open("word/document.xml") as f:
-                tree = ET.parse(f)
-                root = tree.getroot()
-
-                namespaces = {"w": WORD_NS}
-                author_attr = f"{{{WORD_NS}}}author"
-
-                authors: dict[str, int] = {}
-                for tag in ["ins", "del"]:
-                    for elem in root.findall(f".//w:{tag}", namespaces):
-                        author = elem.get(author_attr)
-                        if author:
-                            authors[author] = authors.get(author, 0) + 1
-                return authors
-    except (zipfile.BadZipFile, ET.ParseError):
-        return {}
-
-
-def infer_author(modified_dir: Path, original_docx: Path, default: str = "Claude") -> str:
-    modified_xml = modified_dir / "word" / "document.xml"
-    modified_authors = get_tracked_change_authors(modified_xml)
-
-    if not modified_authors:
-        return default
-
-    original_authors = _get_authors_from_docx(original_docx)
-
-    new_changes: dict[str, int] = {}
-    for author, count in modified_authors.items():
-        original_count = original_authors.get(author, 0)
-        diff = count - original_count
-        if diff > 0:
-            new_changes[author] = diff
-
-    if not new_changes:
-        return default
-
-    if len(new_changes) == 1:
-        return next(iter(new_changes))
-
-    raise ValueError(
-        f"Multiple authors added new changes: {new_changes}. "
-        "Cannot infer which author to validate."
-    )

skills/pptx/scripts/office/pack.py

@@ -1,159 +0,0 @@
-"""Pack a directory into a DOCX, PPTX, or XLSX file.
-
-Validates with auto-repair, condenses XML formatting, and creates the Office file.
-
-Usage:
-    python pack.py <input_directory> <output_file> [--original <file>] [--validate true|false]
-
-Examples:
-    python pack.py unpacked/ output.docx --original input.docx
-    python pack.py unpacked/ output.pptx --validate false
-"""
-
-import argparse
-import sys
-import shutil
-import tempfile
-import zipfile
-from pathlib import Path
-
-import defusedxml.minidom
-
-from validators import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator
-
-def pack(
-    input_directory: str,
-    output_file: str,
-    original_file: str | None = None,
-    validate: bool = True,
-    infer_author_func=None,
-) -> tuple[None, str]:
-    input_dir = Path(input_directory)
-    output_path = Path(output_file)
-    suffix = output_path.suffix.lower()
-
-    if not input_dir.is_dir():
-        return None, f"Error: {input_dir} is not a directory"
-
-    if suffix not in {".docx", ".pptx", ".xlsx"}:
-        return None, f"Error: {output_file} must be a .docx, .pptx, or .xlsx file"
-
-    if validate and original_file:
-        original_path = Path(original_file)
-        if original_path.exists():
-            success, output = _run_validation(
-                input_dir, original_path, suffix, infer_author_func
-            )
-            if output:
-                print(output)
-            if not success:
-                return None, f"Error: Validation failed for {input_dir}"
-
-    with tempfile.TemporaryDirectory() as temp_dir:
-        temp_content_dir = Path(temp_dir) / "content"
-        shutil.copytree(input_dir, temp_content_dir)
-
-        for pattern in ["*.xml", "*.rels"]:
-            for xml_file in temp_content_dir.rglob(pattern):
-                _condense_xml(xml_file)
-
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-        with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zf:
-            for f in temp_content_dir.rglob("*"):
-                if f.is_file():
-                    zf.write(f, f.relative_to(temp_content_dir))
-
-    return None, f"Successfully packed {input_dir} to {output_file}"
-
-
-def _run_validation(
-    unpacked_dir: Path,
-    original_file: Path,
-    suffix: str,
-    infer_author_func=None,
-) -> tuple[bool, str | None]:
-    output_lines = []
-    validators = []
-
-    if suffix == ".docx":
-        author = "Claude"
-        if infer_author_func:
-            try:
-                author = infer_author_func(unpacked_dir, original_file)
-            except ValueError as e:
-                print(f"Warning: {e} Using default author 'Claude'.", file=sys.stderr)
-
-        validators = [
-            DOCXSchemaValidator(unpacked_dir, original_file),
-            RedliningValidator(unpacked_dir, original_file, author=author),
-        ]
-    elif suffix == ".pptx":
-        validators = [PPTXSchemaValidator(unpacked_dir, original_file)]
-
-    if not validators:
-        return True, None
-
-    total_repairs = sum(v.repair() for v in validators)
-    if total_repairs:
-        output_lines.append(f"Auto-repaired {total_repairs} issue(s)")
-
-    success = all(v.validate() for v in validators)
-
-    if success:
-        output_lines.append("All validations PASSED!")
-
-    return success, "\n".join(output_lines) if output_lines else None
-
-
-def _condense_xml(xml_file: Path) -> None:
-    try:
-        with open(xml_file, encoding="utf-8") as f:
-            dom = defusedxml.minidom.parse(f)
-
-        for element in dom.getElementsByTagName("*"):
-            if element.tagName.endswith(":t"):
-                continue
-
-            for child in list(element.childNodes):
-                if (
-                    child.nodeType == child.TEXT_NODE
-                    and child.nodeValue
-                    and child.nodeValue.strip() == ""
-                ) or child.nodeType == child.COMMENT_NODE:
-                    element.removeChild(child)
-
-        xml_file.write_bytes(dom.toxml(encoding="UTF-8"))
-    except Exception as e:
-        print(f"ERROR: Failed to parse {xml_file.name}: {e}", file=sys.stderr)
-        raise
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser(
-        description="Pack a directory into a DOCX, PPTX, or XLSX file"
-    )
-    parser.add_argument("input_directory", help="Unpacked Office document directory")
-    parser.add_argument("output_file", help="Output Office file (.docx/.pptx/.xlsx)")
-    parser.add_argument(
-        "--original",
-        help="Original file for validation comparison",
-    )
-    parser.add_argument(
-        "--validate",
-        type=lambda x: x.lower() == "true",
-        default=True,
-        metavar="true|false",
-        help="Run validation with auto-repair (default: true)",
-    )
-    args = parser.parse_args()
-
-    _, message = pack(
-        args.input_directory,
-        args.output_file,
-        original_file=args.original,
-        validate=args.validate,
-    )
-    print(message)
-
-    if "Error" in message:
-        sys.exit(1)

skills/pptx/scripts/office/soffice.py

@@ -4,20 +4,23 @@ sockets may be blocked (e.g., sandboxed VMs).  Detects the restriction
 at runtime and applies an LD_PRELOAD shim if needed.
 
 Usage:
-    from office.soffice import run_soffice, get_soffice_env
+    from office.soffice import run_soffice
 
-    # Option 1 – run soffice directly
     result = run_soffice(["--headless", "--convert-to", "pdf", "input.docx"])
 
-    # Option 2 – get env dict for your own subprocess calls
-    env = get_soffice_env()
-    subprocess.run(["soffice", ...], env=env)
+Call soffice through run_soffice, not through subprocess with get_soffice_env():
+the env dict carries the shim but names no user profile, and a non-root sandbox
+cannot bootstrap the default one -- soffice aborts with "User installation could
+not be completed" and converts nothing. get_soffice_env() stays public for the
+callers that build their own argv (they must pass -env:UserInstallation too).
 """
 
+import contextlib
 import os
 import socket
 import subprocess
 import tempfile
+from collections.abc import Iterable
 from pathlib import Path
 
 
@@ -32,9 +35,15 @@ def get_soffice_env() -> dict:
     return env
 
 
-def run_soffice(args: list[str], **kwargs) -> subprocess.CompletedProcess:
-    env = get_soffice_env()
-    return subprocess.run(["soffice"] + args, env=env, **kwargs)
+def run_soffice(args: Iterable[str], **kwargs) -> subprocess.CompletedProcess:
+    args = list(args)
+    with contextlib.ExitStack() as stack:
+        if not any(str(a).startswith("-env:UserInstallation") for a in args):
+            profile = stack.enter_context(
+                tempfile.TemporaryDirectory(prefix="lo_profile_", ignore_cleanup_errors=True)
+            )
+            args = [f"-env:UserInstallation={Path(profile).as_uri()}"] + args
+        return subprocess.run(["soffice"] + args, env=get_soffice_env(), **kwargs)
 
 
 

skills/pptx/scripts/office/unpack.py

@@ -1,132 +0,0 @@
-"""Unpack Office files (DOCX, PPTX, XLSX) for editing.
-
-Extracts the ZIP archive, pretty-prints XML files, and optionally:
-- Merges adjacent runs with identical formatting (DOCX only)
-- Simplifies adjacent tracked changes from same author (DOCX only)
-
-Usage:
-    python unpack.py <office_file> <output_dir> [options]
-
-Examples:
-    python unpack.py document.docx unpacked/
-    python unpack.py presentation.pptx unpacked/
-    python unpack.py document.docx unpacked/ --merge-runs false
-"""
-
-import argparse
-import sys
-import zipfile
-from pathlib import Path
-
-import defusedxml.minidom
-
-from helpers.merge_runs import merge_runs as do_merge_runs
-from helpers.simplify_redlines import simplify_redlines as do_simplify_redlines
-
-SMART_QUOTE_REPLACEMENTS = {
-    "\u201c": "&#x201C;",  
-    "\u201d": "&#x201D;",  
-    "\u2018": "&#x2018;",  
-    "\u2019": "&#x2019;",  
-}
-
-
-def unpack(
-    input_file: str,
-    output_directory: str,
-    merge_runs: bool = True,
-    simplify_redlines: bool = True,
-) -> tuple[None, str]:
-    input_path = Path(input_file)
-    output_path = Path(output_directory)
-    suffix = input_path.suffix.lower()
-
-    if not input_path.exists():
-        return None, f"Error: {input_file} does not exist"
-
-    if suffix not in {".docx", ".pptx", ".xlsx"}:
-        return None, f"Error: {input_file} must be a .docx, .pptx, or .xlsx file"
-
-    try:
-        output_path.mkdir(parents=True, exist_ok=True)
-
-        with zipfile.ZipFile(input_path, "r") as zf:
-            zf.extractall(output_path)
-
-        xml_files = list(output_path.rglob("*.xml")) + list(output_path.rglob("*.rels"))
-        for xml_file in xml_files:
-            _pretty_print_xml(xml_file)
-
-        message = f"Unpacked {input_file} ({len(xml_files)} XML files)"
-
-        if suffix == ".docx":
-            if simplify_redlines:
-                simplify_count, _ = do_simplify_redlines(str(output_path))
-                message += f", simplified {simplify_count} tracked changes"
-
-            if merge_runs:
-                merge_count, _ = do_merge_runs(str(output_path))
-                message += f", merged {merge_count} runs"
-
-        for xml_file in xml_files:
-            _escape_smart_quotes(xml_file)
-
-        return None, message
-
-    except zipfile.BadZipFile:
-        return None, f"Error: {input_file} is not a valid Office file"
-    except Exception as e:
-        return None, f"Error unpacking: {e}"
-
-
-def _pretty_print_xml(xml_file: Path) -> None:
-    try:
-        content = xml_file.read_text(encoding="utf-8")
-        dom = defusedxml.minidom.parseString(content)
-        xml_file.write_bytes(dom.toprettyxml(indent="  ", encoding="utf-8"))
-    except Exception:
-        pass  
-
-
-def _escape_smart_quotes(xml_file: Path) -> None:
-    try:
-        content = xml_file.read_text(encoding="utf-8")
-        for char, entity in SMART_QUOTE_REPLACEMENTS.items():
-            content = content.replace(char, entity)
-        xml_file.write_text(content, encoding="utf-8")
-    except Exception:
-        pass
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser(
-        description="Unpack an Office file (DOCX, PPTX, XLSX) for editing"
-    )
-    parser.add_argument("input_file", help="Office file to unpack")
-    parser.add_argument("output_directory", help="Output directory")
-    parser.add_argument(
-        "--merge-runs",
-        type=lambda x: x.lower() == "true",
-        default=True,
-        metavar="true|false",
-        help="Merge adjacent runs with identical formatting (DOCX only, default: true)",
-    )
-    parser.add_argument(
-        "--simplify-redlines",
-        type=lambda x: x.lower() == "true",
-        default=True,
-        metavar="true|false",
-        help="Merge adjacent tracked changes from same author (DOCX only, default: true)",
-    )
-    args = parser.parse_args()
-
-    _, message = unpack(
-        args.input_file,
-        args.output_directory,
-        merge_runs=args.merge_runs,
-        simplify_redlines=args.simplify_redlines,
-    )
-    print(message)
-
-    if "Error" in message:
-        sys.exit(1)

skills/pptx/scripts/office/validate.py

@@ -6,7 +6,7 @@ Usage:
 
 The first argument can be either:
 - An unpacked directory containing the Office document XML files
-- A packed Office file (.docx/.pptx/.xlsx) which will be unpacked to a temp directory
+- A packed Office file (.docx/.pptx/.xlsx or .dotx/.potx/.xltx template) which will be unpacked to a temp directory
 
 Auto-repair fixes:
 - paraId/durableId values that exceed OOXML limits
@@ -19,20 +19,43 @@ import tempfile
 import zipfile
 from pathlib import Path
 
+import defusedxml.ElementTree as ET
+from defusedxml.common import DefusedXmlException
+
+from helpers import OOXML_FAMILY, rezip, safe_extract
 from validators import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator
 
+WORD_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+
+def _fail(message: str):
+    print(f"Error: {message}", file=sys.stderr)
+    sys.exit(2)
+
+
+def _has_tracked_changes(unpacked_dir: Path) -> bool:
+    document = unpacked_dir / "word" / "document.xml"
+    if not document.is_file():
+        return False
+    try:
+        root = ET.parse(document).getroot()
+    except (ET.ParseError, DefusedXmlException):
+        return False  
+    tracked = {f"{{{WORD_NS}}}ins", f"{{{WORD_NS}}}del"}
+    return any(elem.tag in tracked for elem in root.iter())
+
 
 def main():
     parser = argparse.ArgumentParser(description="Validate Office document XML files")
     parser.add_argument(
         "path",
-        help="Path to unpacked directory or packed Office file (.docx/.pptx/.xlsx)",
+        help="Path to unpacked directory or packed Office file (.docx/.pptx/.xlsx or .dotx/.potx/.xltx)",
     )
     parser.add_argument(
         "--original",
         required=False,
         default=None,
-        help="Path to original file (.docx/.pptx/.xlsx). If omitted, all XSD errors are reported and redlining validation is skipped.",
+        help="Path to original file (.docx/.pptx/.xlsx or .dotx/.potx/.xltx). If omitted, all XSD errors are reported and redlining validation is skipped.",
     )
     parser.add_argument(
         "-v",
@@ -43,63 +66,102 @@ def main():
     parser.add_argument(
         "--auto-repair",
         action="store_true",
-        help="Automatically repair common issues (hex IDs, whitespace preservation)",
+        help="Automatically repair common issues (hex IDs, whitespace preservation). "
+        "Modifies the input in place: repairs to a packed file are written back to it.",
     )
     parser.add_argument(
         "--author",
-        default="Claude",
-        help="Author name for redlining validation (default: Claude)",
+        default=None,
+        help="The name you are redlining under. Passing it turns on the "
+        "tracked-change check: any text differing from --original without a "
+        "<w:ins>/<w:del> recording it is reported. Untracked edits carry no "
+        "author, so the check covers them whoever made them — the name marks "
+        "the run as redlining work and is not used to filter. Requires "
+        "--original; docx only.",
     )
     args = parser.parse_args()
 
+    if args.author is not None and not args.original:
+        _fail("--author requires --original")
+
     path = Path(args.path)
-    assert path.exists(), f"Error: {path} does not exist"
+    if not path.exists():
+        _fail(f"{path} does not exist")
 
     original_file = None
     if args.original:
         original_file = Path(args.original)
-        assert original_file.is_file(), f"Error: {original_file} is not a file"
-        assert original_file.suffix.lower() in [".docx", ".pptx", ".xlsx"], (
-            f"Error: {original_file} must be a .docx, .pptx, or .xlsx file"
+        if not original_file.is_file():
+            _fail(f"{original_file} is not a file")
+        if original_file.suffix.lower() not in OOXML_FAMILY:
+            _fail(f"{original_file} must be one of: {', '.join(sorted(OOXML_FAMILY))}")
+
+    family = OOXML_FAMILY.get((original_file or path).suffix.lower())
+    if family is None:
+        _fail(
+            f"Cannot determine file type from {path}. Use --original or provide one of: {', '.join(sorted(OOXML_FAMILY))}."
         )
 
-    file_extension = (original_file or path).suffix.lower()
-    assert file_extension in [".docx", ".pptx", ".xlsx"], (
-        f"Error: Cannot determine file type from {path}. Use --original or provide a .docx/.pptx/.xlsx file."
-    )
+    if args.author is not None and family != "docx":
+        _fail(f"--author only applies to docx files, not {family}")
 
-    if path.is_file() and path.suffix.lower() in [".docx", ".pptx", ".xlsx"]:
-        temp_dir = tempfile.mkdtemp()
-        with zipfile.ZipFile(path, "r") as zf:
-            zf.extractall(temp_dir)
-        unpacked_dir = Path(temp_dir)
+    packed_file = None
+    temp_dir_ctx = None
+    if path.is_file() and path.suffix.lower() in OOXML_FAMILY:
+        packed_file = path
+        temp_dir_ctx = tempfile.TemporaryDirectory()
+        unpacked_dir = Path(temp_dir_ctx.name)
+        try:
+            with zipfile.ZipFile(path, "r") as zf:
+                safe_extract(zf, unpacked_dir)
+        except (zipfile.BadZipFile, ValueError, OSError) as e:
+            _fail(f"cannot unpack {path}: {e}")
     else:
-        assert path.is_dir(), f"Error: {path} is not a directory or Office file"
+        if not path.is_dir():
+            _fail(f"{path} is not a directory or Office file")
         unpacked_dir = path
 
-    match file_extension:
-        case ".docx":
+    match family:
+        case "docx":
             validators = [
                 DOCXSchemaValidator(unpacked_dir, original_file, verbose=args.verbose),
             ]
-            if original_file:
+            if args.author is not None:
                 validators.append(
-                    RedliningValidator(unpacked_dir, original_file, verbose=args.verbose, author=args.author)  
+                    RedliningValidator(unpacked_dir, original_file, verbose=args.verbose)  
                 )
-        case ".pptx":
+            elif original_file and _has_tracked_changes(unpacked_dir):
+                print(
+                    "Note: this document has tracked changes; they were not "
+                    "checked against the original (pass --author to check)."
+                )
+        case "pptx":
             validators = [
                 PPTXSchemaValidator(unpacked_dir, original_file, verbose=args.verbose),
             ]
+        case "xlsx":
+            exts = ", ".join(k for k, v in sorted(OOXML_FAMILY.items()) if v == "xlsx")
+            print(
+                f"No XSD schema validation is performed for xlsx-family files ({exts}). "
+                "For formula-error checking, use scripts/recalc.py instead."
+            )
+            sys.exit(0)
         case _:
-            print(f"Error: Validation not supported for file type {file_extension}")
+            print(f"Error: Validation not supported for file type {family}")
             sys.exit(1)
 
     if args.auto_repair:
         total_repairs = sum(v.repair() for v in validators)
         if total_repairs:
             print(f"Auto-repaired {total_repairs} issue(s)")
+            if packed_file is not None:
+                rezip(unpacked_dir, packed_file)
+                print(f"Wrote repaired file to {packed_file}")
 
-    success = all(v.validate() for v in validators)
+    success = all([v.validate() for v in validators])
+
+    if temp_dir_ctx is not None:
+        temp_dir_ctx.cleanup()
 
     if success:
         print("All validations PASSED!")

skills/pptx/scripts/office/validators/base.py

@@ -6,8 +6,20 @@ import re
 from pathlib import Path
 
 import defusedxml.minidom
+from functools import lru_cache
+
 import lxml.etree
 
+from helpers import safe_extract
+
+
+@lru_cache(maxsize=None)
+def _load_schema(schema_path: str):
+    with open(schema_path, "rb") as xsd_file:
+        xsd_doc = lxml.etree.parse(
+            xsd_file, parser=lxml.etree.XMLParser(), base_url=schema_path
+        )
+    return lxml.etree.XMLSchema(xsd_doc)
 
 class BaseSchemaValidator:
 
@@ -119,21 +131,28 @@ class BaseSchemaValidator:
             try:
                 content = xml_file.read_text(encoding="utf-8")
                 dom = defusedxml.minidom.parseString(content)
-                modified = False
+                pending = []  
 
                 for elem in dom.getElementsByTagName("*"):
-                    if elem.tagName.endswith(":t") and elem.firstChild:
-                        text = elem.firstChild.nodeValue
-                        if text and (text.startswith((' ', '\t')) or text.endswith((' ', '\t'))):
+                    local_name = elem.tagName.rsplit(":", 1)[-1]
+                    if local_name in ("t", "delText", "instrText", "delInstrText"):
+                        text = "".join(
+                            child.data
+                            for child in elem.childNodes
+                            if child.nodeType in (child.TEXT_NODE, child.CDATA_SECTION_NODE)
+                        )
+                        ws = (" ", "\t", "\n", "\r")
+                        if text and (text.startswith(ws) or text.endswith(ws)):
                             if elem.getAttribute("xml:space") != "preserve":
                                 elem.setAttribute("xml:space", "preserve")
                                 text_preview = repr(text[:30]) + "..." if len(text) > 30 else repr(text)
-                                print(f"  Repaired: {xml_file.name}: Added xml:space='preserve' to {elem.tagName}: {text_preview}")
-                                repairs += 1
-                                modified = True
+                                pending.append(f"  Repaired: {xml_file.name}: Added xml:space='preserve' to {elem.tagName}: {text_preview}")
 
-                if modified:
+                if pending:
                     xml_file.write_bytes(dom.toxml(encoding="UTF-8"))
+                    for message in pending:
+                        print(message)
+                    repairs += len(pending)
 
             except Exception:
                 pass
@@ -212,6 +231,8 @@ class BaseSchemaValidator:
                     elem.getparent().remove(elem)
 
                 for elem in root.iter():
+                    if not hasattr(elem, "tag") or callable(elem.tag):
+                        continue
                     tag = (
                         elem.tag.split("}")[-1].lower()
                         if "}" in elem.tag
@@ -326,6 +347,8 @@ class BaseSchemaValidator:
                     namespaces={"ns": self.PACKAGE_RELATIONSHIPS_NAMESPACE},
                 ):
                     target = rel.get("Target")
+                    if rel.get("TargetMode") == "External":
+                        continue
                     if target and not target.startswith(
                         ("http", "mailto:")
                     ):  
@@ -423,6 +446,8 @@ class BaseSchemaValidator:
                 r_ns = self.OFFICE_RELATIONSHIPS_NAMESPACE
                 rid_attrs_to_check = ["id", "embed", "link"]
                 for elem in xml_root.iter():
+                    if not hasattr(elem, "tag") or callable(elem.tag):
+                        continue
                     for attr_name in rid_attrs_to_check:
                         rid_attr = elem.get(f"{{{r_ns}}}{attr_name}")
                         if not rid_attr:
@@ -747,18 +772,16 @@ class BaseSchemaValidator:
 
         return xml_doc
 
-    def _validate_single_file_xsd(self, xml_file, base_path):
-        schema_path = self._get_schema_path(xml_file)
+    def _preprocess_for_schema(self, xml_doc, relative_path):
+        return xml_doc
+
+    def _validate_single_file_xsd(self, xml_file, base_path, schema_path=None):
+        schema_path = schema_path or self._get_schema_path(xml_file)
         if not schema_path:
             return None, None  
 
         try:
-            with open(schema_path, "rb") as xsd_file:
-                parser = lxml.etree.XMLParser()
-                xsd_doc = lxml.etree.parse(
-                    xsd_file, parser=parser, base_url=str(schema_path)
-                )
-                schema = lxml.etree.XMLSchema(xsd_doc)
+            schema = _load_schema(str(schema_path))
 
             with open(xml_file, "r") as f:
                 xml_doc = lxml.etree.parse(f)
@@ -773,6 +796,8 @@ class BaseSchemaValidator:
             ):
                 xml_doc = self._clean_ignorable_namespaces(xml_doc)
 
+            xml_doc = self._preprocess_for_schema(xml_doc, relative_path)
+
             if schema.validate(xml_doc):
                 return True, set()
             else:
@@ -784,7 +809,7 @@ class BaseSchemaValidator:
         except Exception as e:
             return False, {str(e)}
 
-    def _get_original_file_errors(self, xml_file):
+    def _get_original_file_errors(self, xml_file, schema_path=None):
         if self.original_file is None:
             return set()
 
@@ -798,8 +823,11 @@ class BaseSchemaValidator:
         with tempfile.TemporaryDirectory() as temp_dir:
             temp_path = Path(temp_dir)
 
-            with zipfile.ZipFile(self.original_file, "r") as zip_ref:
-                zip_ref.extractall(temp_path)
+            try:
+                with zipfile.ZipFile(self.original_file, "r") as zip_ref:
+                    safe_extract(zip_ref, temp_path)
+            except (zipfile.BadZipFile, ValueError, OSError):
+                return set()
 
             original_xml_file = temp_path / relative_path
 
@@ -807,7 +835,7 @@ class BaseSchemaValidator:
                 return set()
 
             is_valid, errors = self._validate_single_file_xsd(
-                original_xml_file, temp_path
+                original_xml_file, temp_path, schema_path=schema_path
             )
             return errors if errors else set()