docs: fix CLAUDE.md casing, refresh root, add per-package guides

- Rename claude.md -> CLAUDE.md. Git tracked it lowercase, which works
  on macOS (case-insensitive filesystem) but means agents on Linux/CI
  never load it — they look for the uppercase name. The instructions
  were invisible on Linux.

- Refresh the root file against the current codebase: Node 24 (was
  18+), fix the typesync script name and the linker path, add
  `pnpm format`, split env vars by CLI vs worker, and add a short
  "Working with Projects" section covering the project subcommand.

- Correct a misleading testing note. It claimed all tests run against
  dist/. In fact each package tests against its own src/ via
  @swc-node/register; only engine-multi (which runs its workers from
  dist/) and cross-package deps need a build first.

- Add per-package CLAUDE.md for runtime, engine-multi and ws-worker —
  the packages with the least obvious invariants (VM sandboxing, the
  multi-process serialization boundary, strict event ordering). Kept
  short and focused on gotchas, not a rehash of the READMEs.
  These get loaded only when the agent is working with files in that package,
  keeping the context window leaner.

- Remove .claude/command-refactor.md: looked like a plan for a refactor
  that already shipped, had drifted.

- Trim .claude/event-processor.md to behavioural description, dropping
  variable-level detail that goes stale. Still accurate; stays as a
  doc companion to the worker's CLAUDE.md.

Author: stuartc

.claude/command-refactor.md

@@ -106,25 +106,14 @@ Bugs in one handler don't cascade to other events, but partial state may be visi
 
 ## Integration Points
 
-### Initialization (execute.ts)
-
-```
-eventProcessor(engine, context, {
-  [WORKFLOW_START]: handleRunStart,
-  [JOB_START]: handleStepStart,
-  [JOB_COMPLETE]: handleStepComplete,
-  [JOB_ERROR]: onJobError,
-  [WORKFLOW_LOG]: handleRunLog,
-  [WORKFLOW_COMPLETE]: handleRunComplete,
-  [WORKFLOW_ERROR]: handleRunError,
-}, {
-  batch: options.batchLogs ? { [WORKFLOW_LOG]: true } : {},
-  batchInterval: options.batchInterval,
-  batchLimit: options.batchLimit,
-})
-```
-
-Processor set up before workflow starts, ensuring no events missed.
+### Initialization
+
+The processor is created before the workflow starts (so no events are missed), and is given:
+
+- a map of engine event name → handler (workflow start/complete/error, job/step start/complete/error, log)
+- batching options: which event types batch (currently only logs, and only when `batchLogs` is enabled), a batch size limit and interval, and a per-event fallback timeout
+
+The exact option shape changes over time — read `src/api/execute.ts` for the current call, and `src/api/process-events.ts` for the loop itself.
 
 ### Websocket Layer (send-event.ts)
 
@@ -172,12 +161,10 @@ Processor set up before workflow starts, ensuring no events missed.
 
 5. **No explicit teardown**: Relies on engine event emitter lifecycle; queue drains naturally when workflow completes
 
-## Critical Implementation Details
+## Where to Look
+
+Core loop: `src/api/process-events.ts`. Websocket send wrapper: `src/util/send-event.ts`. Handlers: `src/events/`.
 
-- Active batch tracked with `activeBatch` variable (event name or null)
-- Batch events stored in `batch` array, cleared after send
-- Batch timeout stored in `batchTimeout`, cleared when batch sends
-- Queue implemented as array, items are `{name, event}` objects
-- Processing triggered by `enqueue` when queue length becomes 1
-- Recursive `next()` call after queue shift creates continuous flow
-- Event handlers imported from events directory, mapped explicitly in execute function
+- The queue is an array of `{name, event}`; processing kicks off when the first item lands and drains one item at a time.
+- An open batch accumulates matching events (peek-ahead) and flushes on size limit, interval timeout, or arrival of a non-matching event.
+- Exact variable names and default values shift over time — trust the behavioural rules above and read the source for specifics.

.claude/event-processor.md

@@ -37,11 +37,27 @@ The repository has three main packages: **CLI**, **Runtime**, and **Worker**. Th
 
 The **Compiler** transforms job DSL code into standard ES modules with imports and operation arrays.
 
+## Working with Projects
+
+A **workspace** holds one or more local **projects** that sync with Lightning. The CLI `project` subcommand (package: `@openfn/project`) is the most actively-developed area of the repo; handlers live in `packages/cli/src/projects/`. Sync uses Lightning's v2 endpoint.
+
+```bash
+openfn project list                # List projects in the current workspace
+openfn project pull [project]      # Pull from Lightning to the filesystem (fetch + checkout)
+openfn project fetch [project]     # Download project state without expanding it
+openfn project checkout <project>  # Switch the active project in the workspace
+openfn project deploy [project]    # Deploy the checked-out project to Lightning
+openfn project clean               # Delete the workflows folder and re-checkout the active project
+openfn project version [workflow]  # Show the version hash of a workflow
+```
+
+New subcommands follow the existing pattern in `packages/cli/src/projects/` (`list.ts` is the simplest reference).
+
 ## Development Setup
 
 ### Prerequisites
 
-- Node.js 18+ (use `asdf`)
+- Node.js 24 (pinned in `.tool-versions`; `package.json` engines still allows `>=18`). Use `asdf`.
 - pnpm (enable with `corepack enable`)
 
 ### Common Commands
@@ -51,6 +67,7 @@ The **Compiler** transforms job DSL code into standard ES modules with imports a
 pnpm install             # Install dependencies
 pnpm build              # Build all packages
 pnpm test               # Run all tests
+pnpm format             # Format all packages with Prettier
 pnpm changeset          # Add a changeset for your PR
 
 # CLI
@@ -68,18 +85,22 @@ curl -X POST http://localhost:2222/claim  # Manual claim
 
 ### Environment Variables
 
+**CLI:**
 - `OPENFN_REPO_DIR` - CLI adaptor storage
 - `OPENFN_ADAPTORS_REPO` - Local adaptors monorepo path
 - `OPENFN_API_KEY` - API key for Lightning deployment
 - `OPENFN_ENDPOINT` - Lightning URL (default: app.openfn.org)
+
+**Worker:**
 - `WORKER_SECRET` - Worker authentication secret
+- Many other `WORKER_*` vars (capacity, port, backoff, max payload, Sentry DSN, …) — see `packages/ws-worker/src/util/cli.ts`.
 
 ## Repository Structure
 
 ```
 packages/
 ├── cli/          # CLI entry: cli.ts, commands.ts, projects/, options.ts
-├── runtime/      # Runtime entry: index.ts, runtime.ts, util/linker
+├── runtime/      # Runtime entry: index.ts, runtime.ts, modules/linker
 ├── ws-worker/    # Worker entry: start.ts, server.ts, api/, events/
 ├── compiler/     # Job DSL compiler
 ├── engine-multi/ # Multi-process wrapper
@@ -109,15 +130,16 @@ cd packages/cli && pnpm test:watch  # Watch mode
 
 The [.claude](.claude) folder contains detailed guides:
 
-- **[command-refactor.md](.claude/command-refactor.md)** - Refactoring CLI commands into project subcommand structure
-- **[event-processor.md](.claude/event-processor.md)** - Worker event processing architecture (batching, ordering)
+- **[event-processor.md](.claude/event-processor.md)** - Worker event processing deep-dive (ordering, batching) — companion to `packages/ws-worker/CLAUDE.md`
+
+Key packages also carry their own `CLAUDE.md` (runtime, engine-multi, ws-worker), auto-loaded when you work in them.
 
 ## Code Standards
 
 - **Formatting**: Use Prettier (`pnpm format`)
 - **TypeScript**: Required for all new code
-- **TypeSync**: Run `pnpm typesync` after modifying dependencies
-- **Tests**: Write tests and run `pnpm build` before testing (tests run against `dist/`)
+- **TypeSync**: Run `pnpm _typesync` after modifying dependencies
+- **Tests**: Each package's tests run against its own `src/` via `@swc-node/register` (no build of the package under test needed). BUT workspace `@openfn/*` deps resolve to their built `dist/`, and `engine-multi` runs its worker processes from `dist/` — so run `pnpm build` first when tests cross packages or use the engine. When unsure, build.
 - **Independence**: Keep packages loosely coupled where possible
 
 ## Architecture Principles

claude.md CLAUDE.mdclaude.md renamed to CLAUDE.md

@@ -0,0 +1,22 @@
+# Engine (@openfn/engine-multi)
+Wraps @openfn/runtime to execute each workflow in an isolated worker_thread nested inside a pooled child_process, so concurrent runs can't corrupt or starve each other.
+
+## Invariants
+- Three-tier process tree: main process (engine) -> forked child_process (pool member) -> worker_thread (where @openfn/runtime actually runs). Each child hosts exactly one thread, spawned per task and terminated on completion.
+- Everything crossing main<->child<->thread goes over Node IPC / postMessage and is structured-cloned. Only serializable data survives: no functions, closures, class instances, or live handles. This is why resolvers/credentials are preloaded on the main thread and the fully-resolved plan is sent in — you cannot call back into the parent mid-run.
+- Errors must be plain serializable objects before crossing the boundary (use the error serializer); reconstruct Error instances on the parent side. Don't pass Error objects expecting stack/prototype to survive.
+- All messages over the boundary carry a `type` discriminator; the pool routes on the task-resolve / task-reject / run-task message types. New cross-boundary messages must follow this tagged shape.
+- The runtime's own timeout is disabled; the pool owns timeouts by killing the child. The runtime's module whitelist is the security boundary for what a job may import — regexes are stringified to cross the boundary and rehydrated in the thread.
+- Outgoing thread payloads are size-checked and oversized fields (state, logs) are redacted, not truncated transparently. Don't assume an emitted event carries the full state.
+
+## Gotchas
+- Run the engine via the async factory and await it — it validates a live worker (handshake) before accepting work; a bad/missing worker file fails here, not at execute time.
+- Autoinstall and credential preloading happen on the MAIN thread before the task is dispatched; compilation happens INSIDE the thread. Don't move install/network work into the thread or expect lazy credential loading.
+- A clean worker exit uses a sentinel exit code; any other exit code is treated as a crash. OOM is detected by scraping the child's stderr for the V8 heap message — fragile, and distinct from the timeout path (which kills the child proactively).
+- Pool has fixed capacity; tasks beyond capacity queue rather than spawning unbounded children. Children are reused (returned to pool) unless killed by crash/OOM/timeout, so don't rely on fresh global state per run at the child level — isolation comes from the per-run thread, not the child.
+- Consumers get a per-workflow emitter; events are proxied main<-child<-thread. `listen()` can be called before `execute()` (handlers are deferred), and execute is dispatched on a tick so listeners can attach first. ws-worker's event processor consumes these.
+- `console.log` inside the thread is hijacked into the adaptor logger and won't reach stdout; use `console.debug` for raw stdout debugging.
+
+## Testing
+- Tests run against `dist/` (worker entrypoints are resolved as built files, e.g. `dist/worker/...`, `dist/test/...`). Run `pnpm build` before `pnpm test` or paths won't resolve.
+- ava runs `--serial` (process/pool tests are stateful). Mock workers/runners exist as separate tsup entries (mock-run, worker-functions) — pass a custom worker path into the engine/pool to use them instead of the real runtime.