Update to Render

SKILL.md text changes

− removed · + added

--- before
+++ after
@@ -1,145 +1,262 @@
 ---
 name: render-workflows
-description: Sets up, develops, tests, and deploys Render Workflows. Covers first-time scaffolding (via CLI or manual), SDK installation (Python or TypeScript), task patterns (retries, subtasks, fan-out), local development, Dashboard deployment, and troubleshooting. Use when a user wants to set up Render Workflows for the first time, scaffold a workflow service, add or modify workflow tasks, test workflows locally, or deploy workflows to Render.
+description: >-
+  Build, validate locally, deploy, and troubleshoot Render Workflows with the
+  current Python or TypeScript SDK. Use for defining or chaining tasks,
+  integrating the SDK into an existing project, running tasks with the local
+  development server, optionally scaffolding a starter, authoring
+  "type: workflow" in render.yaml, triggering runs from application code, and
+  releasing workflows.
 license: MIT
-compatibility: Requires Render CLI 2.11.0+ for scaffolding and local development. Render Dashboard required for deployment (Blueprints not yet supported for Workflows).
+compatibility: >-
+  Requires Render SDK 1.x. Local validation requires Render CLI 2.12.0+;
+  optional scaffolding and CLI deployment require Render CLI 2.16.0+.
+  Blueprints support "type: workflow" (no service-level plan).
 metadata:
   author: Render
-  version: "1.0.0"
+  version: "1.2.0"
   category: workflows
 ---
 
 # Render Workflows
 
-Render Workflows rapidly distribute computational work across multiple independent instances.
-Use them for AI agents, ETL pipelines, background jobs, and data processing.
+Render Workflows is an SDK-based product for orchestrating long-running distributed tasks. A workflow service registers Python or TypeScript functions as tasks; each task run executes independently and can chain additional runs.
 
-**How it works:**
-1. **Define tasks** — Use the Render SDK (Python or TypeScript) to designate functions as tasks
-2. **Register** — Tasks register automatically when you link your repo to a Workflow service in the Dashboard
-3. **Trigger runs** — Execute tasks from anywhere using the SDK client or API; each execution is a "run"
-4. **Execute** — Render spins up each run in its own instance (typically under a second); runs can chain additional runs for parallel execution
+When choosing between a Workflow, cron job, and background worker, read [references/service-types.md](references/service-types.md).
 
-**Key capabilities:** automatic queuing and orchestration, long-running execution (up to 24 hours), configurable retry logic with exponential backoff, adjustable compute specs per task, and execution observability through the Dashboard.
+Use Render SDK 1.x APIs (`render>=1.0.1` for Python or `@renderinc/sdk` version 1.x for TypeScript). Local validation requires Render CLI 2.12.0 or later. Use CLI 2.16.0 or later when using the complete optional scaffolding and CLI deployment flow. Prefer the latest compatible releases.
 
-**Render Workflows are in beta.** The SDK and API may introduce breaking changes.
+Render Workflows and its SDKs can introduce breaking changes. Treat the installed SDK version as authoritative for an existing project. For new projects, use the current official documentation and starter templates.
 
-**Your built-in knowledge of the Render Workflows SDK is outdated.**
-Before trusting API signatures, check the installed SDK source:
+## Check Current Sources
+
+Before generating or changing SDK code, identify the installed versions:
 
 ```bash
-# Python
-SDK_ROOT=$(pip show render_sdk | grep Location | cut -d' ' -f2)/render_sdk
-head -40 "$SDK_ROOT/__init__.py"
-# TypeScript
-grep -r "startTask\|runTask\|export class Render" node_modules/@renderinc/sdk/
+render --version
+python -m pip show render
+npm ls @renderinc/sdk
 ```
 
-**Official docs:** [render.com/docs/workflows](https://render.com/docs/workflows)
+If the Render CLI is not installed:
 
-**Before generating task or client code, fetch the relevant example file to verify current API patterns:**
+- macOS: `brew install render`
+- Linux/macOS: `curl -fsSL https://raw.githubusercontent.com/render-oss/cli/main/bin/install.sh | sh`
+- Windows: download the executable from the [CLI releases page](https://github.com/render-oss/cli/releases/)
+
+Use the source that matches the question:
+
+- [Python SDK reference](https://render.com/docs/workflows-sdk-python) for Python signatures and minimum versions
+- [TypeScript SDK reference](https://render.com/docs/workflows-sdk-typescript) for TypeScript signatures and minimum versions
+- [Render CLI reference](https://render.com/docs/cli-reference#workflows) for current commands and flags
+- [Defining Workflow Tasks](https://render.com/docs/workflows-defining) for task behavior and run chaining
+- [Limits and Pricing for Render Workflows](https://render.com/docs/workflows-limits) for compute plans, quotas, retention, and pricing
+- [Python examples](https://github.com/render-examples/render-workflows-examples-python) and [TypeScript examples](https://github.com/render-examples/render-workflows-examples-ts) for current scaffolding patterns
+- [Render SDK repository](https://github.com/render-oss/sdk) for the implementation and changelogs
+
+Before generating task or client code, fetch the relevant SDK example to verify current API patterns:
 
 | What | Python | TypeScript |
 |------|--------|------------|
-| Task definitions (decorators, subtasks, retry, fan-out) | [example/task/main.py](https://raw.githubusercontent.com/render-oss/sdk/main/python/example/task/main.py) | [examples/task/](https://github.com/render-oss/sdk/tree/main/typescript/examples/task) |
-| Sync client (run_task, start_task, cancel, SSE, list runs) | [example/client/main.py](https://raw.githubusercontent.com/render-oss/sdk/main/python/example/client/main.py) | [examples/client/](https://github.com/render-oss/sdk/tree/main/typescript/examples/client) |
+| Task definitions (subtasks, retry, fan-out) | [example/task/main.py](https://raw.githubusercontent.com/render-oss/sdk/main/python/example/task/main.py) | [examples/task/](https://github.com/render-oss/sdk/tree/main/typescript/examples/task) |
+| Client (run, start, cancel, stream, list runs) | [example/client/main.py](https://raw.githubusercontent.com/render-oss/sdk/main/python/example/client/main.py) | [examples/client/](https://github.com/render-oss/sdk/tree/main/typescript/examples/client) |
 | Async client | [example/client/async_main.py](https://raw.githubusercontent.com/render-oss/sdk/main/python/example/client/async_main.py) | — |
 
-This skill carries a [quick-reference cheat sheet](references/quick-reference.md) for the API surface. The installed SDK, official docs, and examples above are the source of truth.
+Do not silently upgrade an existing project's SDK major version. If an upgrade is part of the request, read the relevant SDK changelog and migrate all task definitions and callers together.
 
----
+## SDK 1.x Invariants
 
-## Getting Started
+Preserve these rules in generated code:
 
-Supported languages: **Python** and **TypeScript**.
+- Python installs and imports the `render` package, not `render_sdk`.
+- Every task function accepts a `TaskContext` as its first positional parameter. Render supplies it; callers do not include it in task input.
+- Chain a task run with `await ctx.run(task_definition, ...args)`. A task definition is not directly callable.
+- All tasks in a `ctx.run` chain belong to the same workflow service. Trigger another workflow through the SDK client or Render API.
+- Python calls `app.start()` from its workflow entrypoint. TypeScript task registration auto-starts in the workflow environment.
+- Task arguments and return values must be JSON-serializable.
 
-### Prerequisites
+Read [references/quick-reference.md](references/quick-reference.md) when writing SDK code. Read [references/task-patterns.md](references/task-patterns.md) for chaining, fan-out, retries, scheduled triggers, or cross-workflow calls.
 
-**Render CLI (required)**
+## Choose a Starting Point
+
+Do not require `render workflows init`. In an existing codebase, add the SDK and task definitions directly, preserve the project's dependency and build conventions, and validate them with the local development server. For a minimal project or direct integration guidance, read [references/manual-scaffolding.md](references/manual-scaffolding.md).
+
+### Optional starter scaffolding
+
+Use the CLI scaffolder when the user wants a quick example project or a new standalone workflow service:
 
 ```bash
-render --version
+render workflows init
 ```
 
-Requires version 2.11.0+. If not installed:
-- macOS: `brew install render`
-- Linux/macOS: `curl -fsSL https://raw.githubusercontent.com/render-oss/cli/main/bin/install.sh | sh`
-- Windows: download the executable from the [CLI releases page](https://github.com/render-oss/cli/releases/)
+For non-interactive setup, pass the language and destination explicitly:
 
-### Scaffold a new workflow service
+```bash
+render workflows init --confirm --language python --dir workflows --git=false
+render workflows init --confirm --language node --dir workflows --git=false
+```
+
+Use `--git=false` when scaffolding inside an existing Git repository to avoid creating a nested repository. Other useful options include `--template`, `--install-deps`, and `--install-agent-skill`; verify current behavior in the CLI reference.
+
+## Try It Locally with the SDK
 
-**Always prefer `render workflows init` as the primary setup path.** Only fall back to manual scaffolding if the CLI command is unavailable.
+For a first integration, follow the runnable Python or TypeScript [local SDK walkthrough](references/manual-scaffolding.md#try-it-locally-with-the-sdk): define `ping`, start the local task server, invoke it from a separate client script, and verify the returned `"pong"`. No `init`, deployment, or Render API key is needed for this local example. Set local mode in the calling application process, not only in the task server's environment.
+
+After adding or changing SDK task definitions, use the local development server as the primary validation loop. Start it with the workflow's actual start command:
 
 ```bash
-render workflows init
+render workflows dev -- <workflow-start-command>
 ```
 
-**Interactive mode** (default): walks the user through scaffolding an example project, testing it locally, and deploying it to Render.
+In another terminal, list and run tasks against the local server:
 
-**Non-interactive mode**: sets up an example project without prompting.
+```bash
+render workflows tasks list --local
+render workflows start <task-name> --local --input='[]' -o json
+render workflows tasks runs show <task-run-id> --local -o json
+```
 
-If `render workflows init` fails or is not available:
-- **Command not found:** CLI version may be too old. Run `render --version` and upgrade to 2.11.0+.
-- **Command not supported:** fall back to [references/manual-scaffolding.md](references/manual-scaffolding.md) for step-by-step manual setup.
+If a task doesn't appear in the local task list, see [Troubleshooting > Local task list is empty or missing tasks](references/troubleshooting.md#local-task-list-is-empty-or-missing-tasks).
 
----
+Use a JSON array for positional input. Python tasks can also receive a JSON object for named input. Read [references/local-development.md](references/local-development.md) for environment files, custom ports, run inspection, cancellation, and application-client configuration.
 
-## Define Tasks
+In non-interactive mode, `workflows start` returns the new task run ID before the run necessarily finishes. Use that ID with `tasks runs show`, polling for a bounded period until the run completes, fails, or is canceled. Verify the result or error, not only that the run was created.
 
-Guide the user through defining their actual tasks. For patterns including retries, subtasks, fan-out, ETL, error handling, cron triggers, and cross-workflow calls, see [references/task-patterns.md](references/task-patterns.md).
+When safe and practical, run this verification yourself and stop the dev server afterward. Do not claim a task registers successfully based only on source inspection.
+
+## Deploy After Local Validation
+
+Creating or releasing a workflow changes the user's Render account. Only do it when deployment is part of the request and the tasks have been validated locally when local execution is supported.
+
+Before deploying or interpreting deploy status, read [references/deployments.md](references/deployments.md), including its Workflow-specific task-registration behavior.
+
+Before deploying, authenticate and confirm the target workspace:
 
-**After adding a task**, verify it registers by starting the local dev server and listing tasks:
 ```bash
-render workflows dev -- <start-command>
-# In another terminal:
-render workflows tasks list --local
+render whoami
+render workspace current
+```
+
+If authentication is missing, use `render login` for an interactive local session or provide `RENDER_API_KEY` through the environment for automation. Never print the key.
+
+Confirm the intended branch and region, and ensure the exact code to deploy is committed and pushed to GitHub, GitLab, or Bitbucket. Neither path deploys uncommitted local changes.
+
+Two creation paths. MCP supports neither.
+
+| Path | Use when | Runtimes |
+|------|----------|----------|
+| Blueprint (`render.yaml`) | The repo uses IaC, or the workflow ships beside other Render services | `python`, `node` |
+| `render workflows create` or Dashboard | Standalone workflow with no Blueprint | `python`, `node`, `go`, `ruby`, `elixir`, plus Docker in the Dashboard only |
+
+### Deploy with a Blueprint (preferred)
+
+Do **not** set `plan` on a workflow service. Task compute is configured in code (`plan` on the task), not on the service.
+
+```yaml
+services:
+  - type: workflow
+    name: my-workflow
+    runtime: python
+    region: oregon
+    repo: https://github.com/render-examples/render-workflows-examples-python
+    branch: main
+    rootDir: hello-world
+    buildCommand: pip install -r requirements.txt
+    startCommand: python main.py
+    envVars:
+      - key: RENDER_API_KEY
+        sync: false
+```
+
+TypeScript variant: `runtime: node`, `buildCommand: npm install`, and a `startCommand` that runs the project's workflow entrypoint. The TypeScript starter uses `npm start` (`tsx src/main.ts`); the manual setup in [references/manual-scaffolding.md](references/manual-scaffolding.md) uses `npm run workflows:start`. Match both commands to the scripts in `package.json`. Use `npm run build` and `node dist/main.js` only if the project defines a `build` script that emits `dist/main.js`.
+
+Required: `type`, `name`, `runtime`, `region`, `startCommand`, plus `buildCommand` and `repo`. Optional: `branch`, `rootDir`, `buildFilter`, `autoDeployTrigger`, `envVars` (applied to every task run).
+
+The schema's `required` array lists only the first five. Do not treat it as the complete set: the validator also rejects a workflow missing `buildCommand` or `repo`.
+
+- `buildCommand is required for non-docker workflows`. Only Docker-based workflows omit a build command, and those cannot appear in a Blueprint, so a Blueprint workflow always needs one.
+- `repo is required for git-based services`. This fires even when validating from inside that repository with an `origin` remote, which is not how `web` and other Git-based types behave.
+
+Caveats:
+
+- Preview environments skip workflow services. Other Blueprint resources still replicate.
+- Render rejects a Blueprint that would create a workflow with the same name as an existing Blueprint-managed workflow in the workspace.
+- The [Workflows intro FAQ](https://render.com/docs/workflows) may still say Blueprints cannot manage workflows. That is stale. Follow the [changelog](https://render.com/changelog/added-blueprint-support-for-render-workflows) and `https://render.com/schema/render.yaml.json`.
+
+Validate before applying:
+
+```bash
+render blueprints validate
 ```
 
-If the task doesn't appear, see [Troubleshooting > Task Registration Issues](references/troubleshooting.md#task-registration-issues).
+A passing validate is not proof a runtime is supported. `render blueprints validate` currently accepts `runtime: docker` on a workflow even though the schema rejects it.
 
-## Local Development
+Pair with **render-blueprints** for wiring and **render-deploy** for the apply/deeplink flow.
 
-See [references/local-development.md](references/local-development.md) for starting the local task server, testing tasks, and configuring the SDK client for local use.
+### Create with the CLI or Dashboard
 
-## Deploy to Render
+Use this for a standalone workflow with no Blueprint. Interactive mode prompts for configuration:
 
-Workflows are deployed as a **Workflow** service type in the Render Dashboard. **Blueprints (render.yaml) are not yet compatible with Workflows.**
+```bash
+render workflows create
+```
 
-**Deploy checklist:**
+Non-interactive, using the build and run commands from the starter template or the project's existing configuration:
 
-- [ ] Code pushed to GitHub, GitLab, or Bitbucket
-- [ ] In the [Render Dashboard](https://dashboard.render.com), click **New > Workflow**
-- [ ] Link your repository
-- [ ] Set **Root Directory** to `workflows/`
-- [ ] Configure build and start commands (see table below)
-- [ ] Add environment variables (e.g., `RENDER_API_KEY` for tasks that call other workflows)
-- [ ] Click **Deploy Workflow**
-- [ ] Verify deployment: check the Dashboard for a successful deploy event
+```bash
+render workflows create \
+  --name my-workflow \
+  --repo . \
+  --branch <branch> \
+  --region <region> \
+  --runtime python \
+  --build-command "pip install -r requirements.txt" \
+  --run-command "python main.py"
+```
 
-| Field | Python | TypeScript |
-|-------|--------|------------|
-| **Language** | Python 3 | Node |
-| **Build Command** | `pip install -r requirements.txt` | `npm install && npm run build` |
-| **Start Command** | `python main.py` | `node dist/main.js` |
+`--repo .` resolves the repository's remote. For a workflow in a subdirectory, add `--root-directory`. Environment variables can be supplied with repeatable `--env-file` and `--env-var` flags. Never expose secrets in commands or output.
 
-If the deploy fails, check the service logs in the Dashboard. For common deployment errors, see [Troubleshooting](references/troubleshooting.md). For general deploy debugging, use the **render-debug** skill.
+A workflow can build from a Dockerfile, but only through the Dashboard (**New > Workflow**): [the CLI and API cannot create one](https://render.com/docs/workflows-tutorial#docker-specific-limitations), and neither can a Blueprint. Docker-based workflows take no build command and cannot run against the local task server. No creation path can pull a prebuilt registry image.
 
-**Running tasks from other services:**
+For later explicit releases, use:
 
-After deployment, trigger tasks from your other Render services using the SDK client.
+```bash
+render workflows versions release <workflow-id> \
+  --commit <pushed-commit-sha> \
+  --wait
+```
+
+Do not report deployment success from command acceptance alone. Wait for the release, then verify that the expected tasks registered and that one safe task reaches a terminal state with the expected result:
+
+```bash
+render workflows versions list <workflow-id> -o text
+render workflows tasks list <ready-workflow-version-id> -o text
+render workflows start <workflow-slug>/<task-name> --input='[]' -o json
+render workflows tasks runs show <task-run-id> -o json
+```
+
+Poll `tasks runs show` for a bounded period if the run is still queued or running. Stop and report the release or task error instead of retrying an external mutation indefinitely.
+
+If deployment fails, read [references/troubleshooting.md](references/troubleshooting.md). Use the `render-debug` skill for broader Render deployment diagnosis when it is available.
+
+## Trigger Deployed Tasks
+
+Task slugs use `{workflow-slug}/{task-name}`.
+
+Python, synchronous:
 
-Python (synchronous):
 ```python
-from render_sdk import Render
+from render import Render
 
 render = Render()
 result = render.workflows.run_task("my-workflow/hello", ["world"])
 print(result.results)
 ```
 
-Python (asynchronous):
+Python, asynchronous:
+
 ```python
-from render_sdk import RenderAsync
+from render import RenderAsync
 
 render = RenderAsync()
 started = await render.workflows.start_task("my-workflow/hello", ["world"])
@@ -148,6 +265,7 @@
 ```
 
 TypeScript:
+
 ```typescript
 import { Render } from "@renderinc/sdk";
 
@@ -157,54 +275,43 @@
 console.log(finished.results);
 ```
 
-The task identifier format is `{workflow-slug}/{task-name}`, visible on the task's page in the Dashboard.
-
-Workflows do not have built-in scheduling. To trigger tasks on a schedule, use a Render cron job with the SDK client. For cron and cross-workflow examples, see [references/task-patterns.md](references/task-patterns.md).
-
----
-
-## Constraints and Limits
+These clients use `RENDER_API_KEY` unless a token is passed explicitly. Prefer environment variables or a secret manager over hard-coded credentials.
 
-| Constraint | Limit | Notes |
-|------------|-------|-------|
-| Arguments and return values | Must be JSON-serializable | No class instances, functions, etc. |
-| Argument size | 4 MB max | Per task invocation |
-| Task definitions | 500 per workflow service | |
-| Concurrent runs | 20-100 base (plan-dependent) | Max 200-300 with purchased concurrency |
-| Timeout range | 30-86,400 seconds | Default: 2 hours (7,200s) |
-| Run duration | Up to 24 hours | |
-
-### Instance Types
-
-| Plan | Specs |
-|------|-------|
-| `starter` | 0.5 CPU / 512 MB |
-| `standard` (default) | 1 CPU / 2 GB |
-| `pro` | 2 CPU / 4 GB |
-| `pro_plus` | 4 CPU / 8 GB |
-| `pro_max` | 8 CPU / 16 GB |
-| `pro_ultra` | 16 CPU / 32 GB |
+Workflows do not currently provide native scheduled triggers. Use a Render cron job that invokes the SDK client or API when scheduling is required.
 
-`pro_plus`, `pro_max`, and `pro_ultra` require requesting access. Set via the `plan` task option.
+## Limits, Compute Plans, and Pricing
 
-For current pricing, see [Limits and Pricing for Render Workflows](https://render.com/docs/workflows-limits).
+Do not hard-code compute-plan IDs, resource specifications, quotas, retention periods, or prices in this skill or its references.
 
----
+Before setting a task's `plan`, estimating cost, or advising on capacity, consult [references/compute-plans.md](references/compute-plans.md) and [Limits and Pricing for Render Workflows](https://render.com/docs/workflows-limits). Keep only API-shape constraints needed to write correct code in the skill.
 
 ## References
 
-- **Quick-reference cheat sheet:** [references/quick-reference.md](references/quick-reference.md) (API surface, env vars, error types)
-- **Task patterns:** [references/task-patterns.md](references/task-patterns.md)
-- **Local development:** [references/local-development.md](references/local-development.md)
-- **Troubleshooting:** [references/troubleshooting.md](references/troubleshooting.md)
-- **Manual scaffolding (fallback):** [references/manual-scaffolding.md](references/manual-scaffolding.md)
-- **Official docs:** [render.com/docs/workflows](https://render.com/docs/workflows)
-- **Starter template (Python):** [render-examples/workflows-template-python](https://github.com/render-examples/workflows-template-python)
-- **Starter template (TypeScript):** [render-examples/workflows-template-ts](https://github.com/render-examples/workflows-template-ts)
-- **SDK repo:** [github.com/render-oss/sdk](https://github.com/render-oss/sdk)
+- [references/quick-reference.md](references/quick-reference.md): SDK 1.x task and client surface
+- [references/compute-plans.md](references/compute-plans.md): current compute-plan guidance for task `plan` values
+- [references/deployments.md](references/deployments.md): deploy lifecycle and Workflow task registration
+- [references/service-types.md](references/service-types.md): choosing between Workflows and other service types
+- [references/task-patterns.md](references/task-patterns.md): chaining, fan-out, retries, cron triggers, and cross-workflow calls
+- [references/local-development.md](references/local-development.md): local server, CLI runs, environment configuration, and limitations
+- [references/troubleshooting.md](references/troubleshooting.md): common setup, registration, execution, and client failures
+- [references/manual-scaffolding.md](references/manual-scaffolding.md): direct SDK project setup without `workflows init`
 
 ## Related Skills
 
-- **render-deploy:** Deploy web services, static sites, and databases
-- **render-debug:** Debug failed deployments and runtime errors
-- **render-monitor:** Monitor service health and performance
+- `render-blueprints`: `type: workflow` in `render.yaml`, previews, wiring
+- `render-deploy`: Blueprint apply flow for multi-service apps that include a workflow
+- `render-debug`: diagnose deployment and runtime failures
+- `render-monitor`: inspect service health and performance
+
+<!-- shared:documentation-retrieval -->
+## Current documentation retrieval
+
+Whenever this skill directs you to consult current Render documentation:
+
+1. Retrieve the linked Markdown document directly with an available URL-fetching tool or HTTP client, such as `curl`. Do not substitute web-search summaries for the document.
+2. Confirm that retrieval succeeded and returned the expected document, then read its contents. Saving a file or printing its path is not sufficient.
+3. If the request fails or your tool cannot read the Markdown response, open and read the linked HTML version instead.
+4. If neither version can be retrieved, disclose that the current reference is unavailable and follow any topic-specific fallback in the skill. Use bundled guidance only for stable constraints, and do not guess at changeable platform details.
+
+When a task requires multiple references, apply this workflow to each one and distinguish the documents you verified from those that remain unavailable.
+<!-- /shared:documentation-retrieval -->