diff --git a/skills/rig/references/claude-workflow-conversion.md b/skills/rig/references/claude-workflow-conversion.md
index 46c3ca5..579089a 100644
--- a/skills/rig/references/claude-workflow-conversion.md
+++ b/skills/rig/references/claude-workflow-conversion.md
@@ -19,7 +19,7 @@ primitives from its context instead of from globals.
 | `await agent(prompt)` | `await call.text(prompt, options?)` | Returns `string \| null` |
 | `await agent(prompt, { schema })` | `await call.json(prompt, schema, options?)` | `schema` is any `s.*` value (`s.object`, `s.enum`, `s.array`, …); result is typed and validated. Claude workflows only support object schemas; rig accepts any schema type. |
 | Reused prompt + schema pair | `agent({ input, output, instructions })` then `call(worker, input, options?)` | Preferred for anything invoked more than once |
-| `parallel(thunks)` | `parallel(thunks)` | Same barrier semantics; failures become `null` holes |
+| `parallel(thunks)` | `parallel(thunks)` | Same barrier semantics; failures become `null` holes. **TypeScript note:** `parallel` uses a single generic `Result` type, so all thunks must return the same type. For agents with different output types, use `Promise.all` (which skips the concurrency limiter) or cast: `parallel<TypeA \| TypeB>([...]) as Promise<[TypeA \| null, TypeB \| null]>`. |
 | `pipeline(items, ...stages)` | `pipeline(items, ...stages)` | Stages receive `(previous, item, index)`; the first stage's `previous` is the item |
 | `phase(title)` | `phase(title)` | Same |
 | `{ phase: "Verify" }` on a call | `{ phase: "Verify" }` in call options | Overrides the ambient phase for that call only |
diff --git a/skills/rig/samples/390-parallel-multi-tool-workflow.md b/skills/rig/samples/390-parallel-multi-tool-workflow.md
index 474f691..db3e857 100644
--- a/skills/rig/samples/390-parallel-multi-tool-workflow.md
+++ b/skills/rig/samples/390-parallel-multi-tool-workflow.md
@@ -1,5 +1,10 @@
 # 390 - Parallel Multi-Tool Workflow
 
+Uses `parallel(thunks)` — the rig equivalent of `parallel(thunks)` in Claude
+dynamic workflows. Respects the shared concurrency limiter and converts failures
+to `null` holes. Use it instead of `Promise.all` when porting a Claude dynamic
+workflow.
+
 ```rig
 import { workflow, agent, p, s } from "rig";
 
@@ -30,6 +35,7 @@ Return categories map and totalVars count.`,
 });
 
 // Workflow role: Run file count and env health agents in parallel, then combine into an overall health report.
+// `parallel(thunks)` requires uniform thunk return types; use `Promise.all` for heterogeneous agents.
 const parallelMultiToolWorkflow = workflow({
   meta: { name: "workspaceHealth", description: "Parallel workspace health analysis", phases: ["Measure", "Rate"] },
   body: async ({ call, phase }) => {
diff --git a/skills/rig/samples/412-parallel-branch-analysis-workflow.md b/skills/rig/samples/412-parallel-branch-analysis-workflow.md
index 866398c..7875e33 100644
--- a/skills/rig/samples/412-parallel-branch-analysis-workflow.md
+++ b/skills/rig/samples/412-parallel-branch-analysis-workflow.md
@@ -33,6 +33,7 @@ ${p.bash("git log --oneline --since='30 days ago' 2>/dev/null || echo ''")}`,
 });
 
 // Workflow role: run branch health and commit frequency agents in parallel, then classify overall health.
+// `parallel(thunks)` requires uniform thunk return types; use `Promise.all` for heterogeneous agents.
 const parallelBranchAnalysis = workflow({
   meta: { name: "parallelBranchAnalysis", description: "Parallel branch analysis", phases: ["Analyze", "Rate"] },
   body: async ({ call, phase }) => {
diff --git a/skills/rig/samples/430-parallel-git-stats-workflow.md b/skills/rig/samples/430-parallel-git-stats-workflow.md
index 9c5f310..71af9cc 100644
--- a/skills/rig/samples/430-parallel-git-stats-workflow.md
+++ b/skills/rig/samples/430-parallel-git-stats-workflow.md
@@ -36,6 +36,7 @@ totalFiles = sum of all counts.`,
 });
 
 // Workflow role: run commit stats and file stats in parallel, then combine results.
+// `parallel(thunks)` requires uniform thunk return types; use `Promise.all` for heterogeneous agents.
 const parallelGitStatsWorkflow = workflow({
   meta: { name: "parallel-git-stats", description: "Run commit and file stats in parallel." },
   body: async ({ call }) => {