@wooksjs/event-wf 0.7.7 → 0.7.9

package/dist/index.mjs

@@ -1,4 +1,7 @@
-import { createEventContext, current, defineEventKind, key, slot, useLogger, useRouteParams } from "@wooksjs/event-core";
+import { createEventContext, current, defineEventKind, defineWook, key, slot, useLogger, useRouteParams } from "@wooksjs/event-core";
+import { useCookies, useResponse, useUrlParams } from "@wooksjs/event-http";
+import { useBody } from "@wooksjs/http-body";
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from "node:crypto";
 import { StepRetriableError, Workflow, createStep } from "@prostojs/wf";
 import { WooksAdapterBase } from "wooks";
 
@@ -23,17 +26,14 @@ const resumeKey = key("wf.resume");
 * const stepInput = input<MyInput>()
 * ```
 */
-function useWfState() {
-	const c = current();
-	return {
-		ctx: () => c.get(wfKind.keys.inputContext),
-		input: () => c.get(wfKind.keys.input),
-		schemaId: c.get(wfKind.keys.schemaId),
-		stepId: () => c.get(wfKind.keys.stepId),
-		indexes: () => c.get(wfKind.keys.indexes),
-		resume: c.get(resumeKey)
-	};
-}
+const useWfState = defineWook((c) => ({
+	ctx: () => c.get(wfKind.keys.inputContext),
+	input: () => c.get(wfKind.keys.input),
+	schemaId: c.get(wfKind.keys.schemaId),
+	stepId: () => c.get(wfKind.keys.stepId),
+	indexes: () => c.get(wfKind.keys.indexes),
+	resume: c.get(resumeKey)
+}));
 
 //#endregion
 //#region packages/event-wf/src/event-wf.ts
@@ -52,6 +52,446 @@ function resumeWfContext(options, seeds, fn) {
 	});
 }
 
+//#endregion
+//#region packages/event-wf/src/outlets/outlet-context.ts
+/** Registered outlet handlers, keyed by name */
+const outletsRegistryKey = key("wf.outlets.registry");
+/** Active state strategy for current request */
+const stateStrategyKey = key("wf.outlets.stateStrategy");
+/** Finished response set by workflow steps */
+const wfFinishedKey = key("wf.outlets.finished");
+
+//#endregion
+//#region packages/event-wf/src/outlets/use-wf-outlet.ts
+/**
+* Composable for accessing outlet infrastructure from within workflow steps.
+*
+* Most steps don't need this — they just return `outletHttp(form)` or
+* `outletEmail(to, template)`. This composable is for advanced cases
+* where steps need to inspect or modify outlet state directly.
+*/
+const useWfOutlet = defineWook((ctx) => ({
+	getStateStrategy: () => ctx.get(stateStrategyKey),
+	getOutlets: () => ctx.get(outletsRegistryKey),
+	getOutlet: (name) => ctx.get(outletsRegistryKey)?.get(name) ?? null
+}));
+
+//#endregion
+//#region packages/event-wf/src/outlets/use-wf-finished.ts
+/**
+* Composable to set the completion response for a finished workflow.
+*
+* @example
+* ```ts
+* // Redirect after login
+* useWfFinished().set({ type: 'redirect', value: '/dashboard' })
+*
+* // Return data
+* useWfFinished().set({ type: 'data', value: { success: true } })
+* ```
+*/
+const useWfFinished = defineWook((ctx) => ({
+	set: (response) => ctx.set(wfFinishedKey, response),
+	get: () => ctx.has(wfFinishedKey) ? ctx.get(wfFinishedKey) : void 0
+}));
+
+//#endregion
+//#region packages/event-wf/src/outlets/trigger.ts
+const DEFAULT_CONSUME_TOKEN = { email: true };
+/**
+* Handle an HTTP request that starts or resumes a workflow.
+*
+* Reads wfs (state token) and wfid (workflow ID) from request body, query params,
+* or cookies — configurable via `config.token`. On workflow pause, persists state
+* and dispatches to the named outlet. On finish, returns the finished response.
+*
+* @example
+* ```ts
+* // In a wooks HTTP handler:
+* app.post('/workflow', () => handleWfOutletRequest(config, deps))
+*
+* // Better — use createOutletHandler():
+* const handle = createOutletHandler(wfApp)
+* app.post('/workflow', () => handle(config))
+* ```
+*/
+async function handleWfOutletRequest(config, deps) {
+	const tok = config.token ?? {};
+	const tokenName = tok.name ?? "wfs";
+	const tokenRead = tok.read ?? [
+		"body",
+		"query",
+		"cookie"
+	];
+	const tokenWrite = tok.write ?? "body";
+	const wfidName = config.wfidName ?? "wfid";
+	const ctx = current();
+	const registry = new Map(config.outlets.map((o) => [o.name, o]));
+	ctx.set(outletsRegistryKey, registry);
+	ctx.set(wfFinishedKey, void 0);
+	const { parseBody } = useBody();
+	const { params } = useUrlParams();
+	const { getCookie } = useCookies();
+	const response = useResponse();
+	const body = await parseBody().catch(() => void 0);
+	const queryParams = params();
+	let token;
+	for (const source of tokenRead) {
+		if (source === "body") token = body?.[tokenName];
+		else if (source === "query") token = queryParams.get(tokenName) ?? void 0;
+		else if (source === "cookie") token = getCookie(tokenName) ?? void 0;
+		if (token) break;
+	}
+	const wfid = body?.[wfidName] ?? queryParams.get(wfidName) ?? void 0;
+	const input = body?.input;
+	const resolveStrategy = (id) => typeof config.state === "function" ? config.state(id) : config.state;
+	const shouldConsume = (outletName) => {
+		if (typeof tok.consume === "boolean") return tok.consume;
+		return (tok.consume ?? DEFAULT_CONSUME_TOKEN)[outletName] ?? false;
+	};
+	let output;
+	if (token) {
+		const strategy = resolveStrategy(wfid ?? "");
+		ctx.set(stateStrategyKey, strategy);
+		const state = await strategy.retrieve(token);
+		if (!state) return {
+			error: "Invalid or expired workflow state",
+			status: 400
+		};
+		if (state.schemaId !== (wfid ?? "")) {
+			const realStrategy = resolveStrategy(state.schemaId);
+			ctx.set(stateStrategyKey, realStrategy);
+		}
+		const outletName = state.meta?.outlet;
+		if (outletName && shouldConsume(outletName)) await strategy.consume(token);
+		output = await deps.resume(state, {
+			input,
+			eventContext: ctx
+		});
+	} else if (wfid) {
+		if (config.allow?.length && !config.allow.includes(wfid)) return {
+			error: `Workflow '${wfid}' is not allowed`,
+			status: 403
+		};
+		if (config.block?.includes(wfid)) return {
+			error: `Workflow '${wfid}' is blocked`,
+			status: 403
+		};
+		const strategy = resolveStrategy(wfid);
+		ctx.set(stateStrategyKey, strategy);
+		const initialContext = config.initialContext ? config.initialContext(body, wfid) : {};
+		output = await deps.start(wfid, initialContext, {
+			input,
+			eventContext: ctx
+		});
+	} else return {
+		error: "Missing wfs (state token) or wfid (workflow ID)",
+		status: 400
+	};
+	if (output.finished) {
+		if (config.onFinished) return config.onFinished({
+			context: output.state.context,
+			schemaId: output.state.schemaId
+		});
+		const finished = ctx.get(wfFinishedKey);
+		if (finished?.cookies) for (const [name, cookie] of Object.entries(finished.cookies)) response.setCookie(name, cookie.value, cookie.options);
+		if (finished?.type === "redirect") {
+			response.setHeader("location", finished.value);
+			return { status: finished.status ?? 302 };
+		}
+		if (finished) return finished.value;
+		return { finished: true };
+	}
+	if (output.inputRequired) {
+		const outletReq = output.inputRequired;
+		const outletHandler = registry.get(outletReq.outlet);
+		if (!outletHandler) return {
+			error: `Unknown outlet: '${outletReq.outlet}'`,
+			status: 500
+		};
+		const strategy = ctx.get(stateStrategyKey);
+		const stateWithMeta = {
+			...output.state,
+			meta: { outlet: outletReq.outlet }
+		};
+		const newToken = await strategy.persist(stateWithMeta, output.expires ? { ttl: output.expires - Date.now() } : void 0);
+		if (tokenWrite === "cookie") response.setCookie(tokenName, newToken, {
+			httpOnly: true,
+			sameSite: "Strict",
+			path: "/"
+		});
+		const result = await outletHandler.deliver(outletReq, newToken);
+		if (tokenWrite === "body" && result?.response && typeof result.response === "object") return {
+			...result.response,
+			[tokenName]: newToken
+		};
+		return result?.response ?? { waiting: true };
+	}
+	if (output.error) return {
+		error: output.error.message,
+		errorList: output.errorList
+	};
+	return { error: "Unexpected workflow state" };
+}
+
+//#endregion
+//#region packages/event-wf/src/outlets/create-outlet.ts
+/**
+* Creates an HTTP outlet that passes through the outlet payload as
+* the HTTP response body. This is the most common outlet — it returns
+* forms, prompts, or data to the client.
+*
+* @example
+* ```ts
+* const httpOutlet = createHttpOutlet()
+* // Step does: return outletHttp({ fields: ['email', 'password'] })
+* // Client receives: { fields: ['email', 'password'] }
+* ```
+*/
+function createHttpOutlet(opts) {
+	return {
+		name: "http",
+		async deliver(request, _token) {
+			const body = opts?.transform ? opts.transform(request.payload, request.context) : typeof request.payload === "object" && request.payload !== null ? {
+				...request.payload,
+				...request.context
+			} : request.payload;
+			return { response: body };
+		}
+	};
+}
+/**
+* Creates an email outlet that delegates to a user-provided send function.
+* The send function receives the target, template, context, and the state
+* token (for embedding in magic links / verification URLs).
+*
+* @example
+* ```ts
+* const emailOutlet = createEmailOutlet(async (opts) => {
+*   await mailer.send({
+*     to: opts.target,
+*     template: opts.template,
+*     data: { ...opts.context, verifyUrl: `/verify?wfs=${opts.token}` },
+*   })
+* })
+* ```
+*/
+function createEmailOutlet(send) {
+	return {
+		name: "email",
+		async deliver(request, token) {
+			await send({
+				target: request.target ?? "",
+				template: request.template ?? "",
+				context: request.context ?? {},
+				token
+			});
+			return { response: {
+				sent: true,
+				outlet: "email"
+			} };
+		}
+	};
+}
+
+//#endregion
+//#region packages/event-wf/src/outlets/create-handler.ts
+/**
+* Creates a pre-wired outlet handler from a workflow app instance.
+* Eliminates the need to manually construct `WfOutletTriggerDeps`.
+*
+* Accepts any object with `start` and `resume` methods (WooksWf, MoostWf, etc.).
+*
+* @example
+* ```ts
+* const handle = createOutletHandler(wfApp)
+* httpApp.post('/workflow', () => handle(config))
+* ```
+*/
+function createOutletHandler(wfApp) {
+	return (config) => handleWfOutletRequest(config, {
+		start: (schemaId, context, opts) => wfApp.start(schemaId, context, opts),
+		resume: (state, opts) => wfApp.resume(state, opts)
+	});
+}
+
+//#endregion
+//#region node_modules/.pnpm/@prostojs+wf@0.1.1/node_modules/@prostojs/wf/dist/outlets/index.mjs
+/**
+* Generic outlet request. Use for custom outlets.
+*
+* @example
+* return outlet('pending-task', {
+*   payload: ApprovalForm,
+*   target: managerId,
+*   context: { orderId, amount },
+* })
+*/
+function outlet(name, data) {
+	return { inputRequired: {
+		outlet: name,
+		...data
+	} };
+}
+/**
+* Pause for HTTP form input. The outlet returns the payload (form definition)
+* and state token in the HTTP response.
+*
+* @example
+* return outletHttp(LoginForm)
+* return outletHttp(LoginForm, { error: 'Invalid credentials' })
+*/
+function outletHttp(payload, context) {
+	return outlet("http", {
+		payload,
+		context
+	});
+}
+/**
+* Pause and send email with a magic link containing the state token.
+*
+* @example
+* return outletEmail('user@test.com', 'invite', { name: 'Alice' })
+*/
+function outletEmail(target, template, context) {
+	return outlet("email", {
+		target,
+		template,
+		context
+	});
+}
+/**
+* Self-contained AES-256-GCM encrypted state strategy.
+*
+* Workflow state is encrypted into a base64url token that travels with the
+* transport (cookie, URL param, hidden field). No server-side storage needed.
+*
+* Token format: `base64url(iv[12] + authTag[16] + ciphertext)`
+*
+* @example
+* const strategy = new EncapsulatedStateStrategy({
+*     secret: crypto.randomBytes(32),
+*     defaultTtl: 3600_000, // 1 hour
+* });
+* const token = await strategy.persist(state);
+* const recovered = await strategy.retrieve(token);
+*/
+var EncapsulatedStateStrategy = class {
+	/** @throws if secret is not exactly 32 bytes */
+	constructor(config) {
+		this.config = config;
+		this.key = typeof config.secret === "string" ? Buffer.from(config.secret, "hex") : config.secret;
+		if (this.key.length !== 32) throw new Error("EncapsulatedStateStrategy: secret must be exactly 32 bytes");
+	}
+	/**
+	* Encrypt workflow state into a self-contained token.
+	* @param state — workflow state to persist
+	* @param options.ttl — time-to-live in ms (overrides defaultTtl)
+	* @returns base64url-encoded encrypted token
+	*/
+	async persist(state, options) {
+		const ttl = options?.ttl ?? this.config.defaultTtl ?? 0;
+		const exp = ttl > 0 ? Date.now() + ttl : 0;
+		const payload = JSON.stringify({
+			s: state,
+			e: exp
+		});
+		const iv = randomBytes(12);
+		const cipher = createCipheriv("aes-256-gcm", this.key, iv);
+		const encrypted = Buffer.concat([cipher.update(payload, "utf8"), cipher.final()]);
+		const tag = cipher.getAuthTag();
+		return Buffer.concat([
+			iv,
+			tag,
+			encrypted
+		]).toString("base64url");
+	}
+	/** Decrypt and return workflow state. Returns null if token is invalid, expired, or tampered. */
+	async retrieve(token) {
+		return this.decrypt(token);
+	}
+	/** Same as retrieve (stateless — cannot truly invalidate a token). */
+	async consume(token) {
+		return this.decrypt(token);
+	}
+	decrypt(token) {
+		try {
+			const buf = Buffer.from(token, "base64url");
+			if (buf.length < 28) return null;
+			const iv = buf.subarray(0, 12);
+			const tag = buf.subarray(12, 28);
+			const ciphertext = buf.subarray(28);
+			const decipher = createDecipheriv("aes-256-gcm", this.key, iv);
+			decipher.setAuthTag(tag);
+			const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+			const { s: state, e: exp } = JSON.parse(decrypted.toString("utf8"));
+			if (exp > 0 && Date.now() > exp) return null;
+			return state;
+		} catch {
+			return null;
+		}
+	}
+};
+var HandleStateStrategy = class {
+	constructor(config) {
+		this.config = config;
+	}
+	async persist(state, options) {
+		const handle = (this.config.generateHandle ?? randomUUID)();
+		const ttl = options?.ttl ?? this.config.defaultTtl ?? 0;
+		const expiresAt = ttl > 0 ? Date.now() + ttl : void 0;
+		await this.config.store.set(handle, state, expiresAt);
+		return handle;
+	}
+	async retrieve(token) {
+		return (await this.config.store.get(token))?.state ?? null;
+	}
+	async consume(token) {
+		return (await this.config.store.getAndDelete(token))?.state ?? null;
+	}
+};
+/**
+* In-memory state store for development and testing.
+* State is lost on process restart.
+*/
+var WfStateStoreMemory = class {
+	constructor() {
+		this.store = /* @__PURE__ */ new Map();
+	}
+	async set(handle, state, expiresAt) {
+		this.store.set(handle, {
+			state,
+			expiresAt
+		});
+	}
+	async get(handle) {
+		const entry = this.store.get(handle);
+		if (!entry) return null;
+		if (entry.expiresAt && Date.now() > entry.expiresAt) {
+			this.store.delete(handle);
+			return null;
+		}
+		return entry;
+	}
+	async delete(handle) {
+		this.store.delete(handle);
+	}
+	async getAndDelete(handle) {
+		const entry = await this.get(handle);
+		if (entry) this.store.delete(handle);
+		return entry;
+	}
+	async cleanup() {
+		const now = Date.now();
+		let count = 0;
+		for (const [handle, entry] of this.store) if (entry.expiresAt && now > entry.expiresAt) {
+			this.store.delete(handle);
+			count++;
+		}
+		return count;
+	}
+};
+
 //#endregion
 //#region packages/event-wf/src/workflow.ts
 /** Workflow engine that resolves steps via Wooks router lookup. */
@@ -244,4 +684,4 @@ function createWfApp(opts, wooks) {
 }
 
 //#endregion
-export { StepRetriableError, WooksWf, createWfApp, createWfContext, resumeKey, resumeWfContext, useLogger, useRouteParams, useWfState, wfKind, wfShortcuts };
+export { EncapsulatedStateStrategy, HandleStateStrategy, StepRetriableError, WfStateStoreMemory, WooksWf, createEmailOutlet, createHttpOutlet, createOutletHandler, createWfApp, createWfContext, handleWfOutletRequest, outlet, outletEmail, outletHttp, resumeKey, resumeWfContext, useLogger, useRouteParams, useWfFinished, useWfOutlet, useWfState, wfKind, wfShortcuts };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooksjs/event-wf",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "@wooksjs/event-wf",
   "keywords": [
     "app",
@@ -22,13 +22,8 @@
     "url": "git+https://github.com/wooksjs/wooksjs.git",
     "directory": "packages/event-wf"
   },
-  "bin": {
-    "wooksjs-event-wf-skill": "scripts/setup-skills.js"
-  },
   "files": [
-    "dist",
-    "skills",
-    "scripts"
+    "dist"
   ],
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -42,21 +37,32 @@
     }
   },
   "dependencies": {
-    "@prostojs/wf": "^0.0.18"
+    "@prostojs/wf": "^0.1.1"
   },
   "devDependencies": {
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@wooksjs/event-core": "^0.7.7",
-    "wooks": "^0.7.7"
+    "@wooksjs/event-core": "^0.7.9",
+    "@wooksjs/event-http": "^0.7.9",
+    "@wooksjs/http-body": "^0.7.9",
+    "wooks": "^0.7.9"
   },
   "peerDependencies": {
     "@prostojs/logger": "^0.4.3",
-    "@wooksjs/event-core": "^0.7.7",
-    "wooks": "^0.7.7"
+    "@wooksjs/event-core": "^0.7.9",
+    "@wooksjs/event-http": "^0.7.9",
+    "@wooksjs/http-body": "^0.7.9",
+    "wooks": "^0.7.9"
+  },
+  "peerDependenciesMeta": {
+    "@wooksjs/event-http": {
+      "optional": true
+    },
+    "@wooksjs/http-body": {
+      "optional": true
+    }
   },
   "scripts": {
-    "build": "rolldown -c ../../rolldown.config.mjs",
-    "setup-skills": "node scripts/setup-skills.js"
+    "build": "rolldown -c ../../rolldown.config.mjs"
   }
 }

package/scripts/setup-skills.js

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-/* prettier-ignore */
-'use strict'
-
-const fs = require('fs')
-const path = require('path')
-const os = require('os')
-
-const SKILL_NAME = 'wooksjs-event-wf'
-const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
-
-if (!fs.existsSync(SKILL_SRC)) {
-  console.error(`No skills found at ${SKILL_SRC}`)
-  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
-  process.exit(1)
-}
-
-const AGENTS = {
-  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
-  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
-  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
-  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
-  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
-}
-
-const args = process.argv.slice(2)
-const isGlobal = args.includes('--global') || args.includes('-g')
-const isPostinstall = args.includes('--postinstall')
-let installed = 0, skipped = 0
-const installedDirs = []
-
-for (const [agentName, cfg] of Object.entries(AGENTS)) {
-  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
-  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
-
-  // In postinstall mode: silently skip agents that aren't set up globally
-  if (isPostinstall || isGlobal) {
-    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
-  }
-
-  const dest = path.join(targetBase, SKILL_NAME)
-  try {
-    fs.mkdirSync(dest, { recursive: true })
-    fs.cpSync(SKILL_SRC, dest, { recursive: true })
-    console.log(`✅  ${agentName}: installed to ${dest}`)
-    installed++
-    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
-  } catch (err) {
-    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
-  }
-}
-
-// Add locally-installed skill dirs to .gitignore
-if (!isGlobal && installedDirs.length > 0) {
-  const gitignorePath = path.join(process.cwd(), '.gitignore')
-  let gitignoreContent = ''
-  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
-  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
-  if (linesToAdd.length > 0) {
-    const hasHeader = gitignoreContent.includes('# AI agent skills')
-    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
-      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
-      + linesToAdd.join('\n') + '\n'
-    fs.appendFileSync(gitignorePath, block)
-    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
-  }
-}
-
-if (installed === 0 && isPostinstall) {
-  // Silence is fine — no agents present, nothing to do
-} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
-  console.log('No agent directories detected. Try --global or run without it for project-local install.')
-} else if (installed === 0) {
-  console.log('Nothing installed. Run without --global to install project-locally.')
-} else {
-  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
-}

package/skills/wooksjs-event-wf/SKILL.md

@@ -1,42 +0,0 @@
----
-name: wooksjs-event-wf
-description: Wooks Workflow framework — composable, step-based workflow engine for Node.js. Load when building workflow/process automation with wooks; defining workflow steps and flows; using workflow composables (useWfState, useRouteParams, useLogger); working with @wooksjs/event-core context (key, cached, defineWook, defineEventKind); creating conditional and looping flows; resuming paused workflows; handling user input requirements; using string-based step handlers; attaching workflow spies; working with StepRetriableError; creating custom event context composables for workflows; sharing parent event context (eventContext) for HTTP integration; accessing HTTP composables from workflow steps.
----
-
-# @wooksjs/event-wf
-
-A composable workflow framework for Node.js built on async context (AsyncLocalStorage) and `@prostojs/wf`. Define steps and flows as composable units — steps execute sequentially with conditional branching, loops, pause/resume, and user input handling. Context is scoped per workflow execution.
-
-## How to use this skill
-
-Read the domain file that matches the task. Do not load all files — only what you need.
-
-| Domain                         | File                           | Load when...                                                                                                                                                                                 |
-| ------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Event context (core machinery) | [event-core.md](event-core.md) | Understanding `EventContext`, `key()`/`cached()`/`defineWook()`/`defineEventKind()`/`slot()`, creating custom composables, lazy evaluation and caching, building your own `use*()` functions |
-| Workflow app setup             | [core.md](core.md)             | Creating a workflow app, `createWfApp`, starting/resuming workflows, error handling, spies, testing, logging, sharing parent event context (`eventContext`), HTTP integration                |
-| Steps & flows                  | [workflows.md](workflows.md)   | Defining steps (`app.step`), defining flows (`app.flow`), workflow schemas, conditions, loops, user input, parametric steps, `useWfState`, `StepRetriableError`, string-based handlers       |
-
-## Quick reference
-
-```ts
-import { createWfApp } from '@wooksjs/event-wf'
-
-const app = createWfApp<{ result: number }>()
-
-app.step('add', {
-  input: 'number',
-  handler: 'ctx.result += input',
-})
-
-app.flow('calculate', [
-  { id: 'add', input: 5 },
-  { id: 'add', input: 2 },
-  { condition: 'result < 10', steps: [{ id: 'add', input: 3 }] },
-])
-
-const output = await app.start('calculate', { result: 0 })
-console.log(output.state.context) // { result: 10 }
-```
-
-Key exports: `createWfApp()`, `useWfState()`, `useRouteParams()`, `useLogger()`, `StepRetriableError`.