Release v0.4.1

.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "temporal",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Comprehensive skill for the entire Temporal lifecycle — developing applications, using the Temporal CLI, running and managing Temporal Server, and working with Temporal Cloud.",
   "author": {
     "name": "Temporal",
@@ -22,4 +22,4 @@
   ],
   "logo": "assets/temporal-logo.svg",
   "skills": "./skills/"
-}
+}

skills/temporal-cloud-setup/SKILL.md

@@ -1,7 +1,13 @@
 ---
 name: temporal-cloud-setup
-description: Set up Temporal Cloud and run a sample Workflow on it for the user, doing the work end to end. Use when the user wants to set up Temporal Cloud, get started on Temporal Cloud, install the unified Temporal CLI (prerelease cloud-cli), create a Cloud namespace or API key, clone a money-transfer sample app, write the client config TOML, or connect a local Worker to Temporal Cloud and run a sample Workflow. This is the Cloud setup path, not the local learning path (see temporal-getting-started). Covers Python, TypeScript, Go, Java, .NET, and Ruby SDKs.
-version: 0.8.1
+description: Set up Temporal Cloud and run a sample Workflow on it for the user, doing
+  the work end to end. Use when the user wants to set up Temporal Cloud, get started
+  on Temporal Cloud, install the unified Temporal CLI (prerelease cloud-cli), create
+  a Cloud namespace or API key, clone a money-transfer sample app, write the client
+  config TOML, or connect a local Worker to Temporal Cloud and run a sample Workflow.
+  This is the Cloud setup path, not the local learning path (see temporal-getting-started).
+  Covers Python, TypeScript, Go, Java, .NET, and Ruby SDKs.
+version: 0.8.2
 disable-model-invocation: true
 ---
 
@@ -796,4 +802,4 @@ On `status=error`, map the `error_code` via **`references/failure-handling.md`**
 - `scripts/provision.sh` — **the deterministic executor.** Owns preflight / **detect-tools** / **preview** / install / login / regions / namespace-create / **install-deps (manager-parameterized)** / key-mint+config-write / verify / await-auth / **run-workflow (Worker + starter)** / clone / repair-config / cleanup-info. Invoke it and parse its `=== RESULT ===` block (see "Execution model" above); it is the single source of truth for the pinned CLI flags, the per-SDK run commands, **and the per-(SDK,manager) install matrix + minimum-version table**. Pure bash, portable across Claude Code, Codex, and Cursor. **Read-only during a run — invoke it, never edit it (read-only script).**
 - `references/unified-cli.md` — background on the prerelease CLI and the client-config TOML: `login`/`whoami`, `region list`, `namespace create`, `apikey create-for-me`, file locations, and the auth-override gotcha. The script encodes these; read the reference when a flag drifts and you need to update the script.
 - `references/sdk-cloud.md` — per-SDK table: repo + cloud branch, task-queue name, how each connects (`cloud-setup` profile), and worker/starter run commands. No connection edits — the branch is pre-wired.
-- `references/failure-handling.md` — the `error_code` → remediation map. Read it **only when a subcommand returns `status=error`** (progressive disclosure — the happy path never opens it); the Failure Handling section above is a one-line pointer to it, and the Steps spine's On-error column is the index.
+- `references/failure-handling.md` — the `error_code` → remediation map. Read it **only when a subcommand returns `status=error`** (progressive disclosure — the happy path never opens it); the Failure Handling section above is a one-line pointer to it, and the Steps spine's On-error column is the index.

skills/temporal-developer/SKILL.md

@@ -1,7 +1,15 @@
 ---
 name: temporal-developer
-description: Develop, debug, and manage Temporal applications across Python, TypeScript, Go, Java, .NET, Ruby, and Rust. Use when the user is building workflows, activities, or workers with a Temporal SDK, debugging issues like non-determinism errors, stuck workflows, or activity retries, using Temporal CLI, Temporal Server, or Temporal Cloud, or working with durable execution concepts like signals, queries, heartbeats, versioning, continue-as-new, child workflows, or saga patterns. Also use when the user mentions "run a Temporal workflow from the CLI", "start a dev server", "run temporal server start-dev", "temporal workflow start", "temporal workflow execute", "temporal workflow signal", "temporal workflow query", "temporal workflow update".
-version: 0.6.0
+description: Develop, debug, and manage Temporal applications across Python, TypeScript,
+  Go, Java, .NET, Ruby, and Rust. Use when the user is building workflows, activities,
+  or workers with a Temporal SDK, debugging issues like non-determinism errors, stuck
+  workflows, or activity retries, using Temporal CLI, Temporal Server, or Temporal
+  Cloud, or working with durable execution concepts like signals, queries, heartbeats,
+  versioning, continue-as-new, child workflows, or saga patterns. Also use when the
+  user mentions "run a Temporal workflow from the CLI", "start a dev server", "run
+  temporal server start-dev", "temporal workflow start", "temporal workflow execute",
+  "temporal workflow signal", "temporal workflow query", "temporal workflow update".
+version: 0.6.1
 ---
 
 # Skill: temporal-developer
@@ -103,4 +111,4 @@ For Temporal plugins and integrations with third-party frameworks and SDKs (Spri
 
 ### Reporting Issues in This Skill
 
-If you (the AI) find this skill's explanations are unclear, misleading, or missing important information—or if Temporal concepts are proving unexpectedly difficult to work with—draft a GitHub issue body describing the problem encountered and what would have helped, then ask the user to file it at https://github.com/temporalio/skill-temporal-developer/issues/new. Do not file the issue autonomously.
+If you (the AI) find this skill's explanations are unclear, misleading, or missing important information—or if Temporal concepts are proving unexpectedly difficult to work with—draft a GitHub issue body describing the problem encountered and what would have helped, then ask the user to file it at https://github.com/temporalio/skill-temporal-developer/issues/new. Do not file the issue autonomously.

skills/temporal-developer/references/core/error-reference.md

@@ -5,7 +5,7 @@
 | **Non-determinism** | TMPRL1100 | `WorkflowTaskFailed` in history | Replay doesn't match history | Analyze error first. **If accidental**: fix code to match history → restart worker. **If intentional v2 change**: terminate → start fresh workflow. | https://github.com/temporalio/rules/blob/main/rules/TMPRL1100.md |
 | **Deadlock** | TMPRL1101 | `WorkflowTaskFailed` in history, worker logs | Workflow blocked too long (deadlock detected) | Remove blocking operations from workflow code (no I/O, no sleep, no threading locks). Use Temporal primitives instead. | https://github.com/temporalio/rules/blob/main/rules/TMPRL1101.md |
 | **Unfinished handlers** | TMPRL1102 | `WorkflowTaskFailed` in history | Workflow completed while update/signal handlers still running | Ensure all handlers complete before workflow finishes. Use `workflow.wait_condition()` to wait for handler completion. | https://github.com/temporalio/rules/blob/main/rules/TMPRL1102.md |
-| **Payload overflow** | TMPRL1103 | `WorkflowTaskFailed` or `ActivityTaskFailed` in history | Payload size limit exceeded (default 2MB) | Reduce payload size. Use external storage (S3, database) for large data and pass references instead. | https://github.com/temporalio/rules/blob/main/rules/TMPRL1103.md |
+| **Payload overflow** | TMPRL1103 | `WorkflowTaskFailed` or `ActivityTaskFailed` in history | Payload size limit exceeded (default 2MB) | Reduce payload size. Use the SDK's built-in External Storage where available (see `references/{your_language}/external-storage.md`; Go, Python, and TypeScript), or pass references to external storage yourself (see the Large Data Handling pattern in `references/core/patterns.md`). | https://github.com/temporalio/rules/blob/main/rules/TMPRL1103.md |
 | **Workflow code bug** | | `WorkflowTaskFailed` in history | Bug in workflow logic | Fix code → Restart worker → Workflow auto-resumes | |
 | **Missing workflow** | | Worker logs | Workflow not registered | Add to worker.py → Restart worker | |
 | **Missing activity** | | Worker logs | Activity not registered | Add to worker.py → Restart worker | |

skills/temporal-developer/references/core/gotchas.md

@@ -235,3 +235,5 @@ When resetting a workflow with `temporal workflow reset`, `--reapply-type` contr
 - Workflow history growing unboundedly
 
 **The Fix**: Store large data externally (S3/GCS) and pass references, use compression codecs, or chunk data across multiple activities. See the Large Data Handling pattern in `references/core/patterns.md`.
+
+Before hand-rolling reference passing, check whether the SDK does it for you: the Go, Python, and TypeScript SDKs have built-in External Storage that applies the claim-check pattern automatically. See `references/{your_language}/external-storage.md`, if available.

skills/temporal-developer/references/core/patterns.md

@@ -368,6 +368,8 @@ This ensures that on replay, already-completed steps are skipped.
 - Max 4MB per gRPC message
 - Max 50MB for workflow history (aim for < 10MB)
 
+**Check for SDK support first**: the Go, Python, and TypeScript SDKs have built-in External Storage that applies the claim-check pattern for you — Payloads over a size threshold are offloaded to S3 or GCS and replaced in Event History with a small reference, with no changes to Workflow or Activity code. Prefer it where it exists; see `references/{your_language}/external-storage.md`, if available. The rest of this section applies when you need explicit control over which data is offloaded, or when your SDK has no built-in support.
+
 **Key Principle**: Large data should never flow through workflow history. Activities read and write large data directly, passing only small references through the workflow.
 
 **Wrong Approach**: