@cyanheads/pixoo-mcp-server 1.1.2 → 1.1.4

package/AGENTS.md

@@ -1,11 +1,11 @@
 # Developer Protocol
 
 **Server:** pixoo-mcp-server
-**Version:** 1.1.2
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.2`
+**Version:** 1.1.4
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0 (protocol revision 2026-07-28 alongside the 2025 era)
-**Zod:** ^4.6.4
+**Zod:** ^4.6.5
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -165,6 +165,7 @@ Handlers receive a unified `ctx` object. Key properties used by this server:
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
 | `ctx.enrich` | Success-path agent context — `.notice()` / `.total()` / `.echo()` / `.truncated()`. Lands only when the definition declares an `enrichment` block. |
 | `ctx.fail` | Typed throw against the definition's `errors[]` reason union — auto-populates `data.reason`. |
+| `ctx.recoveryFor` | `{ recovery: { hint } }` for a declared reason, resolved from the contract. Pass it as `ctx.fail`'s data argument (or spread it in) to put the declared hint on the wire. |
 | `ctx.state` | Tenant-scoped KV — `.get`, `.set(key, value, { ttl? })`, `.delete`, `.getMany`, `.list`. Keys are validated; colons are not legal separators. |
 | `ctx.requestInput` / `ctx.inputs` | Multi-round-trip input. `return ctx.requestInput(...)`; read the answers with `ctx.inputs.accepted(key, schema)` on re-entry. Unused by this server. |
 | `ctx.signal` | `AbortSignal` for cancellation. Pass it to any long-running I/O. |
@@ -179,28 +180,36 @@ Handlers throw — the framework catches, classifies, and formats.
 
 Pixoo-specific error reasons declared on tools:
 
-| Reason | Code | When |
-|:-------|:-----|:-----|
-| `device_unreachable` | `ServiceUnavailable` | Toolkit result kind `network`/`timeout` |
-| `device_http_error` | `ServiceUnavailable` | Non-2xx from the device's HTTP server |
-| `device_rejected` | `ServiceUnavailable` | Firmware returned non-zero `error_code` |
-| `no_device_configured` | `InvalidParams` | Device tool called without `PIXOO_IP` |
-| `asset_not_found` | `NotFound` | Image/sprite path or URL unreadable |
-| `invalid_color` | `InvalidParams` | `resolveColor` throw — invalid color name or format |
-| `unknown_icon` | `InvalidParams` | Icon name not in registry |
-| `discovery_failed` | `ServiceUnavailable` | Divoom cloud unreachable |
+| Reason | Code | When | `retryable` |
+|:-------|:-----|:-----|:------------|
+| `device_unreachable` | `ServiceUnavailable` | Toolkit result kind `network`/`timeout` | `true` |
+| `device_http_error` | `ServiceUnavailable` | Non-2xx from the device's HTTP server | `true` for 408, 429, 500, 502–504; `false` otherwise |
+| `device_rejected` | `ServiceUnavailable` | Firmware returned non-zero `error_code` | — |
+| `no_device_configured` | `InvalidParams` | Device tool called without `PIXOO_IP` | — |
+| `asset_not_found` | `NotFound` | Image/sprite path or URL unreadable | — |
+| `invalid_color` | `InvalidParams` | `resolveColor` throw — invalid color name or format | — |
+| `unknown_icon` | `InvalidParams` | Icon name not in registry | — |
+| `discovery_failed` | `ServiceUnavailable` | Divoom cloud unreachable | `true` |
+
+`PixooService` and `src/renderer/` raise the device, configuration, and asset reasons themselves (a factory error carrying `data.reason`), so those entries carry `thrownBy: 'service'` — lint-only metadata that keeps `error-contract-unthrown` from reading them as dead. A reason the handler throws with `ctx.fail` stays unmarked, and every such site forwards its declared recovery with `ctx.recoveryFor`. A computed reason forwards the same way (`ctx.recoveryFor(reason)`); `lint:mcp` skips a definition whose `ctx.fail` reason is non-literal, so a clean lint says nothing about those sites.
+
+A contract's `retryable` reaches the wire only through `ctx.fail`; a service throw carries it only when the service writes `data.retryable` itself. `classifyDeviceFailure` (in `pixoo-service.ts`) is the one place a failed device call becomes a reason and a retryability — `PixooService` writes both on its push-path throws, and `pixoo_overlay_text` passes the retryability into `ctx.fail` so it overrides the contract default per occurrence.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 
 errors: [
   { reason: 'no_device_configured', code: JsonRpcErrorCode.InvalidParams,
-    when: 'PIXOO_IP not configured',
-    recovery: 'Run pixoo_discover_devices to find device IPs, then set PIXOO_IP.' },
-  { reason: 'device_unreachable', code: JsonRpcErrorCode.ServiceUnavailable,
-    when: 'Device network timeout or connection refused',
-    recovery: 'Check the device is on the same LAN and powered on, then retry.' },
+    when: 'PIXOO_IP is not set.',
+    recovery: 'Run pixoo_discover_devices to find the device IP, then set PIXOO_IP.',
+    thrownBy: 'service' },
+  { reason: 'invalid_color', code: JsonRpcErrorCode.InvalidParams,
+    when: 'The color value could not be resolved.',
+    recovery: 'Use a hex color (#RRGGBB or #RGB, with or without the #) or a case-insensitive named color such as white, orange, or claude.' },
 ],
+
+// in the handler
+throw ctx.fail('invalid_color', `Invalid color "${input.color}"`, ctx.recoveryFor('invalid_color'));
 ```
 
 Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring. A tool argument that fails the input schema reaches the client as `InvalidParams` (-32602) with `structuredContent.error` — assert that code, not `ValidationError`, in tests.
@@ -284,7 +293,7 @@ Available skills:
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
-| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixup commits autosquashed into the stack, PR body kept in sync. Release PR mode only |
+| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
 | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
@@ -331,6 +340,8 @@ Available skills:
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
+**CI is one file.** `.github/workflows/codeql.yml` is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
+
 ---
 
 ## Bundling
@@ -351,6 +362,12 @@ Each per-version file opens with YAML frontmatter: `summary` (required, ≤350 c
 
 ---
 
+## Publishing
+
+**Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
+
+---
+
 ## Checklist
 
 - [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)

package/CLAUDE.md

@@ -1,11 +1,11 @@
 # Developer Protocol
 
 **Server:** pixoo-mcp-server
-**Version:** 1.1.2
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.2`
+**Version:** 1.1.4
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0 (protocol revision 2026-07-28 alongside the 2025 era)
-**Zod:** ^4.6.4
+**Zod:** ^4.6.5
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -165,6 +165,7 @@ Handlers receive a unified `ctx` object. Key properties used by this server:
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
 | `ctx.enrich` | Success-path agent context — `.notice()` / `.total()` / `.echo()` / `.truncated()`. Lands only when the definition declares an `enrichment` block. |
 | `ctx.fail` | Typed throw against the definition's `errors[]` reason union — auto-populates `data.reason`. |
+| `ctx.recoveryFor` | `{ recovery: { hint } }` for a declared reason, resolved from the contract. Pass it as `ctx.fail`'s data argument (or spread it in) to put the declared hint on the wire. |
 | `ctx.state` | Tenant-scoped KV — `.get`, `.set(key, value, { ttl? })`, `.delete`, `.getMany`, `.list`. Keys are validated; colons are not legal separators. |
 | `ctx.requestInput` / `ctx.inputs` | Multi-round-trip input. `return ctx.requestInput(...)`; read the answers with `ctx.inputs.accepted(key, schema)` on re-entry. Unused by this server. |
 | `ctx.signal` | `AbortSignal` for cancellation. Pass it to any long-running I/O. |
@@ -179,28 +180,36 @@ Handlers throw — the framework catches, classifies, and formats.
 
 Pixoo-specific error reasons declared on tools:
 
-| Reason | Code | When |
-|:-------|:-----|:-----|
-| `device_unreachable` | `ServiceUnavailable` | Toolkit result kind `network`/`timeout` |
-| `device_http_error` | `ServiceUnavailable` | Non-2xx from the device's HTTP server |
-| `device_rejected` | `ServiceUnavailable` | Firmware returned non-zero `error_code` |
-| `no_device_configured` | `InvalidParams` | Device tool called without `PIXOO_IP` |
-| `asset_not_found` | `NotFound` | Image/sprite path or URL unreadable |
-| `invalid_color` | `InvalidParams` | `resolveColor` throw — invalid color name or format |
-| `unknown_icon` | `InvalidParams` | Icon name not in registry |
-| `discovery_failed` | `ServiceUnavailable` | Divoom cloud unreachable |
+| Reason | Code | When | `retryable` |
+|:-------|:-----|:-----|:------------|
+| `device_unreachable` | `ServiceUnavailable` | Toolkit result kind `network`/`timeout` | `true` |
+| `device_http_error` | `ServiceUnavailable` | Non-2xx from the device's HTTP server | `true` for 408, 429, 500, 502–504; `false` otherwise |
+| `device_rejected` | `ServiceUnavailable` | Firmware returned non-zero `error_code` | — |
+| `no_device_configured` | `InvalidParams` | Device tool called without `PIXOO_IP` | — |
+| `asset_not_found` | `NotFound` | Image/sprite path or URL unreadable | — |
+| `invalid_color` | `InvalidParams` | `resolveColor` throw — invalid color name or format | — |
+| `unknown_icon` | `InvalidParams` | Icon name not in registry | — |
+| `discovery_failed` | `ServiceUnavailable` | Divoom cloud unreachable | `true` |
+
+`PixooService` and `src/renderer/` raise the device, configuration, and asset reasons themselves (a factory error carrying `data.reason`), so those entries carry `thrownBy: 'service'` — lint-only metadata that keeps `error-contract-unthrown` from reading them as dead. A reason the handler throws with `ctx.fail` stays unmarked, and every such site forwards its declared recovery with `ctx.recoveryFor`. A computed reason forwards the same way (`ctx.recoveryFor(reason)`); `lint:mcp` skips a definition whose `ctx.fail` reason is non-literal, so a clean lint says nothing about those sites.
+
+A contract's `retryable` reaches the wire only through `ctx.fail`; a service throw carries it only when the service writes `data.retryable` itself. `classifyDeviceFailure` (in `pixoo-service.ts`) is the one place a failed device call becomes a reason and a retryability — `PixooService` writes both on its push-path throws, and `pixoo_overlay_text` passes the retryability into `ctx.fail` so it overrides the contract default per occurrence.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 
 errors: [
   { reason: 'no_device_configured', code: JsonRpcErrorCode.InvalidParams,
-    when: 'PIXOO_IP not configured',
-    recovery: 'Run pixoo_discover_devices to find device IPs, then set PIXOO_IP.' },
-  { reason: 'device_unreachable', code: JsonRpcErrorCode.ServiceUnavailable,
-    when: 'Device network timeout or connection refused',
-    recovery: 'Check the device is on the same LAN and powered on, then retry.' },
+    when: 'PIXOO_IP is not set.',
+    recovery: 'Run pixoo_discover_devices to find the device IP, then set PIXOO_IP.',
+    thrownBy: 'service' },
+  { reason: 'invalid_color', code: JsonRpcErrorCode.InvalidParams,
+    when: 'The color value could not be resolved.',
+    recovery: 'Use a hex color (#RRGGBB or #RGB, with or without the #) or a case-insensitive named color such as white, orange, or claude.' },
 ],
+
+// in the handler
+throw ctx.fail('invalid_color', `Invalid color "${input.color}"`, ctx.recoveryFor('invalid_color'));
 ```
 
 Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring. A tool argument that fails the input schema reaches the client as `InvalidParams` (-32602) with `structuredContent.error` — assert that code, not `ValidationError`, in tests.
@@ -284,7 +293,7 @@ Available skills:
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
-| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixup commits autosquashed into the stack, PR body kept in sync. Release PR mode only |
+| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
 | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
@@ -331,6 +340,8 @@ Available skills:
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
+**CI is one file.** `.github/workflows/codeql.yml` is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
+
 ---
 
 ## Bundling
@@ -351,6 +362,12 @@ Each per-version file opens with YAML frontmatter: `summary` (required, ≤350 c
 
 ---
 
+## Publishing
+
+**Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
+
+---
+
 ## Checklist
 
 - [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-1.1.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/pixoo-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/pixoo-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pixoo-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-1.1.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/pixoo-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/pixoo-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pixoo-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -66,7 +66,8 @@ All resource data is also reachable via tools. `pixoo_design_brief` surfaces the
 - Up to 50 layered elements rendered back-to-front: `text`, `icon`, `rect`, `circle`, `line`, `progress`, `sparkline`, `bitmap`, `pixels`, `image`, `sprite`
 - Background: solid color, gradient (vertical, horizontal, or radial), or named theme
 - Animation via named effect presets (`float`, `scroll-left`, `scroll-right`, `pulse`, `blink`, `twinkle`, `drift`, `fade-in`, `fade-out`) or raw per-property keyframe arrays — 1–40 frames at 10–2000ms per frame (default 150ms)
-- `image` and `sprite` elements accept an absolute local path or an https URL; a supplied `output` path must be absolute with no traversal segments
+- `image` elements accept an absolute local path or an https URL; `sprite` elements take an absolute local path; a supplied `output` path must be absolute with no traversal segments
+- `opacity` (0–100) blends any element, images included, over the layers beneath it
 - Static scenes return a PNG preview; animations return a labeled contact-sheet PNG plus a saved GIF (GIF preview is inconsistent across MCP clients)
 - Typed failures for `asset_not_found`, `invalid_color`, and `unknown_icon`, alongside the shared device-error reasons
 
@@ -74,7 +75,7 @@ All resource data is also reachable via tools. `pixoo_design_brief` surfaces the
 
 ### `pixoo_push_image` <sub>tool</sub>
 
-- Accepts an absolute local file path or an https (not http) URL
+- Accepts an absolute local file path or an https (not http) URL; a URL response is capped at 10 MB, enforced while the body streams
 - Three fit modes: `contain` (letterbox), `cover` (crop to fill), `fill` (stretch)
 - Three resize kernels: `nearest` for pixel art (default), `lanczos3` for photos, `mitchell` for a balance
 - Returns the exact resized result as an image content block before it is pushed
@@ -85,7 +86,7 @@ All resource data is also reachable via tools. `pixoo_design_brief` surfaces the
 
 - `mode: "set"` adds or updates an overlay on one of 20 independent slots (`id` 0–19); `mode: "clear"` removes it
 - 115 device-rendered font IDs (0–114); overlays persist across channel switches until explicitly cleared
-- Configurable `x`/`y` (0–64), scroll `direction` (`left`/`right`), `speed` (0–100), and `align`; color is `#RRGGBB` hex only — named colors aren't supported here
+- Configurable `x`/`y` (0–64), scroll `direction` (`left`/`right`), `speed` (0–100), and `align`; color accepts hex (`#RRGGBB` or `#RGB`) or a named color, the same as the render tools
 - Device-rendered, not previewable — for styled, previewable text use `pixoo_display_text`
 
 ---
@@ -93,7 +94,7 @@ All resource data is also reachable via tools. `pixoo_design_brief` surfaces the
 ### `pixoo_control_device` <sub>tool</sub>
 
 - Call with no params to read state only; supply any of `brightness` (0–100), `screen` (`on`/`off`), `channel` (`faces`/`cloud`/`visualizer`/`custom`), or `clockFaceId` to apply changes before the read-back
-- `applied` lists which requested settings succeeded; a failed setting is omitted from `applied` and reported via an enrichment notice instead of failing the call
+- `applied` lists which requested settings succeeded; a failed setting is omitted from `applied` and reported in a `notice` instead of failing the call — every failed setting in one call, each with its failure kind and message
 - Always returns current `reachable`, `channel`, `brightness`, `screenOn`, and `clockId` (the latter three absent when the device is unreachable)
 
 ---
@@ -162,8 +163,8 @@ Agent-friendly output:
 
 - Preview-as-content — render tools return the upscaled (8×, 512px) output as an image content block, so the calling model sees exactly what was drawn, before and after push
 - Layout transparency — every silent renderer decision (font fallback, truncation, scroll engaged, element clipped) is reported in `layout[]` so agents can inspect and refine
-- Device truth — `pushed` reflects the device ACK; `deviceState` after a push flags visibility issues (screen off, brightness ≤ 10, wrong channel) as enrichment notices rather than failures
-- Graceful degradation — render succeeds and returns the preview even when the device is unreachable, so the agent keeps its work
+- Device truth — `pushed` reflects the device ACK; `deviceState` after a push reports the channel, brightness, and screen state the device returned
+- Render without a device — `push: false` renders and returns the preview with no device reachable; a push to an unreachable device fails with a retryable `device_unreachable` error
 
 ## Getting started
 
@@ -275,7 +276,7 @@ All configuration is validated at startup via Zod schemas in `src/config/server-
 | `PIXOO_PUSH_MIN_INTERVAL_MS` | Minimum interval between device pushes in milliseconds. Prevents device freeze from rapid-fire commands. | `1000` |
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
 | `MCP_HTTP_PORT` | HTTP server port. | `3010` |
-| `MCP_SESSION_MODE` | HTTP session handling: `stateful`, `stateless`, or `auto`. The server declares `stateless` in source — no tool requests input mid-call — and a value set here overrides it. | `stateless` |
+| `MCP_SESSION_MODE` | HTTP session handling: `stateful`, `stateless`, or `auto` (the framework's schema default, which resolves to `stateful`). The server declares `stateless` in source — no tool requests input mid-call — and a value set here overrides it. | `stateless` |
 | `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth`. | `none` |
 | `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.). | `info` |
 | `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |

package/changelog/1.1.x/1.1.3.md

@@ -0,0 +1,30 @@
+---
+summary: "Errors thrown in the tool handlers now forward their declared recovery hint to callers; invalid_color hints match what resolveColor accepts; pixoo_control_device drops two error reasons it could never emit (#8). mcp-ts-core ^0.13.2 → ^0.13.6 adds a Recovery: hint on argument rejections and key normalization for tool calls."
+breaking: false
+security: false
+---
+
+# 1.1.3 — 2026-09-21
+
+## Changed
+
+- **Declared recovery hints reach the caller** — errors thrown in the tool handlers (`invalid_color`, `unknown_icon`, `invalid_output_path`, local-path `asset_not_found`, and `pixoo_overlay_text`'s `device_unreachable`/`device_rejected`) now carry `error.data.recovery.hint` and a `Recovery:` line in the text; previously those errors carried only `data.reason`.
+- **`invalid_color` hints match what `resolveColor` accepts** — hex (`#RRGGBB`/`#RGB`, `#` optional) or a case-insensitive named color. `pixoo_overlay_text`'s hint used to say named colors were unsupported for overlays, but its handler always resolved them (#8).
+- **`pixoo_control_device` no longer declares `device_unreachable`/`device_rejected`** — its setters report failures in the result instead of throwing, so neither reason could occur; only the advertised `reason` examples change.
+- `pixoo_design_brief`'s color-troubleshooting topic now says named colors are case-insensitive, matching `resolveColor`.
+- Server `instructions` reworded to one two-sentence string, following the framework's instructions-shape guidance.
+- Service-raised error reasons are marked `thrownBy: 'service'` in each tool's error contract — lint metadata only, no wire effect.
+- **Argument rejections carry a schema-derived `Recovery:` hint** naming the tool's accepted keys, and an omitted required enum/literal field now reads as missing rather than as a wrong choice ([cyanheads/mcp-ts-core#445](https://github.com/cyanheads/mcp-ts-core/issues/445), [cyanheads/mcp-ts-core#378](https://github.com/cyanheads/mcp-ts-core/issues/378)).
+- **A case-style variant of a declared argument key is rewritten and accepted** (e.g. `clock_face_id` for `clockFaceId`), and a JSON-stringified array argument is repaired and re-parsed once; an undeclared key is still rejected ([cyanheads/mcp-ts-core#452](https://github.com/cyanheads/mcp-ts-core/issues/452), [cyanheads/mcp-ts-core#453](https://github.com/cyanheads/mcp-ts-core/issues/453), [cyanheads/mcp-ts-core#234](https://github.com/cyanheads/mcp-ts-core/issues/234)).
+- **Tool error text now closes with `(reason <reason>)`**, plus ` · retryable` / ` · not retryable` when the error declares `data.retryable` ([cyanheads/mcp-ts-core#458](https://github.com/cyanheads/mcp-ts-core/issues/458)).
+- `.env.example`/README now note that `MCP_SESSION_MODE=auto` (the framework's schema default) resolves to `stateful`; the shipped value stays `stateless`. `.env.example` documents the commented `MCP_HTTP_RESUMABILITY*` options.
+- Test config hides `pixoo-toolkit`'s dangling sourcemap warnings during tests ([cyanheads/pixoo-toolkit#42](https://github.com/cyanheads/pixoo-toolkit/issues/42)).
+- Repo hygiene: CodeQL workflow added; framework skills, `lint-mcp.ts`, the changelog template, and `devcheck.config.json` synced with mcp-ts-core 0.13.6.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.2 → ^0.13.6
+- `zod` ^4.6.4 → ^4.6.5
+- `@biomejs/biome` 2.5.13 → 2.5.14
+- `@types/node` 26.5.1 → 26.6.2
+- `vitest` ^5.0.0 → ^5.0.1

package/changelog/1.1.x/1.1.4.md

@@ -0,0 +1,22 @@
+---
+summary: "Push-capable tools now declare device_http_error and carry retryable; pixoo_compose_scene's image opacity and missing local-asset errors are fixed; pixoo_control_device no longer drops failed-setter notices; pixoo_push_image's fetch cap now holds while the body streams."
+breaking: false
+security: true
+---
+
+# 1.1.4 — 2026-09-23
+
+## Changed
+
+- Entry-point session-mode test retries on a fresh port when the child exits before serving, instead of waiting out the full boot deadline.
+
+## Fixed
+
+- **`pixoo_display_text`, `pixoo_compose_scene`, and `pixoo_push_image` now declare `device_http_error` and carry `data.retryable` on push failures** — `mapFailure` threw through the raw `serviceUnavailable()` factory, bypassing the tool contract ([#11](https://github.com/cyanheads/pixoo-mcp-server/issues/11)).
+- **`pixoo_compose_scene`'s `image` elements honor `opacity`** — the blit went to the base canvas instead of the opacity-compositing scratch canvas, so opacity was silently dropped ([#4](https://github.com/cyanheads/pixoo-mcp-server/issues/4)).
+- **A missing local `image` or `sprite` path in `pixoo_compose_scene` now fails as `asset_not_found`** instead of an unclassified `InternalError` ([#12](https://github.com/cyanheads/pixoo-mcp-server/issues/12)).
+- **`pixoo_control_device` no longer drops failed-setter notices** — the tool declared no `enrichment` block, so `ctx.enrich.notice` calls were discarded; failures across multiple setters in one call now compose into a single notice ([#13](https://github.com/cyanheads/pixoo-mcp-server/issues/13)).
+
+## Security
+
+- **`pixoo_push_image`'s 10 MB fetch cap now holds while the body streams** — a URL response with no `content-length` header was fully buffered before the size check fired, allowing unbounded memory use ([#7](https://github.com/cyanheads/pixoo-mcp-server/issues/7)).

package/changelog/template.md

@@ -6,8 +6,8 @@
 
 # Required. One-line GitHub Release-style headline. 350 character cap — a
 # ceiling, not a target. Default short and scannable. Don't pad, don't stitch
-# unrelated changes with commas/semicolons into an inventory — pick the
-# headline, like a tag's theme line. Quotes required: unquoted YAML treats
+# unrelated changes with commas/semicolons into an inventory — pick the one
+# headline the release is about. Quotes required: unquoted YAML treats
 # `: ` inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
@@ -119,11 +119,11 @@ security: false
   TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
   via `gh release create --notes-from-tag`. It is a condensed digest of this
   entry, never a copy, and its format is owned by the `release-and-publish`
-  skill (step 4, "Create the annotated tag"): the entry's `summary:` as the
-  theme line without the version, flat headline bullets — no Keep-a-Changelog
-  section headers, no gates line — at most one deps line, issue backlinks,
-  and the changelog link last. In release-PR mode the `git-wrapup` skill
-  authors that digest as the PR body's `## Changes` and the tag copies it.
+  skill (step 4, "Create the annotated tag"): a short subject line without the
+  version, flat headline bullets — no Keep-a-Changelog section headers, no
+  gates line — at most one deps line, issue backlinks, and the changelog link
+  last. In release-PR mode the `git-wrapup` skill authors those bullets as the
+  PR body's `## Changes` and the tag copies them.
 -->
 
 ## Added

package/dist/index.js

@@ -53,8 +53,6 @@ await createApp({
     setup(core) {
         initPixooService(core.config, core.storage);
     },
-    instructions: 'Pixoo LED matrix display server. Use pixoo_design_brief(topic) first to orient on craft guidelines. ' +
-        'pixoo_display_text is the 80% case for styled text. pixoo_compose_scene for layered scenes, widgets, and animations. ' +
-        'All render tools return a preview image so you can inspect the result before it hits the display.',
+    instructions: 'Run pixoo_design_brief with a topic first for craft guidance and live device state, then render with pixoo_display_text for styled text or pixoo_compose_scene for layered scenes, widgets, and animations. Every render tool returns a preview image, so pass push: false to inspect a design before it reaches the Pixoo display.',
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY;AACZ,OAAO,EAAE,wBAAwB,EAAE,MAAM,mEAAmE,CAAC;AAC7G,OAAO,EAAE,yBAAyB,EAAE,MAAM,oEAAoE,CAAC;AAC/G,OAAO,EAAE,kBAAkB,EAAE,MAAM,4DAA4D,CAAC;AAChG,OAAO,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AAClG,QAAQ;AACR,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,kBAAkB,EAAE,MAAM,6DAA6D,CAAC;AACjG,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAErE,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,kBAAkB;IACxB,KAAK,EAAE,kBAAkB;IACzB,KAAK,EAAE;QACL,gBAAgB;QAChB,iBAAiB;QACjB,cAAc;QACd,gBAAgB;QAChB,kBAAkB;QAClB,oBAAoB;QACpB,gBAAgB;KACjB;IACD,SAAS,EAAE;QACT,yBAAyB;QACzB,mBAAmB;QACnB,kBAAkB;QAClB,wBAAwB;KACzB;IACD,OAAO,EAAE,EAAE;IACX,2EAA2E;IAC3E,WAAW,EAAE,WAAW;IACxB;;;;;OAKG;IACH,UAAU,EAAE;QACV,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QACxD,gBAAgB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QAC5D,0BAA0B,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;KACvE;IACD,KAAK,CAAC,IAAI;QACR,gBAAgB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IACD,YAAY,EACV,sGAAsG;QACtG,uHAAuH;QACvH,mGAAmG;CACtG,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY;AACZ,OAAO,EAAE,wBAAwB,EAAE,MAAM,mEAAmE,CAAC;AAC7G,OAAO,EAAE,yBAAyB,EAAE,MAAM,oEAAoE,CAAC;AAC/G,OAAO,EAAE,kBAAkB,EAAE,MAAM,4DAA4D,CAAC;AAChG,OAAO,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AAClG,QAAQ;AACR,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,kBAAkB,EAAE,MAAM,6DAA6D,CAAC;AACjG,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAErE,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,kBAAkB;IACxB,KAAK,EAAE,kBAAkB;IACzB,KAAK,EAAE;QACL,gBAAgB;QAChB,iBAAiB;QACjB,cAAc;QACd,gBAAgB;QAChB,kBAAkB;QAClB,oBAAoB;QACpB,gBAAgB;KACjB;IACD,SAAS,EAAE;QACT,yBAAyB;QACzB,mBAAmB;QACnB,kBAAkB;QAClB,wBAAwB;KACzB;IACD,OAAO,EAAE,EAAE;IACX,2EAA2E;IAC3E,WAAW,EAAE,WAAW;IACxB;;;;;OAKG;IACH,UAAU,EAAE;QACV,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QACxD,gBAAgB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QAC5D,0BAA0B,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;KACvE;IACD,KAAK,CAAC,IAAI;QACR,gBAAgB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IACD,YAAY,EACV,qUAAqU;CACxU,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/pixoo-compose-scene.tool.d.ts

@@ -471,26 +471,36 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
     readonly when: "Device is not reachable over the network.";
     readonly retryable: true;
     readonly recovery: "Check the device is powered on and on the same network. Retry in a few seconds.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "device_http_error";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "The device answered with a non-2xx HTTP status (retryable for 408, 429, 500, and 502–504).";
+    readonly recovery: "The device may be busy or rebooting; wait a few seconds and retry. If it persists, run pixoo_discover_devices to confirm PIXOO_IP points at the Pixoo.";
+    readonly thrownBy: "service";
 }, {
     readonly reason: "device_rejected";
     readonly code: JsonRpcErrorCode.ServiceUnavailable;
     readonly when: "Device firmware returned a non-zero error code.";
     readonly recovery: "Note the device error code and check the Pixoo documentation.";
+    readonly thrownBy: "service";
 }, {
     readonly reason: "no_device_configured";
     readonly code: JsonRpcErrorCode.InvalidParams;
     readonly when: "PIXOO_IP is not set and push was requested.";
     readonly recovery: "Run pixoo_discover_devices to find the device IP, then set PIXOO_IP.";
+    readonly thrownBy: "service";
 }, {
     readonly reason: "asset_not_found";
     readonly code: JsonRpcErrorCode.NotFound;
     readonly when: "An image or sprite path could not be read.";
     readonly recovery: "Verify the file path exists and is readable, or check the URL is reachable.";
+    readonly thrownBy: "service";
 }, {
     readonly reason: "invalid_color";
     readonly code: JsonRpcErrorCode.InvalidParams;
     readonly when: "A color value could not be resolved.";
-    readonly recovery: "Use #RRGGBB hex or a named color. See pixoo://reference/themes for palettes.";
+    readonly recovery: "Use a hex color (#RRGGBB or #RGB, with or without the #) or a case-insensitive named color such as white, orange, or claude. See pixoo://reference/themes for palette colors.";
 }, {
     readonly reason: "unknown_icon";
     readonly code: JsonRpcErrorCode.InvalidParams;

package/dist/mcp-server/tools/definitions/pixoo-compose-scene.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pixoo-compose-scene.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/pixoo-compose-scene.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAmT3E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiT5B,CAAC"}
+{"version":3,"file":"pixoo-compose-scene.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/pixoo-compose-scene.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAmT3E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgU5B,CAAC"}

package/dist/mcp-server/tools/definitions/pixoo-compose-scene.tool.js

@@ -323,8 +323,7 @@ export const pixooComposeScene = tool('pixoo_compose_scene', {
         output: z
             .string()
             .optional()
-            .describe('Absolute, already-normalized path to save the first frame to, in addition to the ' +
-            'PIXOO_OUTPUT_DIR auto-save when that is configured. Both paths are reported in outputFiles.'),
+            .describe('Absolute, already-normalized path to save the first frame to, in addition to the PIXOO_OUTPUT_DIR auto-save when that is configured. Both paths are reported in outputFiles.'),
     }),
     output: z.object({
         pushed: z
@@ -371,30 +370,41 @@ export const pixooComposeScene = tool('pixoo_compose_scene', {
             when: 'Device is not reachable over the network.',
             retryable: true,
             recovery: 'Check the device is powered on and on the same network. Retry in a few seconds.',
+            thrownBy: 'service',
+        },
+        {
+            reason: 'device_http_error',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'The device answered with a non-2xx HTTP status (retryable for 408, 429, 500, and 502–504).',
+            recovery: 'The device may be busy or rebooting; wait a few seconds and retry. If it persists, run pixoo_discover_devices to confirm PIXOO_IP points at the Pixoo.',
+            thrownBy: 'service',
         },
         {
             reason: 'device_rejected',
             code: JsonRpcErrorCode.ServiceUnavailable,
             when: 'Device firmware returned a non-zero error code.',
             recovery: 'Note the device error code and check the Pixoo documentation.',
+            thrownBy: 'service',
         },
         {
             reason: 'no_device_configured',
             code: JsonRpcErrorCode.InvalidParams,
             when: 'PIXOO_IP is not set and push was requested.',
             recovery: 'Run pixoo_discover_devices to find the device IP, then set PIXOO_IP.',
+            thrownBy: 'service',
         },
         {
             reason: 'asset_not_found',
             code: JsonRpcErrorCode.NotFound,
             when: 'An image or sprite path could not be read.',
             recovery: 'Verify the file path exists and is readable, or check the URL is reachable.',
+            thrownBy: 'service',
         },
         {
             reason: 'invalid_color',
             code: JsonRpcErrorCode.InvalidParams,
             when: 'A color value could not be resolved.',
-            recovery: 'Use #RRGGBB hex or a named color. See pixoo://reference/themes for palettes.',
+            recovery: 'Use a hex color (#RRGGBB or #RGB, with or without the #) or a case-insensitive named color such as white, orange, or claude. See pixoo://reference/themes for palette colors.',
         },
         {
             reason: 'unknown_icon',
@@ -430,7 +440,7 @@ export const pixooComposeScene = tool('pixoo_compose_scene', {
         // collapse traversal segments, passing everything.
         if (input.output &&
             (!path.isAbsolute(input.output) || path.normalize(input.output) !== input.output)) {
-            throw ctx.fail('invalid_output_path', `Invalid output path: "${input.output}". Must be an absolute path with no traversal segments.`);
+            throw ctx.fail('invalid_output_path', `Invalid output path: "${input.output}". Must be an absolute path with no traversal segments.`, ctx.recoveryFor('invalid_output_path'));
         }
         ctx.log.info('Rendering scene', {
             elements: input.elements.length,
@@ -449,10 +459,10 @@ export const pixooComposeScene = tool('pixoo_compose_scene', {
         }
         catch (err) {
             if (err instanceof Error && err.message.includes('Unknown color')) {
-                throw ctx.fail('invalid_color', `${err.message}. Valid named colors: ${validColorNames}. See pixoo://reference/themes for palette colors.`);
+                throw ctx.fail('invalid_color', `${err.message}. Valid named colors: ${validColorNames}.`, ctx.recoveryFor('invalid_color'));
             }
             if (err instanceof McpError && err.data?.['reason'] === 'unknown_icon') {
-                throw ctx.fail('unknown_icon', `${err.message} Valid icons: ${validIconNames}. See pixoo://reference/icons.`);
+                throw ctx.fail('unknown_icon', `${err.message} Valid icons: ${validIconNames}.`, ctx.recoveryFor('unknown_icon'));
             }
             throw err;
         }