Update Render Workflows skill for SDK 1.x

skills/render-workflows/references/local-development.md

@@ -1,116 +1,106 @@
 # Local Development
 
-Run workflow tasks locally for faster development and testing.
-
-## Contents
-
-- Prerequisites
-- Starting the local task server
-- Triggering task runs (CLI and application code)
-- Viewing results
-- Limitations
+Use the Render CLI's local task server to register and run tasks without deploying. Read the current [local development documentation](https://render.com/docs/workflows-local-development) when behavior differs from this reference.
 
 ## Prerequisites
 
-- **Render CLI 2.11.0+**: `render --version`
-  - 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/)
-- A workflow project with registered tasks
+- Render CLI 2.12.0 or later for local development; this skill recommends 2.16.0 or later for the complete scaffolding and deployment flow
+- A Python or TypeScript workflow project with its dependencies installed
+- A non-Docker workflow start command; Docker-based workflows do not currently support the local task server
 
-## Starting the Local Task Server
+## Start the Local Task Server
 
-From your project directory:
+Run from the workflow project's root directory:
 
 ```bash
 # Python
-render workflows dev -- python workflows/main.py
+render workflows dev -- python main.py
 
-# TypeScript
-render workflows dev -- npx tsx workflows/main.ts
+# TypeScript starter
+render workflows dev -- npm start
 ```
 
-The local server starts on port `8120`. Customize with `--port`:
+The default port is `8120`. Use the same custom port on every related CLI command:
 
 ```bash
-render workflows dev --port 8121 -- python workflows/main.py
+render workflows dev --port 8121 -- python main.py
+render workflows tasks list --local --port 8121
 ```
 
-The server picks up code changes automatically as you iterate.
+The CLI loads `.env` from the current directory automatically. To load explicit files, pass `--env-file` more than once if needed; later files override earlier files:
+
+```bash
+render workflows dev \
+  --env-file .env \
+  --env-file .env.local \
+  -- python main.py
+```
 
-## Triggering Task Runs
+Use `--debug` when task execution events are needed for diagnosis.
 
-### From the CLI
+## Run and Inspect Tasks
 
-List and run tasks interactively:
+Interactive task browser:
 
 ```bash
 render workflows tasks list --local
 ```
 
-**The `--local` flag is required.** Without it, the CLI lists deployed (remote) tasks.
+Non-interactive flow:
 
-The interactive menu lets you:
-1. Select a task
-2. Choose `run`
-3. Provide input as a JSON array (e.g., `[5]` or `[]`)
-4. View live logs
+```bash
+render workflows tasks list --local -o text
+render workflows start calculate_square --local --input='[5]' -o text
+render workflows tasks runs list calculate_square --local -o text
+render workflows tasks runs show <task-run-id> --local -o json
+render workflows cancel <task-run-id> --local
+```
 
-### From Application Code
+Use `-o text`, `-o json`, or `-o yaml` to disable menu navigation. The canonical long form of `render workflows start` is `render workflows tasks runs start`; the canonical long form of `cancel` is `render workflows tasks runs cancel`.
 
-Configure your app to target the local task server.
+Non-interactive `workflows start` can return while the run is still queued or running. Copy its task run ID and poll `tasks runs show` for a bounded period until the status is completed, failed, or canceled. Confirm the result or error rather than treating run creation as successful execution.
 
-**Python:**
+Inputs:
 
-Set environment variables:
-```bash
-RENDER_USE_LOCAL_DEV=true
-```
+- Use a JSON array for positional arguments: `[5]`, `["left", "right"]`, or `[]`.
+- A Python task can use a JSON object for named arguments: `{"value": 5}`.
+- Do not include the `TaskContext` parameter in either input form.
+
+## Trigger Local Runs from Application Code
+
+For complete Python and TypeScript client scripts with a verified `ping` result, follow [Try It Locally with the SDK](manual-scaffolding.md#try-it-locally-with-the-sdk).
+
+Local SDK calls do not require a Render API key or a deployed workflow. Set local mode in the **calling application's** environment (setting it only on the task server does not configure a separately running client):
 
-Or for a custom port:
 ```bash
-RENDER_USE_LOCAL_DEV=true
-RENDER_LOCAL_DEV_URL=http://localhost:8121
+export RENDER_USE_LOCAL_DEV=true
 ```
 
-The SDK clients (`Render()` and `RenderAsync()`) automatically detect these and route requests to the local server.
-
-**TypeScript:**
+For a custom server URL, also set:
 
-Same environment variables:
 ```bash
-RENDER_USE_LOCAL_DEV=true
+export RENDER_LOCAL_DEV_URL=http://localhost:8121
 ```
 
-Or pass configuration directly:
+Python `Render()` and `RenderAsync()` clients detect these variables. TypeScript supports the same variables or explicit configuration:
+
 ```typescript
 import { Render } from "@renderinc/sdk";
 
 const render = new Render({
   useLocalDev: true,
-  localDevUrl: "http://localhost:8120",
+  localDevUrl: "http://localhost:8121",
 });
 ```
 
-**Render API (any language):**
-
-Swap the base URL for task endpoints:
-```
-http://localhost:8120
-```
-
-The local task server only simulates task-related endpoints. Other Render API endpoints are not supported locally.
-
-## Viewing Results
+For direct Render API code, use the local task server as the base URL for task endpoints only. Other Render API endpoints are not simulated.
 
-After running a task via the CLI:
-1. Press **Esc** to go back to the command menu
-2. Select `runs` to see task runs
-3. Select a run and choose `results` to see output
+## Local-Only Behavior
 
-## Limitations
+- Logs and results are held in memory and disappear when the server stops.
+- Stored run history can increase memory usage; restart the server during high-volume testing.
+- Local task and run identifiers are generated for each server session and do not correspond to deployed identifiers.
+- The server reloads task definitions when it starts subprocesses, so source changes are picked up without deploying.
+- Local execution simulates task orchestration but does not reproduce production container isolation, networking, or compute characteristics.
 
-- Logs and results are stored **in memory** and lost on server shutdown
-- High volume of runs can increase memory usage; restart the server periodically
-- Task and run IDs are random UUIDs, not matching deployed identifiers
-- Subtasks run locally in the same server process
+Stop the local task server after verification when an agent started it for the user.