pub const SCATTER: &str = "# \u{6563}/\u{96c6} (Scatter/Gather) \u{2014} Parallel Processing\n\n## Syntax\n\n```\ninput | scatter [--as VAR] [--limit N] [--timeout DUR] | command | gather [--first N] [--format lines|json]\n```\n\n## Parameters\n\n**scatter:** `--as VAR` (default: `ITEM`) \u{2014} variable name per item. `--limit N` (default: 8, clamped to 1..=10000) \u{2014} max concurrent workers. Requests above 10000 are clamped and emit a `tracing::warn` on the `kaish::scatter` target. `--timeout DUR` (default: none) \u{2014} per-worker timeout (`30`, `5s`, `500ms`, `2m`, `1h`); cancels the worker and kills its external children with the kernel\'s `kill_grace`. Workers that hit the timeout are tagged `\"timed_out\": true` in `gather --format json` output.\n\n**gather:** `--first N` (default: 0/all) \u{2014} take first N results. `--format lines|json` (default: `lines`) \u{2014} output format. JSON output includes per-worker `timed_out` flag.\n\n## Example\n\n```bash\n# Fan out to 4 workers, compute squares, collect first 5 as JSON\nseq 1 20 | scatter --as N --limit 4 | echo \"{\\\"id\\\": $N, \\\"square\\\": $((N * N))}\" | gather --first 5 --format json\n\n# Process files in parallel\nglob \"*.json\" | scatter --as FILE --limit 4 | jq \".name\" $FILE | gather\n```\n\n## Behavior\n\n- Results arrive in **completion order**, not input order\n- Each worker runs the full pipeline with `$VAR` set to its item\n- Outer scope variables are visible to workers\n- Workers share the same VFS\n- Failed workers: error collected, other workers continue\n- `set -e` before scatter stops on first error\n- **Workers run in a forked kernel.** Each parallel worker gets its own kernel instance with snapshotted session state (scope, cwd, aliases, user tools). This means workers can run the **full dispatch chain**: user-defined functions (`tool name { ... }`), `.kai` scripts, and command substitution in arguments all work correctly inside scatter workers. Mutations within a worker (e.g. changing a variable) stay within that worker and do not leak back to the parent or other workers.\n- **Cancellation cascades.** Workers fork with `fork_attached`, so their cancellation tokens are children of the parent kernel\'s. A parent timeout, `Kernel::cancel`, or REPL Ctrl-C propagates into every running worker and kills its external children via SIGTERM \u{2192} `kill_grace` \u{2192} SIGKILL.\n";