awaitly 1.5.0 → 1.6.0

package/README.md

@@ -1,25 +1,256 @@
 # awaitly
 
-*basically, async done right*
+Stop writing `try/catch` in every async handler.
 
-Typed async workflows with automatic error inference. Build type-safe workflows with Result types, step caching, resume state, and human-in-the-loop support.
+awaitly lets you:
+- return errors as data (`ok` / `err`)
+- compose async steps linearly
+- TypeScript knows **all possible errors** automatically
+- map errors at the boundary (HTTP, RPC, jobs)
 
-**You've been here before:** You're debugging a production issue at 2am. The error says "Failed to load user data." But *why* did it fail? Was it the database? The cache? The API? TypeScript can't help you - it just sees `unknown` in every catch block.
-
-This library fixes that. Your errors become **first-class citizens** with full type inference, so TypeScript knows exactly what can go wrong before your code even runs.
+No exceptions for expected failures. No manual error unions.
 
 ```bash
 npm install awaitly
 ```
 
-📚 **[Full Documentation](https://jagreehal.github.io/awaitly/)** — guides, API reference, and examples.
+📚 **[Full Documentation](https://jagreehal.github.io/awaitly/)** - guides, API reference, and examples.
+
+---
+
+## The Problem
+
+JavaScript async code conflates two kinds of failures:
+
+- **Expected**: "User not found", "Payment declined" — these are business outcomes
+- **Unexpected**: Network timeout, SDK crash, OOM — these are bugs
+
+Traditional try/catch loses type information:
+
+```typescript
+try {
+  const user = await getUser(id);
+  const order = await createOrder(user);
+} catch (error) {
+  // What type is error? unknown.
+  // Was it "user not found" or a network crash? No idea.
+}
+```
+
+awaitly separates these: expected failures become typed data, unexpected failures become `UnexpectedError`.
+
+---
+
+## Results as Data
+
+Functions that can fail return `AsyncResult<SuccessType, ErrorType>`:
+
+```typescript
+import { ok, err, type AsyncResult } from "awaitly";
+
+type User = { id: string; name: string };
+type UserNotFound = { type: "USER_NOT_FOUND"; userId: string };
+
+async function getUser(id: string): AsyncResult<User, UserNotFound> {
+  if (id === "u-1") return ok({ id, name: "Alice" });
+  return err({ type: "USER_NOT_FOUND", userId: id });
+}
+
+const result = await getUser("u-2");
+if (result.ok) {
+  console.log(result.value.name); // TypeScript knows this is User
+} else {
+  console.log(result.error.userId); // TypeScript knows this is UserNotFound
+}
+```
+
+No exceptions. TypeScript tracks every possible error.
+
+---
+
+## The Composition Problem
+
+When you compose multiple Result-returning functions, you hit boilerplate:
+
+```typescript
+// ❌ Every call needs: if (!result.ok) return result
+async function processOrder(orderId: string) {
+  const orderResult = await getOrder(orderId);
+  if (!orderResult.ok) return orderResult; // boilerplate
+
+  const userResult = await getUser(orderResult.value.userId);
+  if (!userResult.ok) return userResult; // more boilerplate
+
+  const paymentResult = await charge(orderResult.value.total);
+  if (!paymentResult.ok) return paymentResult; // even more
+
+  return paymentResult;
+}
+```
+
+10 steps = 10 if-checks. This is what `step()` solves.
+
+---
+
+## run() — Simple Composition
+
+`run()` gives you a `step()` function that unwraps Results automatically:
+
+```typescript
+import { run } from "awaitly";
+
+const result = await run(async (step) => {
+  const order = await step(() => getOrder(orderId)); // unwraps ok, exits on err
+  const user = await step(() => getUser(order.userId)); // same
+  const payment = await step(() => charge(order.total)); // same
+  return payment;
+});
+```
+
+**The happy path reads linearly.** No if-checks.
+
+### Why thunks? `step(() => fn())` not `step(fn())`
+
+Always wrap in a function:
+
+```typescript
+step(() => getUser(id)); // ✅ Correct - step controls when it runs
+step(getUser(id)); // ❌ Wrong - executes immediately
+```
+
+Thunks enable:
+
+- **Caching**: step checks cache before calling
+- **Retries**: step can re-call on failure
+- **Timeouts**: step can abort mid-execution
+
+### UnexpectedError — The Safety Net
+
+If code throws instead of returning a Result, `run()` catches it:
+
+```typescript
+import { UNEXPECTED_ERROR } from "awaitly/workflow";
+
+if (!result.ok && result.error.type === UNEXPECTED_ERROR) {
+  console.error("Bug or SDK error:", result.error.cause);
+}
+```
+
+- **Expected failures** → your typed errors
+- **Unexpected failures** → `UnexpectedError`
+
+TypeScript forces you to handle both.
+
+---
+
+## createWorkflow — Production API
+
+`run()` requires manual error type declaration. `createWorkflow()` infers them automatically:
+
+```typescript
+import { createWorkflow } from "awaitly/workflow";
+
+const deps = {
+  getUser: async (id: string): AsyncResult<User, UserNotFound> => {
+    /* ... */
+  },
+  getOrder: async (id: string): AsyncResult<Order, OrderNotFound> => {
+    /* ... */
+  },
+};
+
+const workflow = createWorkflow(deps);
+
+const result = await workflow(async (step, deps) => {
+  const user = await step(() => deps.getUser(userId));
+  const order = await step(() => deps.getOrder(orderId));
+  return { user, order };
+});
+// TypeScript KNOWS: result.error is UserNotFound | OrderNotFound | UnexpectedError
+```
+
+### When to use which?
+
+| `run()`                        | `createWorkflow()`             |
+| ------------------------------ | ------------------------------ |
+| Simple one-off composition     | Production handlers            |
+| Explicit error types           | Automatic error inference      |
+| Building abstractions          | Caching, retries, events       |
+
+---
+
+## How It Works
+
+```mermaid
+flowchart TD
+    subgraph "step() unwraps Results, exits early on error"
+        S1["step(() => deps.fetchUser(...))"] -->|ok| S2["step(() => deps.fetchPosts(...))"]
+        S2 -->|ok| S3["step(() => deps.sendEmail(...))"]
+        S3 -->|ok| S4["✓ Success"]
+
+        S1 -.->|error| EXIT["Return error"]
+        S2 -.->|error| EXIT
+        S3 -.->|error| EXIT
+    end
+```
+
+Each `step()` unwraps a `Result`. If it's `ok`, you get the value and continue. If it's an error, the workflow exits immediately — no manual `if (!result.ok)` checks needed. The happy path stays clean.
+
+---
+
+## Key Concepts
+
+| Concept             | What it does                                                                             |
+| ------------------- | ---------------------------------------------------------------------------------------- |
+| **Result**          | `ok(value)` or `err(error)` — typed success/failure, no exceptions                       |
+| **Workflow**        | Wraps your dependencies and tracks their error types automatically                       |
+| **step()**          | Unwraps a Result, short-circuits on failure, enables caching/retries                     |
+| **step.try**        | Catches throws and converts them to typed errors                                         |
+| **step.fromResult** | Preserves rich error objects from other Result-returning code                            |
+| **Events**          | `onEvent` streams everything — timing, retries, failures — for visualization or logging  |
+| **Resume**          | Save completed steps, pick up later (great for approvals or crashes)                     |
+| **UnexpectedError** | Safety net for throws outside your declared errors; map it to HTTP 500 at the boundary   |
+
+---
+
+## Quickstart
+
+Now that you understand the concepts, here's the complete pattern:
+
+```typescript
+import { ok, err, type AsyncResult } from "awaitly";
+import { createWorkflow } from "awaitly/workflow";
+
+type Task = { id: string };
+type TaskNotFound = { type: "TASK_NOT_FOUND"; id: string };
+
+// 1. Define dependencies that return Results
+const deps = {
+  loadTask: async (id: string): AsyncResult<Task, TaskNotFound> => {
+    if (id === "t-1") return ok({ id });
+    return err({ type: "TASK_NOT_FOUND", id });
+  },
+};
+
+// 2. Create and run a workflow
+const workflow = createWorkflow(deps);
+
+const result = await workflow(async (step, deps) => {
+  return await step(() => deps.loadTask("t-1"));
+});
+
+// 3. Handle the result
+console.log(result.ok ? result.value : result.error);
+```
+
+### What just happened?
 
-**What you get:**
+- `deps.loadTask` returns a Result (`ok` or `err`)
+- `createWorkflow(deps)` groups dependencies and infers all possible errors
+- `step(() => ...)` runs the operation and unwraps the success value
+- if a step returns `err`, the workflow exits early
 
-- **Automatic error inference** - Error types flow from your dependencies. Add a step? The union updates. Remove one? It updates. Zero manual tracking.
-- **Built-in reliability** - Retries, timeouts, caching, and circuit breakers when you need them. Not before.
-- **Resume & approvals** - Pause workflows for human review, persist state, pick up where you left off.
-- **Full visibility** - Event streams, ASCII timelines, Mermaid diagrams. See what ran, what failed, and why.
+---
 
 ## Before & After: See Why This Matters
 
@@ -86,128 +317,106 @@ async function executeTransfer(
 **With workflow: typed errors, automatic inference, clean code**
 
 ```typescript
-import { ok, err, type AsyncResult } from 'awaitly';
-import { createWorkflow } from 'awaitly/workflow';
+import { ok, err, type AsyncResult } from "awaitly";
+import { createWorkflow, UNEXPECTED_ERROR } from "awaitly/workflow";
 
-// Define typed error types (explicit and type-safe!)
-type UserNotFound = { type: 'USER_NOT_FOUND'; userId: string };
-type InsufficientFunds = { type: 'INSUFFICIENT_FUNDS'; required: number; available: number };
-type TransferFailed = { type: 'TRANSFER_FAILED'; reason: string };
+type User = { id: string; balance: number };
+type UserNotFound = { type: "USER_NOT_FOUND"; userId: string };
+type InsufficientFunds = { type: "INSUFFICIENT_FUNDS"; required: number; available: number };
+type TransferFailed = { type: "TRANSFER_FAILED"; reason: string };
 
-// Operations return Results - errors are part of the type signature
 const deps = {
-  getUser: async (userId: string): AsyncResult<{ id: string; balance: number }, UserNotFound> => {
-    if (userId === "unknown") {
-      return err({ type: 'USER_NOT_FOUND', userId }); // Typed error with context!
-    }
+  getUser: async (userId: string): AsyncResult<User, UserNotFound> => {
+    if (userId === "unknown") return err({ type: "USER_NOT_FOUND", userId });
     return ok({ id: userId, balance: 1000 });
   },
 
-  validateBalance: (user: { balance: number }, amount: number): AsyncResult<void, InsufficientFunds> => {
+  validateBalance: (user: User, amount: number): AsyncResult<void, InsufficientFunds> => {
     if (user.balance < amount) {
-      return err({
-        type: 'INSUFFICIENT_FUNDS',
-        required: amount,
-        available: user.balance, // Rich error context!
-      });
+      return err({ type: "INSUFFICIENT_FUNDS", required: amount, available: user.balance });
     }
     return ok(undefined);
   },
 
-  executeTransfer: async (
-    fromUser: { id: string },
-    toUser: { id: string },
-    amount: number
-  ): AsyncResult<{ transactionId: string }, TransferFailed> => {
+  executeTransfer: async (): AsyncResult<{ transactionId: string }, TransferFailed> => {
     return ok({ transactionId: "tx-12345" });
   },
 };
 
-// ✅ TypeScript knows ALL possible error types at compile time!
-const transferWorkflow = createWorkflow(deps);
-
-const result = await transferWorkflow(async (step) => {
-  // step() automatically unwraps success or exits early on error
-  // No try/catch needed! No manual null checks!
-  const fromUser = await step(deps.getUser(fromUserId));
-  const toUser = await step(deps.getUser(toUserId));
-  await step(deps.validateBalance(fromUser, amount));
-  const transaction = await step(deps.executeTransfer(fromUser, toUser, amount));
-  return transaction;
-});
+const transfer = createWorkflow(deps);
+
+// In an HTTP handler
+async function handler(fromUserId: string, toUserId: string, amount: number) {
+  const result = await transfer(async (step, deps) => {
+    const fromUser = await step(() => deps.getUser(fromUserId));
+    const toUser = await step(() => deps.getUser(toUserId));
+    await step(() => deps.validateBalance(fromUser, amount));
+    return await step(() => deps.executeTransfer());
+  });
+
+  // TypeScript knows ALL possible errors - map them to HTTP responses
+  if (result.ok) return { statusCode: 200, body: result.value };
 
-// Handle the final result with full type safety
-if (result.ok) {
-  console.log("Success! Transaction:", result.value.transactionId);
-} else {
-  // TypeScript knows EXACTLY which error types are possible!
   switch (result.error.type) {
-    case 'USER_NOT_FOUND':
-      console.log("Error: User not found:", result.error.userId); // Full context!
-      break;
-    case 'INSUFFICIENT_FUNDS':
-      console.log(`Error: Need $${result.error.required} but only have $${result.error.available}`);
-      break;
-    case 'TRANSFER_FAILED':
-      console.log("Error: Transfer failed:", result.error.reason);
-      break;
+    case "USER_NOT_FOUND":
+      return { statusCode: 404, body: { message: "User not found", userId: result.error.userId } };
+    case "INSUFFICIENT_FUNDS":
+      return { statusCode: 400, body: result.error };
+    case "TRANSFER_FAILED":
+    case UNEXPECTED_ERROR:
+      return { statusCode: 500, body: { message: "Internal error" } };
   }
 }
 ```
 
-**The magic:** Error types are **inferred from your dependencies**. Add a new step? The error union updates automatically. Remove one? It updates. You'll never `switch` on an error that can't happen, or miss one that can. TypeScript enforces it at compile time.
+**How it works:** TypeScript knows **all possible errors** from your dependencies. Add a step? The errors update automatically. Remove one? They update. You'll never miss an error case.
 
-## Quickstart (60 Seconds)
+---
 
-### 1. Define your operations
+## Mental model
 
-Return `ok(value)` or `err(errorCode)` instead of throwing.
+Think of awaitly like this:
 
-```typescript
-import { ok, err, type AsyncResult } from 'awaitly';
+- Leaf functions return data OR an error (never throw for expected cases)
+- A workflow runs steps in order
+- `step()`:
+  - gives you the value on success
+  - exits immediately on error
+- The boundary (HTTP, job, CLI) decides how to respond
 
-const fetchOrder = async (id: string): AsyncResult<Order, 'ORDER_NOT_FOUND'> =>
-  id ? ok({ id, total: 99.99, email: 'user@example.com' }) : err('ORDER_NOT_FOUND');
-
-const chargeCard = async (amount: number): AsyncResult<Payment, 'CARD_DECLINED'> =>
-  amount < 10000 ? ok({ id: 'pay_123', amount }) : err('CARD_DECLINED');
-```
+---
 
-### 2. Create and run
+## Mapping errors at the boundary
 
-`createWorkflow` handles the type magic. `step()` unwraps results or exits early on failure.
+The final result maps cleanly to HTTP responses, job statuses, or CLI exit codes:
 
 ```typescript
-import { createWorkflow } from 'awaitly/workflow';
+import { UNEXPECTED_ERROR } from "awaitly/workflow";
 
-const checkout = createWorkflow({ fetchOrder, chargeCard });
-
-const result = await checkout(async (step) => {
-  const order = await step(fetchOrder('order_456'));
-  const payment = await step(chargeCard(order.total));
-  return { order, payment };
-});
-// result.error is: 'ORDER_NOT_FOUND' | 'CARD_DECLINED' | UnexpectedError
-```
+// In an HTTP handler
+if (result.ok) {
+  return { statusCode: 200, body: result.value };
+}
 
-That's it! TypeScript knows exactly what can fail. Now let's see the full power.
+switch (result.error.type) {
+  case "TASK_NOT_FOUND":
+    return { statusCode: 404, body: { message: "Task not found" } };
 
-## How It Works
+  case UNEXPECTED_ERROR:
+    // Log the cause for debugging (it's the original thrown error)
+    console.error("Unexpected error:", result.error.cause);
+    return { statusCode: 500, body: { message: "Internal error" } };
 
-```mermaid
-flowchart TD
-    subgraph "step() unwraps Results, exits early on error"
-        S1["step(fetchUser)"] -->|ok| S2["step(fetchPosts)"]
-        S2 -->|ok| S3["step(sendEmail)"]
-        S3 -->|ok| S4["✓ Success"]
-
-        S1 -.->|error| EXIT["Return error"]
-        S2 -.->|error| EXIT
-        S3 -.->|error| EXIT
-    end
+  default:
+    return { statusCode: 500, body: { message: "Internal error" } };
+}
 ```
 
-Each `step()` unwraps a `Result`. If it's `ok`, you get the value and continue. If it's an error, the workflow exits immediately, no manual `if (result.isErr())` checks needed. The happy path stays clean.
+**Why `UnexpectedError`?**
+- Expected failures → your typed errors (e.g., `TASK_NOT_FOUND`)
+- Unexpected failures (bugs, SDK throws) → `UnexpectedError`
+
+TypeScript will force you to handle both. This is intentional.
 
 ---
 
@@ -218,13 +427,13 @@ Each `step()` unwraps a `Result`. If it's `ok`, you get the value and continue.
 Add resilience exactly where you need it - no nested try/catch or custom retry loops.
 
 ```typescript
-const result = await workflow(async (step) => {
+const result = await workflow(async (step, deps) => {
   // Retry 3 times with exponential backoff, timeout after 5 seconds
-  const user = await step.retry(
-    () => fetchUser('1'),
-    { attempts: 3, backoff: 'exponential', timeout: { ms: 5000 } }
+  const task = await step.retry(
+    () => deps.loadTask("t-1"),
+    { attempts: 3, backoff: "exponential", timeout: { ms: 5000 } }
   );
-  return user;
+  return task;
 });
 ```
 
@@ -264,10 +473,10 @@ const workflow = createWorkflow({ fetchUser, fetchPosts }, {
   onEvent: collector.handleEvent, // Automatically collects step_complete events
 });
 
-await workflow(async (step) => {
+await workflow(async (step, deps) => {
   // Only steps with keys are saved
-  const user = await step(() => fetchUser("1"), { key: "user:1" });
-  const posts = await step(() => fetchPosts(user.id), { key: `posts:${user.id}` });
+  const user = await step(() => deps.fetchUser("1"), { key: "user:1" });
+  const posts = await step(() => deps.fetchPosts(user.id), { key: `posts:${user.id}` });
   return { user, posts };
 });
 
@@ -305,9 +514,9 @@ const workflow = createWorkflow({ fetchUser, fetchPosts }, {
   resumeState: savedState, // Pre-populates cache from saved state
 });
 
-await workflow(async (step) => {
-  const user = await step(() => fetchUser("1"), { key: "user:1" }); // ✅ Cache hit - no fetchUser call
-  const posts = await step(() => fetchPosts(user.id), { key: `posts:${user.id}` }); // ✅ Cache hit
+await workflow(async (step, deps) => {
+  const user = await step(() => deps.fetchUser("1"), { key: "user:1" }); // ✅ Cache hit
+  const posts = await step(() => deps.fetchPosts(user.id), { key: `posts:${user.id}` }); // ✅ Cache hit
   return { user, posts };
 });
 ```
@@ -359,13 +568,13 @@ const requireApproval = createApprovalStep({
   },
 });
 
-const result = await refundWorkflow(async (step) => {
-  const refund = await step(calculateRefund(orderId));
+const result = await refundWorkflow(async (step, deps) => {
+  const refund = await step(() => deps.calculateRefund(orderId));
 
   // Workflow pauses here until someone approves
-  const approval = await step(requireApproval, { key: 'approve:refund' });
+  const approval = await step(() => requireApproval(), { key: "approve:refund" });
 
-  return await step(processRefund(refund, approval));
+  return await step(() => deps.processRefund(refund, approval));
 });
 
 if (!result.ok && isPendingApproval(result.error)) {
@@ -386,9 +595,9 @@ const workflow = createWorkflow({ fetchOrder, chargeCard }, {
   onEvent: viz.handleEvent,
 });
 
-await workflow(async (step) => {
-  const order = await step(() => fetchOrder('order_456'), { name: 'Fetch order' });
-  const payment = await step(() => chargeCard(order.total), { name: 'Charge card' });
+await workflow(async (step, deps) => {
+  const order = await step(() => deps.fetchOrder('order_456'), { name: 'Fetch order' });
+  const payment = await step(() => deps.chargeCard(order.total), { name: 'Charge card' });
   return { order, payment };
 });
 
@@ -397,815 +606,112 @@ console.log(viz.renderAs('mermaid'));
 
 ---
 
-## Start Here
-
-Let's build something real in five short steps. Each one adds a single concept - by the end, you'll have a working workflow with typed errors, retries, and full observability.
-
-### Step 1 - Install
-
-```bash
-npm install awaitly
-# or
-pnpm add awaitly
-```
-
-### Step 2 - Describe Async Dependencies
-
-Define the units of work as `AsyncResult<T, E>` helpers. Results encode success (`ok`) or typed failure (`err`).
-
-```typescript
-import { ok, err, type AsyncResult } from 'awaitly';
-
-type User = { id: string; name: string };
-
-const fetchUser = async (id: string): AsyncResult<User, 'NOT_FOUND'> =>
-  id === '1' ? ok({ id, name: 'Alice' }) : err('NOT_FOUND');
-```
-
-### Step 3 - Compose a Workflow
-
-`createWorkflow` collects dependencies once so the library can infer the total error union.
-
-```typescript
-import { createWorkflow } from 'awaitly/workflow';
-
-const workflow = createWorkflow({ fetchUser });
-```
+## What's next?
 
-### Step 4 - Run & Inspect Results
+You have the foundation. Pick one:
 
-Use `step()` inside the executor. It unwraps results, exits early on failure, and gives a typed `result` back to you.
+- **If you need retries/timeouts:** [Reliability guide](https://jagreehal.github.io/awaitly/advanced/policies/)
+- **If you need crash recovery:** [Persistence guide](https://jagreehal.github.io/awaitly/guides/persistence/)
+- **If you want observability:** [Visualization guide](https://jagreehal.github.io/awaitly/guides/visualization/)
 
-```typescript
-const result = await workflow(async (step) => {
-  const user = await step(fetchUser('1'));
-  return user;
-});
-
-if (result.ok) {
-  console.log(result.value.name);
-} else {
-  console.error(result.error); // 'NOT_FOUND' | UnexpectedError
-}
-```
+## Advanced Features (when you need them)
 
-### Step 5 - Add Safeguards
-
-Introduce retries, timeout protection, or wrappers for throwing code only when you need them.
-
-```typescript
-const data = await workflow(async (step) => {
-  const user = await step(fetchUser('1'));
-
-  const posts = await step.try(
-    () => fetch(`/api/users/${user.id}/posts`).then((r) => {
-      if (!r.ok) throw new Error(`HTTP ${r.status}`);
-      return r.json();
-    }),
-    { error: 'FETCH_FAILED' as const }
-  );
-
-  return { user, posts };
-});
-```
-
-That's the foundation. Now let's build on it.
+- **Retries / timeouts / backoff** → [Reliability guide](https://jagreehal.github.io/awaitly/advanced/policies/)
+- **Step caching with keys** → [Caching guide](https://jagreehal.github.io/awaitly/guides/caching/)
+- **Save & resume** → [Persistence guide](https://jagreehal.github.io/awaitly/guides/persistence/)
+- **Human-in-the-loop approvals** → [HITL guide](https://jagreehal.github.io/awaitly/guides/human-in-loop/)
+- **Visualization via `onEvent`** → [Visualization guide](https://jagreehal.github.io/awaitly/guides/visualization/)
 
 ---
 
-## Persistence Quickstart
-
-Save workflow state to a database and resume later. Perfect for crash recovery, long-running workflows, or pausing for approvals.
-
-### Basic Save & Resume
+## Common Patterns (quick reference)
 
 ```typescript
-import { createWorkflow, createResumeStateCollector } from 'awaitly/workflow';
-import { stringifyState, parseState } from 'awaitly/persistence';
-
-// 1. Collect state during execution
-const collector = createResumeStateCollector();
-const workflow = createWorkflow({ fetchUser, fetchPosts }, {
-  onEvent: collector.handleEvent,
-});
-
-await workflow(async (step) => {
-  const user = await step(() => fetchUser("1"), { key: "user:1" });
-  const posts = await step(() => fetchPosts(user.id), { key: `posts:${user.id}` });
-  return { user, posts };
-});
-
-// 2. Save to database
-const state = collector.getResumeState();
-const json = stringifyState(state, { workflowId: "123" });
-await db.workflowStates.create({ id: "123", state: json });
+// Wrap throwing code
+const data = await step.try(() => fetch(url).then(r => r.json()), { error: "HTTP_FAILED" as const });
 
-// 3. Resume later
-const saved = await db.workflowStates.findUnique({ where: { id: "123" } });
-const savedState = parseState(saved.state);
+// Retries with backoff
+const user = await step.retry(() => deps.fetchUser(id), { attempts: 3, backoff: "exponential" });
 
-const resumed = createWorkflow({ fetchUser, fetchPosts }, {
-  resumeState: savedState,
-});
+// Timeout protection
+const result = await step.withTimeout(() => deps.slowOperation(), { ms: 5000 });
 
-// Cached steps skip execution automatically
-await resumed(async (step) => {
-  const user = await step(() => fetchUser("1"), { key: "user:1" }); // ✅ Cache hit
-  const posts = await step(() => fetchPosts(user.id), { key: `posts:${user.id}` }); // ✅ Cache hit
-  return { user, posts };
-});
+// Caching (use thunk + key)
+const user = await step(() => deps.fetchUser(id), { key: `user:${id}` });
 ```
 
-### With Database Adapter (Redis, DynamoDB, etc.)
-
-```typescript
-import { createStatePersistence } from 'awaitly/persistence';
-import { createClient } from 'redis';
-
-const redis = createClient();
-await redis.connect();
-
-// Create persistence adapter
-const persistence = createStatePersistence({
-  get: (key) => redis.get(key),
-  set: (key, value) => redis.set(key, value),
-  delete: (key) => redis.del(key).then(n => n > 0),
-  exists: (key) => redis.exists(key).then(n => n > 0),
-  keys: (pattern) => redis.keys(pattern),
-}, 'workflow:state:');
-
-// Save
-const collector = createResumeStateCollector();
-const workflow = createWorkflow(deps, { onEvent: collector.handleEvent });
-await workflow(async (step) => { /* ... */ });
-
-await persistence.save('run-123', collector.getResumeState(), { userId: 'user-1' });
-
-// Load and resume
-const savedState = await persistence.load('run-123');
-const resumed = createWorkflow(deps, { resumeState: savedState });
-```
-
-**See the [Save & Resume](#-save--resume-persist-workflows-across-restarts) section for more details.**
-
 ---
 
-## Guided Tutorial
-
-We'll take a single workflow through four stages - from basic to production-ready. Each stage builds on the last, so you'll see how features compose naturally.
-
-### Stage 1 - Hello Workflow
-
-1. Declare dependencies (`fetchUser`, `fetchPosts`).
-2. Create the workflow: `const loadUserData = createWorkflow({ fetchUser, fetchPosts })`.
-3. Use `step()` to fan out and gather results.
-
-```typescript
-const fetchPosts = async (userId: string): AsyncResult<Post[], 'FETCH_ERROR'> =>
-  ok([{ id: 1, title: 'Hello World' }]);
-
-const fetchUser = async (id: string): AsyncResult<User, 'NOT_FOUND'> =>
-  id === '1' ? ok({ id, name: 'Alice' }) : err('NOT_FOUND');
-
-const loadUserData = createWorkflow({ fetchUser, fetchPosts });
-
-const result = await loadUserData(async (step) => {
-  const user = await step(fetchUser('1'));
-  const posts = await step(fetchPosts(user.id));
-  return { user, posts };
-});
-```
-
-### Stage 2 - Validation & Branching
-
-Add validation helpers and watch the error union update automatically.
-
-```typescript
-const validateEmail = async (email: string): AsyncResult<string, 'INVALID_EMAIL'> =>
-  email.includes('@') ? ok(email) : err('INVALID_EMAIL');
-
-const signUp = createWorkflow({ validateEmail, fetchUser });
-
-const result = await signUp(async (step) => {
-  const email = await step(validateEmail('user@example.com'));
-  const user = await step(fetchUser(email));
-  return { email, user };
-});
-```
-
-### Stage 3 - Reliability Features
-
-Layer in retries, caching, and timeouts only around the calls that need them.
-
-```typescript
-const resilientWorkflow = createWorkflow({ fetchUser, fetchPosts }, {
-  cache: new Map(),
-});
-
-const result = await resilientWorkflow(async (step) => {
-  const user = await step.retry(
-    () => fetchUser('1'),
-    {
-      attempts: 3,
-      backoff: 'exponential',
-      name: 'Fetch user',
-      key: 'user:1'
-    }
-  );
-
-  const posts = await step.withTimeout(
-    () => fetchPosts(user.id),
-    { ms: 5000, name: 'Fetch posts' }
-  );
-
-  return { user, posts };
-});
-```
-
-### Stage 4 - Human-in-the-Loop & Resume
-
-Pause long-running workflows until an operator approves, then resume using persisted step results.
-
-```typescript
-import { createWorkflow, createResumeStateCollector } from 'awaitly/workflow';
-import {
-  createApprovalStep,
-  injectApproval,
-  isPendingApproval,
-} from 'awaitly/hitl';
-
-// Use collector to automatically capture state
-const collector = createResumeStateCollector();
-const requireApproval = createApprovalStep({
-  key: 'approval:deploy',
-  checkApproval: async () => ({ status: 'pending' }),
-});
-
-const gatedWorkflow = createWorkflow({ requireApproval }, {
-  onEvent: collector.handleEvent, // Automatically collects step results
-});
-
-const result = await gatedWorkflow(async (step) => step(requireApproval, { key: 'approval:deploy' }));
-
-if (!result.ok && isPendingApproval(result.error)) {
-  // Get collected state
-  const state = collector.getResumeState();
-  
-  // Later, when approval is granted, inject it and resume
-  const updatedState = injectApproval(state, {
-    stepKey: 'approval:deploy',
-    value: { approvedBy: 'ops' },
-  });
-
-  // Resume with approval injected
-  const resumed = createWorkflow({ requireApproval }, { resumeState: updatedState });
-  await resumed(async (step) => step(requireApproval, { key: 'approval:deploy' })); // Uses injected approval
-}
-```
-
-## Try It Yourself
-
-- Open the [TypeScript Playground](https://www.typescriptlang.org/play) and paste any snippet from the tutorial.
-- Prefer running locally? Save a file, run `npx tsx workflow-demo.ts`, and iterate with real dependencies.
-- For interactive debugging, add `console.log` inside `onEvent` callbacks to visualize timing immediately.
-
-## Key Concepts
-
-| Concept | What it does |
-|---------|--------------|
-| **Result** | `ok(value)` or `err(error)` - typed success/failure, no exceptions |
-| **Workflow** | Wraps your dependencies and tracks their error types automatically |
-| **step()** | Unwraps a Result, short-circuits on failure, enables caching/retries |
-| **step.try** | Catches throws and converts them to typed errors |
-| **step.fromResult** | Preserves rich error objects from other Result-returning code |
-| **Events** | `onEvent` streams everything - timing, retries, failures - for visualization or logging |
-| **Resume** | Save completed steps, pick up later (great for approvals or crashes) |
-| **UnexpectedError** | Safety net for throws outside your declared union; use `strict` mode to force explicit handling |
-
-## Recipes & Patterns
-
-### Core Recipes
-
-#### Basic Workflow
-
-```typescript
-const result = await loadUserData(async (step) => {
-  const user = await step(fetchUser('1'));
-  const posts = await step(fetchPosts(user.id));
-  return { user, posts };
-});
-```
-
-#### User Signup
-
-```typescript
-const validateEmail = async (email: string): AsyncResult<string, 'INVALID_EMAIL'> =>
-  email.includes('@') ? ok(email) : err('INVALID_EMAIL');
-
-const checkDuplicate = async (email: string): AsyncResult<void, 'EMAIL_EXISTS'> =>
-  email === 'taken@example.com' ? err('EMAIL_EXISTS') : ok(undefined);
-
-const createAccount = async (email: string): AsyncResult<{ id: string }, 'DB_ERROR'> =>
-  ok({ id: crypto.randomUUID() });
-
-const sendWelcome = async (userId: string): AsyncResult<void, 'EMAIL_FAILED'> => ok(undefined);
-
-const signUp = createWorkflow({ validateEmail, checkDuplicate, createAccount, sendWelcome });
-
-const result = await signUp(async (step) => {
-  const email = await step(validateEmail('user@example.com'));
-  await step(checkDuplicate(email));
-  const account = await step(createAccount(email));
-  await step(sendWelcome(account.id));
-  return account;
-});
-// result.error: 'INVALID_EMAIL' | 'EMAIL_EXISTS' | 'DB_ERROR' | 'EMAIL_FAILED' | UnexpectedError
-```
-
-#### Checkout Flow
-
-```typescript
-const authenticate = async (token: string): AsyncResult<{ userId: string }, 'UNAUTHORIZED'> =>
-  token === 'valid' ? ok({ userId: 'user-1' }) : err('UNAUTHORIZED');
-
-const fetchOrder = async (id: string): AsyncResult<{ total: number }, 'ORDER_NOT_FOUND'> =>
-  ok({ total: 99 });
-
-const chargeCard = async (amount: number): AsyncResult<{ txId: string }, 'PAYMENT_FAILED'> =>
-  ok({ txId: 'tx-123' });
-
-const checkout = createWorkflow({ authenticate, fetchOrder, chargeCard });
-
-const result = await checkout(async (step) => {
-  const auth = await step(authenticate(token));
-  const order = await step(fetchOrder(orderId));
-  const payment = await step(chargeCard(order.total));
-  return { userId: auth.userId, txId: payment.txId };
-});
-// result.error: 'UNAUTHORIZED' | 'ORDER_NOT_FOUND' | 'PAYMENT_FAILED' | UnexpectedError
-```
-
-#### Composing Workflows
-
-You can combine multiple workflows together. The error types automatically aggregate:
-
-```typescript
-// Validation workflow
-const validateEmail = async (email: string): AsyncResult<string, 'INVALID_EMAIL'> =>
-  email.includes('@') ? ok(email) : err('INVALID_EMAIL');
-
-const validatePassword = async (pwd: string): AsyncResult<string, 'WEAK_PASSWORD'> =>
-  pwd.length >= 8 ? ok(pwd) : err('WEAK_PASSWORD');
-
-const validationWorkflow = createWorkflow({ validateEmail, validatePassword });
-
-// Checkout workflow
-const checkoutWorkflow = createWorkflow({ authenticate, fetchOrder, chargeCard });
-
-// Composed workflow: validation + checkout
-// Include all dependencies from both workflows
-const validateAndCheckout = createWorkflow({
-  validateEmail,
-  validatePassword,
-  authenticate,
-  fetchOrder,
-  chargeCard,
-});
-
-const result = await validateAndCheckout(async (step) => {
-  // Validation steps
-  const email = await step(validateEmail('user@example.com'));
-  const password = await step(validatePassword('secret123'));
-  
-  // Checkout steps
-  const auth = await step(authenticate('valid'));
-  const order = await step(fetchOrder('order-1'));
-  const payment = await step(chargeCard(order.total));
-  
-  return { email, password, userId: auth.userId, txId: payment.txId };
-});
-// result.error: 'INVALID_EMAIL' | 'WEAK_PASSWORD' | 'UNAUTHORIZED' | 'ORDER_NOT_FOUND' | 'PAYMENT_FAILED' | UnexpectedError
-```
-
-### Common Patterns
-
-- **Validation & gating** - Run early workflows so later steps never execute for invalid data.
-
-  ```typescript
-  const validated = await step(() => validationWorkflow(async (inner) => inner(deps.validateEmail(email))));
-  ```
-
-- **API calls with typed errors** - Wrap fetch/axios via `step.try` and switch on the union later.
-
-  ```typescript
-  const payload = await step.try(() => fetch(url).then((r) => r.json()), { error: 'HTTP_FAILED' });
-  ```
-
-- **Wrapping Result-returning functions** - Use `step.fromResult` to preserve rich error types.
-
-  ```typescript
-  const response = await step.fromResult(
-    () => callProvider(input),
-    {
-      onError: (e) => ({
-        type: 'PROVIDER_FAILED' as const,
-        provider: e.provider,  // TypeScript knows e is ProviderError
-        code: e.code,
-      })
-    }
-  );
-  ```
-
-- **Retries, backoff, and timeouts** - Built into `step.retry()` and `step.withTimeout()`.
-
-  ```typescript
-  const data = await step.retry(
-    () => step.withTimeout(() => fetchData(), { ms: 2000 }),
-    { attempts: 3, backoff: 'exponential', retryOn: (error) => error !== 'FATAL' }
-  );
-  ```
-
-- **State save & resume** - Persist step completions and resume later.
-
-  ```typescript
-  import { createWorkflow, createResumeStateCollector } from 'awaitly/workflow';
-
-  // Collect state during execution
-  const collector = createResumeStateCollector();
-  const workflow = createWorkflow(deps, {
-    onEvent: collector.handleEvent, // Automatically collects step_complete events
-  });
-
-  await workflow(async (step) => {
-    const user = await step(() => fetchUser("1"), { key: "user:1" });
-    return user;
-  });
-
-  // Get collected state
-  const state = collector.getResumeState();
-
-  // Resume later
-  const resumed = createWorkflow(deps, { resumeState: state });
-  ```
-
-- **Human-in-the-loop approvals** - Pause a workflow until someone approves.
-
-  ```typescript
-  import { createApprovalStep, isPendingApproval, injectApproval } from 'awaitly/hitl';
-
-  const requireApproval = createApprovalStep({ key: 'approval:deploy', checkApproval: async () => {/* ... */} });
-  const result = await workflow(async (step) => step(requireApproval, { key: 'approval:deploy' }));
-
-  if (!result.ok && isPendingApproval(result.error)) {
-    // notify operators, later call injectApproval(savedState, { stepKey, value })
-  }
-  ```
-
-- **Caching & deduplication** - Give steps names + keys.
-
-  ```typescript
-  const user = await step(() => fetchUser(id), { name: 'Fetch user', key: `user:${id}` });
-  ```
-
-- **Branching logic** - It's just JavaScript - use normal `if`/`switch`.
-
-  ```typescript
-  const user = await step(fetchUser(id));
-
-  if (user.role === 'admin') {
-    return await step(fetchAdminDashboard(user.id));
-  }
-
-  if (user.subscription === 'free') {
-    return await step(fetchFreeTierData(user.id));
-  }
-
-  return await step(fetchPremiumData(user.id));
-  ```
-
-- **Parallel operations** - Use helpers when you truly need concurrency.
-
-  ```typescript
-  import { allAsync, partition, map } from 'awaitly';
-
-  const result = await allAsync([
-    fetchUser('1'),
-    fetchPosts('1'),
-  ]);
-  const data = map(result, ([user, posts]) => ({ user, posts }));
-  ```
+## When to use awaitly
 
-## Real-World Example: Safe Payment Retries with Persistence
+**Use it when:**
+- You want Result types with async/await (not method chains)
+- You need automatic error inference from dependencies
+- You're building workflows that benefit from caching, retries, or resume
 
-The scariest failure mode in payments: **charge succeeded, but persistence failed**. If you retry naively, you charge the customer twice.
-
-Step keys + persistence solve this. Save state to a database, and if the workflow crashes, resume from the last successful step:
-
-```typescript
-import { createWorkflow, createResumeStateCollector } from 'awaitly/workflow';
-import { stringifyState, parseState } from 'awaitly/persistence';
-
-const processPayment = createWorkflow({ validateCard, chargeProvider, persistResult });
-
-// Collect state for persistence
-const collector = createResumeStateCollector();
-const workflow = createWorkflow(
-  { validateCard, chargeProvider, persistResult },
-  { onEvent: collector.handleEvent }
-);
-
-const result = await workflow(async (step) => {
-  const card = await step(() => validateCard(input), { key: 'validate' });
-
-  // This is the dangerous step. Once it succeeds, never repeat it:
-  const charge = await step(() => chargeProvider(card), {
-    key: `charge:${input.idempotencyKey}`,
-  });
-
-  // If THIS fails (DB down), save state and rerun later.
-  // The charge step is cached - it won't execute again.
-  await step(() => persistResult(charge), { key: `persist:${charge.id}` });
-
-  return { paymentId: charge.id };
-});
-
-// Save state after each run (or on crash)
-if (result.ok) {
-  const state = collector.getResumeState();
-  const json = stringifyState(state, { orderId: input.orderId });
-  await db.workflowStates.upsert({
-    where: { idempotencyKey: input.idempotencyKey },
-    update: { state: json, updatedAt: new Date() },
-    create: { idempotencyKey: input.idempotencyKey, state: json },
-  });
-}
-```
-
-**Crash recovery:** If the workflow crashes after charging but before persisting:
-
-```typescript
-// On restart, load saved state
-const saved = await db.workflowStates.findUnique({
-  where: { idempotencyKey: input.idempotencyKey },
-});
-
-if (saved) {
-  const savedState = parseState(saved.state);
-  const workflow = createWorkflow(
-    { validateCard, chargeProvider, persistResult },
-    { resumeState: savedState }
-  );
-
-  // Resume - charge step uses cached result, no double-billing!
-  const result = await workflow(async (step) => {
-    const card = await step(() => validateCard(input), { key: 'validate' }); // Cache hit
-    const charge = await step(() => chargeProvider(card), {
-      key: `charge:${input.idempotencyKey}`,
-    }); // Cache hit - returns previous charge result
-    await step(() => persistResult(charge), { key: `persist:${charge.id}` }); // Executes fresh
-    return { paymentId: charge.id };
-  });
-}
-```
-
-Crash after charging but before persisting? Resume the workflow. The charge step returns its cached result. No double-billing.
-
-## Is This Library Right for You?
-
-```mermaid
-flowchart TD
-    Start([Need typed errors?]) --> Simple{Simple use case?}
-
-    Simple -->|Yes| TryCatch["try/catch is fine"]
-    Simple -->|No| WantAsync{Want async/await syntax?}
-
-    WantAsync -->|Yes| NeedOrchestration{Need retries/caching/resume?}
-    WantAsync -->|No| Neverthrow["Consider neverthrow"]
-
-    NeedOrchestration -->|Yes| Workflow["✓ awaitly"]
-    NeedOrchestration -->|No| Either["Either works - awaitly adds room to grow"]
-
-    style Workflow fill:#E8F5E9
-```
-
-**Choose this library when:**
-
-- You want Result types with familiar async/await syntax
-- You need automatic error type inference
-- You're building workflows that benefit from step caching or resume
-- You want type-safe error handling without Effect's learning curve
-
-## How It Compares
-
-**`try/catch` everywhere** - You lose error types. Every catch block sees `unknown`. Retries? Manual. Timeouts? Manual. Observability? Hope you remembered to add logging.
-
-**Result-only libraries** (fp-ts, neverthrow) - Great for typed errors in pure functions. But when you need retries, caching, timeouts, or human approvals, you're back to wiring it yourself.
-
-**This library** - Typed errors *plus* the orchestration primitives. Error inference flows from your dependencies. Retries, timeouts, caching, resume, and visualization are built in - use them when you need them.
+**Skip it when:**
+- You prefer functional chaining (consider neverthrow)
 
 ### vs neverthrow
 
-| Aspect | neverthrow | awaitly |
-|--------|-----------|---------|
-| **Chaining style** | `.andThen()` method chains (nest with 3+ ops) | `step()` with async/await (stays flat) |
-| **Error inference** | Manual: `type Errors = 'A' \| 'B' \| 'C'` | Automatic from `createWorkflow({ deps })` |
-| **Result access** | `.isOk()`, `.isErr()` methods | `.ok` boolean property |
-| **Wrapping throws** | `ResultAsync.fromPromise(p, mapErr)` | `step.try(fn, { error })` or wrap in AsyncResult |
-| **Parallel ops** | `ResultAsync.combine([...])` | `allAsync([...])` |
-| **Retries** | DIY with recursive `.orElse()` | Built-in `step.retry({ attempts, backoff })` |
-| **Timeouts** | DIY with `Promise.race()` | Built-in `step.withTimeout({ ms })` |
-| **Caching** | DIY | Built-in with `{ key: 'cache-key' }` |
-| **Resume/persist** | DIY | Built-in with `resumeState` + `isStepComplete()` |
-| **Events** | DIY | 15+ event types via `onEvent` |
-
-**When to use neverthrow:** You want typed Results with minimal bundle size and prefer functional chaining.
-
-**When to use awaitly:** You want typed Results with async/await syntax, automatic error inference, and built-in reliability primitives.
-
-See the [comparison table above](#vs-neverthrow) for pattern-by-pattern equivalents.
-
-### Where awaitly shines
-
-**Complex checkout flows:**
-```typescript
-// 5 different error types, all automatically inferred
-const checkout = createWorkflow({ validateCart, checkInventory, getPricing, processPayment, createOrder });
-
-const result = await checkout(async (step) => {
-  const cart = await step(() => validateCart(input));
+| awaitly | neverthrow |
+|---------|-----------|
+| async/await with `step()` | `.andThen()` method chains |
+| Automatic error inference | Manual error unions |
+| Built-in retries, timeouts, caching | DIY |
 
-  // Parallel execution stays clean
-  const [inventory, pricing] = await step(() => allAsync([
-    checkInventory(cart.items),
-    getPricing(cart.items)
-  ]));
-
-  const payment = await step(() => processPayment(cart, pricing.total));
-  return await step(() => createOrder(cart, payment));
-});
-// TypeScript knows: Result<Order, ValidationError | InventoryError | PricingError | PaymentError | OrderError>
-```
-
-**Branching logic with native control flow:**
-```typescript
-// Just JavaScript - no functional gymnastics
-const tenant = await step(() => fetchTenant(id));
-
-if (tenant.plan === 'free') {
-  return await step(() => calculateFreeUsage(tenant));
-}
-
-// Variables from earlier steps are in scope - no closure drilling
-const [users, resources] = await step(() => allAsync([fetchUsers(), fetchResources()]));
-
-switch (tenant.plan) {
-  case 'pro': await step(() => sendProNotification(tenant)); break;
-  case 'enterprise': await step(() => sendEnterpriseNotification(tenant)); break;
-}
-```
-
-**Data pipelines with caching and resume:**
-```typescript
-const pipeline = createWorkflow(deps, { cache: new Map() });
-
-const result = await pipeline(async (step) => {
-  // `key` enables caching and resume from last successful step
-  const user = await step(() => fetchUser(id), { key: 'user' });
-  const posts = await step(() => fetchPosts(user.id), { key: 'posts' });
-  const comments = await step(() => fetchComments(posts), { key: 'comments' });
-  return { user, posts, comments };
-}, { resumeState: savedState });
-```
+**neverthrow:** Minimal bundle, functional chaining.
+**awaitly:** async/await syntax + orchestration built in.
 
 ## Quick Reference
 
-### Workflow Builders
-
 | API | Description |
 |-----|-------------|
-| `createWorkflow(deps, opts?)` | Reusable workflow with automatic error unions, caching, resume, events, strict mode. |
-| `run(executor, opts?)` | One-off workflow; you supply `Output` and `Error` generics manually. |
-| `createSagaWorkflow(deps, opts?)` | Workflow with automatic compensation handlers. |
-| `createWorkflowHarness(deps, opts?)` | Testing harness with deterministic step control. |
+| `createWorkflow(deps)` | Recommended. Auto-infers errors from deps. |
+| `step(() => deps.fn())` | Run a step, unwrap result. |
+| `step.retry(fn, opts)` | Retry with backoff. |
+| `step.withTimeout(fn, { ms })` | Timeout protection. |
+| `ok(value)` / `err(error)` | Construct Results. |
 
-### Step Helpers
+See [full API reference](https://jagreehal.github.io/awaitly/reference/api/) for `run()`, `step.try`, `step.fromResult`, combinators, circuit breakers, and more.
 
-| API | Description |
-|-----|-------------|
-| `step(op, meta?)` | Execute a dependency or thunk. Supports `{ key, name, retry, timeout }`. |
-| `step.try(fn, { error })` | Catch throws/rejections and emit a typed error. |
-| `step.fromResult(fn, { onError })` | Preserve rich error objects from other Result-returning code. |
-| `step.retry(fn, opts)` | Retries with fixed/linear/exponential backoff, jitter, and predicates. |
-| `step.withTimeout(fn, { ms, signal?, name? })` | Auto-timeout operations and optionally pass AbortSignal. |
+### run()
 
-### Result & Utility Helpers
+Most users do NOT need `run()`.
 
-| API | Description |
-|-----|-------------|
-| `ok(value)` / `err(error)` | Construct Results. |
-| `map`, `mapError`, `bimap` | Transform values or errors. |
-| `andThen`, `match` | Chain or pattern-match Results. |
-| `orElse`, `recover` | Error recovery and fallback patterns. |
-| `allAsync`, `partition` | Batch operations where the first error wins or you collect everything. |
-| `isStepTimeoutError(error)` | Runtime guard for timeout failures. |
-| `getStepTimeoutMeta(error)` | Inspect timeout metadata (attempt, ms, name). |
-| `createCircuitBreaker(name, config)` | Guard dependencies with open/close behavior. |
-| `createRateLimiter(name, config)` | Ensure steps respect throughput policies. |
-| `createWebhookHandler(workflow, fn, config)` | Turn workflows into HTTP handlers quickly. |
-
-### Choosing Between run() and createWorkflow()
-
-| Use Case | Recommendation |
-|----------|----------------|
-| Dependencies known at compile time | `createWorkflow()` |
-| Dependencies passed as parameters | `run()` |
-| Need step caching or resume | `createWorkflow()` |
-| One-off workflow invocation | `run()` |
-| Want automatic error inference | `createWorkflow()` |
-| Error types known upfront | `run()` |
-
-**`run()`** - Best for dynamic dependencies, testing, or lightweight workflows where you know the error types:
+Use it only when:
+- dependencies are passed dynamically as parameters
+- you want explicit control over the error union
+- you're building abstractions on top of awaitly
 
 ```typescript
-import { run } from 'awaitly';
+import { run } from "awaitly";
 
-const result = await run<Output, 'NOT_FOUND' | 'FETCH_ERROR'>(
+const result = await run<Output, "NOT_FOUND" | "FETCH_ERROR">(
   async (step) => {
-    const user = await step(fetchUser(userId)); // userId from parameter
+    const user = await step(() => fetchUser(userId)); // thunk for consistency
     return user;
   },
-  { onError: (e) => console.log('Failed:', e) }
+  { onError: (e) => console.log("Failed:", e) }
 );
 ```
 
-**`createWorkflow()`** - Best for reusable workflows with static dependencies. Provides automatic error type inference:
+For most cases, stick with `createWorkflow()` which infers error types automatically.
 
-```typescript
-const loadUser = createWorkflow({ fetchUser, fetchPosts });
-// Error type computed automatically from deps
-```
+### Imports
 
-### Import paths
+Most apps only need:
 
 ```typescript
-// Main entry - result primitives + run() for composition
-import { ok, err, map, all, run } from 'awaitly';
-
-// Core layer - Result primitives + tagged errors + pattern matching
-import { ok, err, map, TaggedError, Match } from 'awaitly/core';
-
-// Workflow layer - orchestration, Duration, step collector
-import { createWorkflow, Duration, createResumeStateCollector, isStepComplete } from 'awaitly/workflow';
-
-// Visualization tools
-import { createVisualizer } from 'awaitly/visualize';
-
-// Batch processing
-import { processInBatches } from 'awaitly/batch';
-
-// Resource management
-import { createResourceScope, withScope } from 'awaitly/resource';
-
-// Retry strategies
-import { Schedule, Duration } from 'awaitly/retry';
-
-// Reliability patterns (umbrella)
-import { createCircuitBreaker, createRateLimiter, createSagaWorkflow } from 'awaitly/reliability';
-
-// Granular reliability imports
-import { createCircuitBreaker } from 'awaitly/circuit-breaker';
-import { createRateLimiter } from 'awaitly/ratelimit';
-import { createSagaWorkflow, runSaga } from 'awaitly/saga';
-import { servicePolicies, withPolicy } from 'awaitly/policies';
-
-// Persistence and versioning
-import { createStatePersistence, createFileCache, migrateState } from 'awaitly/persistence';
-
-// Human-in-the-loop orchestration
-import { createHITLOrchestrator, createApprovalWebhookHandler } from 'awaitly/hitl';
-
-// HTTP webhook handlers
-import { createWebhookHandler, createExpressHandler } from 'awaitly/webhook';
-
-// OpenTelemetry integration
-import { createAutotelAdapter, withAutotelTracing } from 'awaitly/otel';
-
-// Development tools
-import { createDevtools, quickVisualize } from 'awaitly/devtools';
-
-// Testing harness
-import { createWorkflowHarness, createMockFn } from 'awaitly/testing';
-
-// Utility modules (optional granular imports)
-import { when, unless } from 'awaitly/conditional';
-import { Duration, millis, seconds } from 'awaitly/duration';
-import { Match, matchValue } from 'awaitly/match';
-import { TaggedError } from 'awaitly/tagged-error';
+import { ok, err, type AsyncResult } from "awaitly";
+import { createWorkflow, UNEXPECTED_ERROR } from "awaitly/workflow";
 ```
 
+Everything else is optional and documented in the [guides](https://jagreehal.github.io/awaitly/).
+
 ## Common Pitfalls
 
-**Use thunks for caching.** `step(fetchUser('1'))` executes immediately. Use `step(() => fetchUser('1'), { key })` for caching to work.
+**Use thunks for caching.** `step(deps.fetchUser('1'))` executes immediately. Use `step(() => deps.fetchUser('1'), { key })` for caching to work.
 
 **Keys must be stable.** Use `user:${id}`, not `user:${Date.now()}`.
 
@@ -1213,68 +719,32 @@ import { TaggedError } from 'awaitly/tagged-error';
 
 ## Troubleshooting & FAQ
 
-- **Why is `UnexpectedError` in my union?** Add `{ strict: true, catchUnexpected: () => 'UNEXPECTED' }` when creating the workflow to map unknown errors explicitly.
+- **Why is `UnexpectedError` in my result?** It's a safety net for unexpected throws. Map it to HTTP 500 at the boundary.
 - **How do I inspect what ran?** Pass `onEvent` and log `step_*` / `workflow_*` events or feed them into `createVisualizer()` for diagrams.
 - **A workflow is stuck waiting for approval. Now what?** Use `isPendingApproval(error)` to detect the state, notify operators, then call `injectApproval(state, { stepKey, value })` to resume.
 - **Cache is not used between runs.** Supply a stable `{ key }` per step and provide a cache/resume adapter in `createWorkflow(deps, { cache })`.
 - **I only need a single run with dynamic dependencies.** Use `run()` instead of `createWorkflow()` and pass dependencies directly to the executor.
 
-## Visualizing Workflows
-
-Hook into the event stream and render diagrams for docs, PRs, or dashboards:
+## Next Steps
 
-```typescript
-import { createVisualizer } from 'awaitly/visualize';
+**If you only read one guide next:** [Retries & Timeouts](https://jagreehal.github.io/awaitly/guides/retries-timeouts/) - most apps need reliability.
 
-const viz = createVisualizer({ workflowName: 'user-posts-flow' });
-const workflow = createWorkflow({ fetchUser, fetchPosts }, {
-  onEvent: viz.handleEvent,
-});
-
-await workflow(async (step) => {
-  const user = await step(() => fetchUser('1'), { name: 'Fetch user' });
-  const posts = await step(() => fetchPosts(user.id), { name: 'Fetch posts' });
-  return { user, posts };
-});
-
-// ASCII output for terminal/CLI
-console.log(viz.render());
-
-// Mermaid diagram for Markdown/docs
-console.log(viz.renderAs('mermaid'));
+**Other guides:**
+- [Persistence](https://jagreehal.github.io/awaitly/guides/persistence/) - save & resume workflows
+- [Testing](https://jagreehal.github.io/awaitly/guides/testing/) - deterministic harness
+- [Full API Reference](https://jagreehal.github.io/awaitly/reference/api/)
 
-// JSON IR for programmatic access
-console.log(viz.renderAs('json'));
-```
-
-Mermaid output drops directly into Markdown for documentation. The ASCII block is handy for CLI screenshots or incident runbooks.
-
-**For post-execution visualization**, collect events and visualize later:
-
-```typescript
-import { createEventCollector } from 'awaitly/visualize';
-
-const collector = createEventCollector({ workflowName: 'my-workflow' });
-const workflow = createWorkflow({ fetchUser, fetchPosts }, {
-  onEvent: collector.handleEvent,
-});
-
-await workflow(async (step) => { /* ... */ });
-
-// Visualize collected events
-console.log(collector.visualize());
-console.log(collector.visualizeAs('mermaid'));
-```
-
-## Keep Going
-
-**Already using neverthrow?** See the [comparison table above](#vs-neverthrow) for pattern-by-pattern equivalents - you'll feel at home quickly.
+---
 
-**Ready for production features?** The [advanced guides](https://jagreehal.github.io/awaitly/advanced/saga-compensation/) cover sagas, circuit breakers, rate limiting, persistence adapters, and HITL orchestration.
+## You're done
 
-**Need the full API?** [API reference](https://jagreehal.github.io/awaitly/reference/api/) has everything in one place.
+If you understand:
+- `ok` / `err`
+- `createWorkflow`
+- `step()`
+- mapping Result at the boundary
 
-**Explore all guides:** [Documentation site](https://jagreehal.github.io/awaitly/) has the complete set of guides, tutorials, and reference material.
+You already know ~80% of awaitly.
 
 ---