workflow 5.0.0-beta.27 → 5.0.0-beta.28

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AASA,OAAO,mCAAmC,CAAC;AAE3C,YAAY,EACV,KAAK,EACL,gBAAgB,EAChB,eAAe,EACf,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,EACd,UAAU,EACV,aAAa,GACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,MAAM,EACN,GAAG,EACH,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,GACnC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,GACN,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAOA,OAAO,mCAAmC,CAAC;AAE3C,YAAY,EACV,KAAK,EACL,gBAAgB,EAChB,eAAe,EACf,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,EACd,UAAU,EACV,aAAa,GACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,MAAM,EACN,GAAG,EACH,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,GACnC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,GACN,MAAM,8BAA8B,CAAC"}

package/dist/api.js

@@ -1,14 +1,12 @@
 // Side-effect import: ensure `world.ts` is loaded so its module-load
 // `globalThis[GetWorldFnKey] ??= getWorld` registration fires before any
-// host route reaches `getWorldLazy()`. Without this, webpack/turbopack
-// tree-shake `world.ts` out of routes that only use `start` (the most
-// common host-side entry point) and `getWorldLazy()`'s dynamic-import
-// fallback then fails because the bundler inlined `get-world-lazy.js`
-// into the route bundle. Resolved to an empty stub via the `workflow`
-// export condition in VM/step bundles, so this stays host-only.
+// host route reaches `getWorldLazy()`. Without this, webpack/turbopack can
+// tree-shake `world.ts` out of routes that only use `start`. Resolved to an
+// empty stub via the `workflow` export condition in VM/step bundles, so this
+// stays host-only.
 // See `@workflow/core/src/runtime/world-init.ts` for the full rationale.
 import '@workflow/core/runtime/world-init';
 export { getHookByToken, resumeHook, resumeWebhook, } from '@workflow/core/runtime/resume-hook';
 export { getRun, Run, } from '@workflow/core/runtime/run';
 export { start, } from '@workflow/core/runtime/start';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxxRUFBcUU7QUFDckUseUVBQXlFO0FBQ3pFLHVFQUF1RTtBQUN2RSxzRUFBc0U7QUFDdEUsc0VBQXNFO0FBQ3RFLHNFQUFzRTtBQUN0RSxzRUFBc0U7QUFDdEUsZ0VBQWdFO0FBQ2hFLHlFQUF5RTtBQUN6RSxPQUFPLG1DQUFtQyxDQUFDO0FBUTNDLE9BQU8sRUFDTCxjQUFjLEVBQ2QsVUFBVSxFQUNWLGFBQWEsR0FDZCxNQUFNLG9DQUFvQyxDQUFDO0FBQzVDLE9BQU8sRUFDTCxNQUFNLEVBQ04sR0FBRyxHQUdKLE1BQU0sNEJBQTRCLENBQUM7QUFDcEMsT0FBTyxFQUVMLEtBQUssR0FDTixNQUFNLDhCQUE4QixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gU2lkZS1lZmZlY3QgaW1wb3J0OiBlbnN1cmUgYHdvcmxkLnRzYCBpcyBsb2FkZWQgc28gaXRzIG1vZHVsZS1sb2FkXG4vLyBgZ2xvYmFsVGhpc1tHZXRXb3JsZEZuS2V5XSA/Pz0gZ2V0V29ybGRgIHJlZ2lzdHJhdGlvbiBmaXJlcyBiZWZvcmUgYW55XG4vLyBob3N0IHJvdXRlIHJlYWNoZXMgYGdldFdvcmxkTGF6eSgpYC4gV2l0aG91dCB0aGlzLCB3ZWJwYWNrL3R1cmJvcGFja1xuLy8gdHJlZS1zaGFrZSBgd29ybGQudHNgIG91dCBvZiByb3V0ZXMgdGhhdCBvbmx5IHVzZSBgc3RhcnRgICh0aGUgbW9zdFxuLy8gY29tbW9uIGhvc3Qtc2lkZSBlbnRyeSBwb2ludCkgYW5kIGBnZXRXb3JsZExhenkoKWAncyBkeW5hbWljLWltcG9ydFxuLy8gZmFsbGJhY2sgdGhlbiBmYWlscyBiZWNhdXNlIHRoZSBidW5kbGVyIGlubGluZWQgYGdldC13b3JsZC1sYXp5LmpzYFxuLy8gaW50byB0aGUgcm91dGUgYnVuZGxlLiBSZXNvbHZlZCB0byBhbiBlbXB0eSBzdHViIHZpYSB0aGUgYHdvcmtmbG93YFxuLy8gZXhwb3J0IGNvbmRpdGlvbiBpbiBWTS9zdGVwIGJ1bmRsZXMsIHNvIHRoaXMgc3RheXMgaG9zdC1vbmx5LlxuLy8gU2VlIGBAd29ya2Zsb3cvY29yZS9zcmMvcnVudGltZS93b3JsZC1pbml0LnRzYCBmb3IgdGhlIGZ1bGwgcmF0aW9uYWxlLlxuaW1wb3J0ICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3dvcmxkLWluaXQnO1xuXG5leHBvcnQgdHlwZSB7XG4gIEV2ZW50LFxuICBTdG9wU2xlZXBPcHRpb25zLFxuICBTdG9wU2xlZXBSZXN1bHQsXG4gIFdvcmtmbG93UnVuLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lJztcbmV4cG9ydCB7XG4gIGdldEhvb2tCeVRva2VuLFxuICByZXN1bWVIb29rLFxuICByZXN1bWVXZWJob29rLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3Jlc3VtZS1ob29rJztcbmV4cG9ydCB7XG4gIGdldFJ1bixcbiAgUnVuLFxuICB0eXBlIFdvcmtmbG93UmVhZGFibGVTdHJlYW0sXG4gIHR5cGUgV29ya2Zsb3dSZWFkYWJsZVN0cmVhbU9wdGlvbnMsXG59IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3J1bnRpbWUvcnVuJztcbmV4cG9ydCB7XG4gIHR5cGUgU3RhcnRPcHRpb25zLFxuICBzdGFydCxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZS9zdGFydCc7XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxxRUFBcUU7QUFDckUseUVBQXlFO0FBQ3pFLDJFQUEyRTtBQUMzRSw0RUFBNEU7QUFDNUUsNkVBQTZFO0FBQzdFLG1CQUFtQjtBQUNuQix5RUFBeUU7QUFDekUsT0FBTyxtQ0FBbUMsQ0FBQztBQVEzQyxPQUFPLEVBQ0wsY0FBYyxFQUNkLFVBQVUsRUFDVixhQUFhLEdBQ2QsTUFBTSxvQ0FBb0MsQ0FBQztBQUM1QyxPQUFPLEVBQ0wsTUFBTSxFQUNOLEdBQUcsR0FHSixNQUFNLDRCQUE0QixDQUFDO0FBQ3BDLE9BQU8sRUFFTCxLQUFLLEdBQ04sTUFBTSw4QkFBOEIsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIFNpZGUtZWZmZWN0IGltcG9ydDogZW5zdXJlIGB3b3JsZC50c2AgaXMgbG9hZGVkIHNvIGl0cyBtb2R1bGUtbG9hZFxuLy8gYGdsb2JhbFRoaXNbR2V0V29ybGRGbktleV0gPz89IGdldFdvcmxkYCByZWdpc3RyYXRpb24gZmlyZXMgYmVmb3JlIGFueVxuLy8gaG9zdCByb3V0ZSByZWFjaGVzIGBnZXRXb3JsZExhenkoKWAuIFdpdGhvdXQgdGhpcywgd2VicGFjay90dXJib3BhY2sgY2FuXG4vLyB0cmVlLXNoYWtlIGB3b3JsZC50c2Agb3V0IG9mIHJvdXRlcyB0aGF0IG9ubHkgdXNlIGBzdGFydGAuIFJlc29sdmVkIHRvIGFuXG4vLyBlbXB0eSBzdHViIHZpYSB0aGUgYHdvcmtmbG93YCBleHBvcnQgY29uZGl0aW9uIGluIFZNL3N0ZXAgYnVuZGxlcywgc28gdGhpc1xuLy8gc3RheXMgaG9zdC1vbmx5LlxuLy8gU2VlIGBAd29ya2Zsb3cvY29yZS9zcmMvcnVudGltZS93b3JsZC1pbml0LnRzYCBmb3IgdGhlIGZ1bGwgcmF0aW9uYWxlLlxuaW1wb3J0ICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3dvcmxkLWluaXQnO1xuXG5leHBvcnQgdHlwZSB7XG4gIEV2ZW50LFxuICBTdG9wU2xlZXBPcHRpb25zLFxuICBTdG9wU2xlZXBSZXN1bHQsXG4gIFdvcmtmbG93UnVuLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lJztcbmV4cG9ydCB7XG4gIGdldEhvb2tCeVRva2VuLFxuICByZXN1bWVIb29rLFxuICByZXN1bWVXZWJob29rLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3Jlc3VtZS1ob29rJztcbmV4cG9ydCB7XG4gIGdldFJ1bixcbiAgUnVuLFxuICB0eXBlIFdvcmtmbG93UmVhZGFibGVTdHJlYW0sXG4gIHR5cGUgV29ya2Zsb3dSZWFkYWJsZVN0cmVhbU9wdGlvbnMsXG59IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3J1bnRpbWUvcnVuJztcbmV4cG9ydCB7XG4gIHR5cGUgU3RhcnRPcHRpb25zLFxuICBzdGFydCxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZS9zdGFydCc7XG4iXX0=

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import '@workflow/core/runtime/world-init';
 export * from '@workflow/core';
 export * from './stdlib.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,mCAAmC,CAAC;AAE3C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -1,3 +1,8 @@
+// Host-side side effect: defineHook().resume() and other top-level helpers can
+// reach getWorldLazy() without importing `workflow/api`. The `workflow` export
+// condition resolves this package entry to `workflow.js` inside VM/workflow
+// bundles, so this init import stays out of sandboxed workflow code.
+import '@workflow/core/runtime/world-init';
 export * from '@workflow/core';
 export * from './stdlib.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbImV4cG9ydCAqIGZyb20gJ0B3b3JrZmxvdy9jb3JlJztcbmV4cG9ydCAqIGZyb20gJy4vc3RkbGliLmpzJztcbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsK0VBQStFO0FBQy9FLCtFQUErRTtBQUMvRSw0RUFBNEU7QUFDNUUscUVBQXFFO0FBQ3JFLE9BQU8sbUNBQW1DLENBQUM7QUFFM0MsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEhvc3Qtc2lkZSBzaWRlIGVmZmVjdDogZGVmaW5lSG9vaygpLnJlc3VtZSgpIGFuZCBvdGhlciB0b3AtbGV2ZWwgaGVscGVycyBjYW5cbi8vIHJlYWNoIGdldFdvcmxkTGF6eSgpIHdpdGhvdXQgaW1wb3J0aW5nIGB3b3JrZmxvdy9hcGlgLiBUaGUgYHdvcmtmbG93YCBleHBvcnRcbi8vIGNvbmRpdGlvbiByZXNvbHZlcyB0aGlzIHBhY2thZ2UgZW50cnkgdG8gYHdvcmtmbG93LmpzYCBpbnNpZGUgVk0vd29ya2Zsb3dcbi8vIGJ1bmRsZXMsIHNvIHRoaXMgaW5pdCBpbXBvcnQgc3RheXMgb3V0IG9mIHNhbmRib3hlZCB3b3JrZmxvdyBjb2RlLlxuaW1wb3J0ICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3dvcmxkLWluaXQnO1xuXG5leHBvcnQgKiBmcm9tICdAd29ya2Zsb3cvY29yZSc7XG5leHBvcnQgKiBmcm9tICcuL3N0ZGxpYi5qcyc7XG4iXX0=

package/dist/runtime.d.ts

@@ -1,2 +1,3 @@
-export { createWorld, getWorld, getWorldHandlers, healthCheck, type HealthCheckEndpoint, type HealthCheckOptions, type HealthCheckResult, setWorld, workflowEntrypoint, } from '@workflow/core/runtime';
+import '@workflow/core/runtime/world-init';
+export { createWorld, getWorld, getWorldHandlers, type HealthCheckEndpoint, type HealthCheckOptions, type HealthCheckResult, healthCheck, setWorld, workflowEntrypoint, } from '@workflow/core/runtime';
 //# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,QAAQ,EACR,gBAAgB,EAChB,WAAW,EACX,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,QAAQ,EACR,kBAAkB,GACnB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,mCAAmC,CAAC;AAE3C,OAAO,EACL,WAAW,EACX,QAAQ,EACR,gBAAgB,EAChB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,WAAW,EACX,QAAQ,EACR,kBAAkB,GACnB,MAAM,wBAAwB,CAAC"}

package/dist/runtime.js

@@ -1,2 +1,5 @@
+// Host-side side effect: runtime-only imports can still reach getWorldLazy()
+// through stream helpers, so register getWorld before exporting runtime APIs.
+import '@workflow/core/runtime/world-init';
 export { createWorld, getWorld, getWorldHandlers, healthCheck, setWorld, workflowEntrypoint, } from '@workflow/core/runtime';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVudGltZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9ydW50aW1lLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFDTCxXQUFXLEVBQ1gsUUFBUSxFQUNSLGdCQUFnQixFQUNoQixXQUFXLEVBSVgsUUFBUSxFQUNSLGtCQUFrQixHQUNuQixNQUFNLHdCQUF3QixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IHtcbiAgY3JlYXRlV29ybGQsXG4gIGdldFdvcmxkLFxuICBnZXRXb3JsZEhhbmRsZXJzLFxuICBoZWFsdGhDaGVjayxcbiAgdHlwZSBIZWFsdGhDaGVja0VuZHBvaW50LFxuICB0eXBlIEhlYWx0aENoZWNrT3B0aW9ucyxcbiAgdHlwZSBIZWFsdGhDaGVja1Jlc3VsdCxcbiAgc2V0V29ybGQsXG4gIHdvcmtmbG93RW50cnlwb2ludCxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZSc7XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVudGltZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9ydW50aW1lLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLDZFQUE2RTtBQUM3RSw4RUFBOEU7QUFDOUUsT0FBTyxtQ0FBbUMsQ0FBQztBQUUzQyxPQUFPLEVBQ0wsV0FBVyxFQUNYLFFBQVEsRUFDUixnQkFBZ0IsRUFJaEIsV0FBVyxFQUNYLFFBQVEsRUFDUixrQkFBa0IsR0FDbkIsTUFBTSx3QkFBd0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEhvc3Qtc2lkZSBzaWRlIGVmZmVjdDogcnVudGltZS1vbmx5IGltcG9ydHMgY2FuIHN0aWxsIHJlYWNoIGdldFdvcmxkTGF6eSgpXG4vLyB0aHJvdWdoIHN0cmVhbSBoZWxwZXJzLCBzbyByZWdpc3RlciBnZXRXb3JsZCBiZWZvcmUgZXhwb3J0aW5nIHJ1bnRpbWUgQVBJcy5cbmltcG9ydCAnQHdvcmtmbG93L2NvcmUvcnVudGltZS93b3JsZC1pbml0JztcblxuZXhwb3J0IHtcbiAgY3JlYXRlV29ybGQsXG4gIGdldFdvcmxkLFxuICBnZXRXb3JsZEhhbmRsZXJzLFxuICB0eXBlIEhlYWx0aENoZWNrRW5kcG9pbnQsXG4gIHR5cGUgSGVhbHRoQ2hlY2tPcHRpb25zLFxuICB0eXBlIEhlYWx0aENoZWNrUmVzdWx0LFxuICBoZWFsdGhDaGVjayxcbiAgc2V0V29ybGQsXG4gIHdvcmtmbG93RW50cnlwb2ludCxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZSc7XG4iXX0=

package/docs/configuration/build-and-diagnostics.mdx

@@ -0,0 +1,51 @@
+---
+title: Build and Diagnostics
+description: Build-time environment variables for manifests, source maps, and development diagnostics.
+type: reference
+summary: Configure generated bundles and build-time diagnostics.
+related:
+  - /docs/configuration/framework-options
+  - /docs/api-reference/workflow-next/with-workflow
+---
+
+Build and diagnostics variables are read by the compiler, builders, and framework integrations when your app is built or when the dev server starts.
+
+## Source maps
+
+### `WORKFLOW_SOURCEMAP`
+
+- Framework option: `sourcemap` where supported
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+- Explicit framework config wins over this environment variable.
+
+Accepted values:
+
+- `true`, `inline`, or `1` - append an inline base64 source map to each generated bundle.
+- `linked` - write a `.map` file and add a `sourceMappingURL` comment.
+- `external` - write a `.map` file without adding the comment.
+- `both` - emit inline and external source maps.
+- `false` or `0` - omit source maps.
+
+### `WORKFLOW_EMIT_SOURCEMAPS_FOR_DEBUGGING`
+
+- Default: disabled
+- Legacy source-map toggle kept for compatibility.
+- Only affects the final workflow wrapper and webhook bundle.
+- Prefer `WORKFLOW_SOURCEMAP` or a framework `sourcemap` option.
+
+## Manifests
+
+### `WORKFLOW_PUBLIC_MANIFEST`
+
+- Default: disabled
+- Set `1` to expose the workflow manifest at `/.well-known/workflow/v1/manifest.json`.
+- Useful for e2e tests and tools that need to discover workflows over HTTP.
+
+## Development diagnostics
+
+### `WORKFLOW_DEV_HMR_LOGS`
+
+- Default: disabled
+- Set `1` to log workflow rebuild activity during `next dev`.
+- Useful for diagnosing watch and HMR issues.

package/docs/configuration/cli-and-web-ui.mdx

@@ -0,0 +1,154 @@
+---
+title: CLI and Web UI
+description: CLI flags and environment variables for inspecting local, Postgres, and Vercel Workflow runs.
+type: reference
+summary: Configure workflow inspect, workflow web, workflow health, and observability tooling.
+related:
+  - /docs/observability
+  - /docs/configuration/worlds
+---
+
+The `workflow` CLI uses flags first, then environment variables, then defaults or local inference.
+
+Vercel project and auth settings can often be inferred from `.vercel/project.json` and your Vercel CLI login.
+
+## Target backend
+
+### `--backend` / `-b`
+
+- Environment variable: `WORKFLOW_TARGET_WORLD`
+- Default: `local`
+- Backend to inspect: `local`, `vercel`, or a World package.
+
+### `--authToken` / `-a`
+
+- Environment variable: `WORKFLOW_VERCEL_AUTH_TOKEN`
+- Default: Vercel CLI login
+- Vercel token for `--backend vercel`.
+
+### `--project`
+
+- Environment variable: `WORKFLOW_VERCEL_PROJECT`
+- Default: inferred when possible
+- Vercel project ID for `--backend vercel`.
+
+### `--team`
+
+- Environment variable: `WORKFLOW_VERCEL_TEAM`
+- Default: inferred when possible
+- Vercel team ID for `--backend vercel`.
+
+### `WORKFLOW_VERCEL_PROJECT_NAME`
+
+- CLI flag: none
+- Default: inferred when possible
+- Vercel project slug used for dashboard links.
+
+### `--env` / `-e`
+
+- Environment variable: `WORKFLOW_VERCEL_ENV`
+- Default: `production`
+- Vercel environment for `--backend vercel`.
+- Accepts `production` or `preview`.
+
+## Web UI
+
+### `--web` / `-w`
+
+- Environment variable: none
+- Default: disabled
+- Opens the relevant dashboard or web UI instead of printing terminal output.
+
+### `--webPort`
+
+- Environment variable: `WORKFLOW_WEB_PORT`
+- Default: `3456`
+- Port for the local web UI server.
+
+### `--noBrowser`
+
+- Environment variable: `WORKFLOW_DISABLE_BROWSER_OPEN`
+- Default: browser opens
+- Prevents the CLI from opening a browser for web UI commands.
+
+### `--localUi`
+
+- Environment variable: `WORKFLOW_LOCAL_UI`
+- Default: disabled
+- Uses the local web UI instead of the Vercel dashboard when inspecting Vercel.
+
+### `--url`
+
+- Environment variable: none
+- Default: disabled
+- Prints the dashboard or run deep-link URL instead of opening a browser or starting a local server.
+
+## Output and filtering
+
+### `--json` / `-j`
+
+- Environment variable: none
+- Default: disabled
+- Prints machine-readable JSON where the command supports it.
+
+### `--sort`
+
+- Environment variable: none
+- Default: `desc`
+- Sort order for list commands. Accepts `asc` or `desc`.
+
+### `--limit`
+
+- Environment variable: none
+- Default: `20`
+- Number of items returned per page for list commands.
+
+### `--cursor`
+
+- Environment variable: none
+- Default: unset
+- Pagination cursor for list commands.
+
+### `--interactive` / `-i`
+
+- Environment variable: none
+- Default: disabled
+- Enables keyboard-controlled pagination for supported list commands.
+
+## Health checks
+
+### `--port` / `-p`
+
+- Command: `workflow health`
+- Environment variable: `WORKFLOW_LOCAL_BASE_URL`, then `PORT`
+- Default: `3000` when neither env var is set
+- Local server port for health checks.
+- The flag writes `WORKFLOW_LOCAL_BASE_URL`.
+
+## Verbose logging and updates
+
+### `--verbose` / `-v`
+
+- Environment variable: `DEBUG`
+- Default: disabled
+- Enables verbose CLI output.
+
+### `WORKFLOW_NO_UPDATE_CHECK`
+
+- CLI flag: none
+- Default: update check enabled
+- Set `1` to disable the CLI update check.
+
+## Observability paths
+
+### `WORKFLOW_OBSERVABILITY_CWD`
+
+- CLI flag: none
+- Default: `process.cwd()`
+- Working directory used by observability tooling to find `.vercel`, `.workflow-data`, and manifests.
+
+### `WORKFLOW_MANIFEST_PATH`
+
+- CLI flag: none
+- Default: inferred
+- Explicit path to the workflow manifest for the web UI.

package/docs/configuration/framework-options.mdx

@@ -0,0 +1,165 @@
+---
+title: Framework Options
+description: Build-time and dev-server configuration for Workflow framework integrations.
+type: reference
+summary: Configure Workflow through framework plugins and module options.
+related:
+  - /docs/api-reference/workflow-next/with-workflow
+  - /docs/configuration/build-and-diagnostics
+---
+
+Framework options are read at build or dev-server startup. Use them for settings that belong in source control, such as source-map behavior or framework-specific output paths.
+
+## Next.js
+
+`withWorkflow()` accepts an optional second argument.
+
+### `workflows.local.port`
+
+- Environment override: `PORT`
+- Default: auto-detected
+- Local-only. Sets the application port used by the Local World when queue messages call back into the app.
+- The option writes `PORT` for non-Vercel builds.
+
+### `workflows.sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+- Explicit config wins over `WORKFLOW_SOURCEMAP`.
+
+```typescript title="next.config.ts" lineNumbers
+import { withWorkflow } from "workflow/next";
+
+export default withWorkflow(
+  {},
+  {
+    workflows: {
+      local: {
+        port: 4000,
+      },
+      sourcemap: false,
+    },
+  }
+);
+```
+
+## Nitro and Nuxt
+
+Configure Workflow through the Nitro `workflow` module options.
+
+### `workflow.dirs`
+
+- Environment override: none
+- Default: `["workflows"]`
+- Directories scanned for workflow files.
+
+### `workflow.typescriptPlugin`
+
+- Environment override: none
+- Default: `false` for raw Nitro, `true` through the Nuxt module
+- Enables the Workflow TypeScript language-service plugin in generated `tsconfig.json`.
+- This affects editor diagnostics and completions. Workflow builds do not require it.
+- Raw Nitro leaves it opt-in because it changes TypeScript editor behavior. Nuxt enables it by default because the Nuxt module owns the generated `tsconfig.json` flow.
+
+### `workflow.runtime`
+
+- Environment override: none
+- Default: framework default
+- Node.js runtime emitted for Vercel Functions, such as `nodejs22.x` or `nodejs24.x`.
+
+### `workflow.sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+## NestJS
+
+Configure Workflow through `WorkflowModule.forRoot()`.
+
+### `workingDir`
+
+- Environment override: none
+- Default: `process.cwd()`
+- Application root used for workflow discovery and bundling.
+
+### `dirs`
+
+- Environment override: none
+- Default: `["src"]`
+- Directories scanned for workflow files.
+
+### `outDir`
+
+- Environment override: none
+- Default: `.nestjs/workflow`
+- Directory for generated workflow bundles.
+
+### `watch`
+
+- Environment override: none
+- Default: `false`
+- Rebuilds workflow bundles during development.
+
+### `moduleType`
+
+- Environment override: none
+- Default: `es6`
+- Set to `commonjs` when the Nest app compiles TypeScript to CJS through SWC.
+
+### `distDir`
+
+- Environment override: none
+- Default: `dist`
+- Compiled JavaScript output directory used by the CJS import rewrite.
+
+### `sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+### `skipBuild`
+
+- Environment override: none
+- Default: `false`
+- Skips bundle generation when bundles are already pre-built.
+
+## Astro
+
+### `sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+## SvelteKit
+
+### `sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+## Rollup
+
+### `exclude`
+
+- Environment override: none
+- Default: `[]`
+- Path prefixes skipped by the directive transform.
+
+## Source-map values
+
+`WORKFLOW_SOURCEMAP` accepts these values:
+
+- `true`, `inline`, or `1` - append an inline base64 source map to each generated bundle.
+- `linked` - write a `.map` file and add a `sourceMappingURL` comment.
+- `external` - write a `.map` file without adding the comment.
+- `both` - emit inline and external source maps.
+- `false` or `0` - omit source maps.
+
+<Callout type="info">
+The legacy `WORKFLOW_EMIT_SOURCEMAPS_FOR_DEBUGGING=1` variable still works, but it only affects the final workflow wrapper and webhook bundle. Prefer `WORKFLOW_SOURCEMAP` or a framework `sourcemap` option.
+</Callout>

package/docs/configuration/index.mdx

@@ -0,0 +1,32 @@
+---
+title: Configuration
+description: Reference for Workflow SDK configuration options, environment variables, and CLI overrides.
+type: conceptual
+summary: Configure framework integrations, Worlds, runtime tuning, builds, and CLI observability.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/configuration/framework-options
+  - /docs/configuration/worlds
+  - /docs/configuration/runtime-tuning
+  - /docs/configuration/build-and-diagnostics
+  - /docs/configuration/cli-and-web-ui
+---
+
+Workflow SDK is configured through typed framework options, World factory options, environment variables, and CLI flags.
+
+When more than one surface controls the same setting, the usual precedence is:
+
+```txt
+explicit option or CLI flag > environment variable > built-in default
+```
+
+Invalid environment variable values do not crash the app. They log a warning and fall back to the default, or to the documented clamp range.
+
+## Configuration areas
+
+- [Framework options](/docs/configuration/framework-options) - build-time and dev-server options for Next.js, Nitro, NestJS, Astro, SvelteKit, and Rollup.
+- [Worlds](/docs/configuration/worlds) - `WORKFLOW_TARGET_WORLD`, Local World, Postgres World, and Vercel World configuration.
+- [Runtime tuning](/docs/configuration/runtime-tuning) - replay budgets, inline execution, queue delivery limits, compression, tracing, and advanced runtime escape hatches.
+- [Build and diagnostics](/docs/configuration/build-and-diagnostics) - public manifests, HMR logs, and source-map controls.
+- [CLI and web UI](/docs/configuration/cli-and-web-ui) - `workflow inspect`, `workflow web`, `workflow health`, and observability environment overrides.

package/docs/configuration/meta.json

@@ -0,0 +1,12 @@
+{
+  "title": "Configuration",
+  "pages": [
+    "index",
+    "framework-options",
+    "worlds",
+    "runtime-tuning",
+    "build-and-diagnostics",
+    "cli-and-web-ui"
+  ],
+  "defaultOpen": false
+}

package/docs/configuration/runtime-tuning.mdx

@@ -0,0 +1,143 @@
+---
+title: Runtime Tuning
+description: Runtime environment variables for replay, inline execution, queue delivery, compression, tracing, and advanced limits.
+type: reference
+summary: Tune Workflow runtime behavior where workflows execute.
+related:
+  - /docs/configuration/worlds
+  - /docs/how-it-works/event-sourcing
+---
+
+Runtime variables are read where workflows execute. Set them on the deployment or dev server.
+
+## Replay and queue delivery
+
+### `WORKFLOW_REPLAY_TIMEOUT_MS`
+
+- Default: `240000`
+- Clamp: `30000` to `780000`
+- Charged time budget for replay and orchestration work in one handler invocation.
+- Covers loading events, re-running the workflow function, resolving suspensions, and scheduling follow-up work.
+- Does not include time spent inside inline `"use step"` bodies. Steps are bounded by the platform function duration instead.
+
+For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPLAY_TIMEOUT_MS=300000`, because the replay budget is paused while the step body runs.
+
+### `WORKFLOW_REPLAY_TIMEOUT_MAX_RETRIES`
+
+- Default: `3`
+- Queue deliveries that may hit the replay timeout before the run is failed with `REPLAY_TIMEOUT`.
+
+### `WORKFLOW_MAX_QUEUE_DELIVERIES`
+
+- Default: `48`
+- Delivery attempts before a run or step is failed gracefully.
+- Can only be lowered. The default is calibrated so Workflow can record failure before the queue expires the message.
+
+### `WORKFLOW_REPLAY_DIVERGENCE_MAX_RETRIES`
+
+- Default: `3`
+- Recovery replays before replay divergence is recorded as corruption.
+
+## Inline execution
+
+### `WORKFLOW_V2_TIMEOUT_MS`
+
+- Default: `120000`
+- Wall-clock guard for the inline replay loop.
+- Once elapsed, the handler requeues the workflow instead of continuing to run more inline work in the same invocation.
+
+### `WORKFLOW_MAX_INLINE_STEPS`
+
+- Default: `3`
+- Clamp: `1` to `16`
+- Number of newly-created steps one invocation runs inline in parallel before queueing the rest.
+
+### `WORKFLOW_TURBO`
+
+- Default: enabled
+- Fast path for a run's first delivery.
+- Set `0` or `false` to disable.
+
+### `WORKFLOW_OPTIMISTIC_INLINE_START`
+
+- Default: disabled
+- Starts inline step bodies before their `step_started` event is confirmed.
+- Use only when step side effects are idempotent.
+- Set `0` or `false` to force it off, including the first-delivery fast path used by `WORKFLOW_TURBO`.
+
+## Compression and tracing
+
+### `WORKFLOW_DISABLE_COMPRESSION`
+
+- Default: compression enabled
+- Set `1` to disable compression when writing payloads.
+- Reads still decompress existing payloads.
+
+### `WORKFLOW_COMPRESSION_CODEC`
+
+- Default: automatic
+- Forces the write-side codec to `zstd` or `gzip`.
+- Invalid values are ignored. Automatic mode prefers `zstd` when the current Node.js runtime supports it, otherwise it falls back to `gzip`.
+
+### `WORKFLOW_TRACE_MODE`
+
+- Default: `linked`
+- OpenTelemetry span topology for runs.
+- Accepts `linked` or `continuous`.
+
+### `DEBUG`
+
+- Default: unset
+- Debug log filter with wildcards and negation.
+- Examples: `workflow:*`, `workflow:*,-workflow:telemetry:*`.
+
+## Queue namespace
+
+### `WORKFLOW_QUEUE_NAMESPACE`
+
+- Default: none
+- Queue topic namespace shared by build output and Worlds.
+- Must match `^[a-z][a-z0-9]*$`.
+- Set it consistently at build and runtime.
+
+## Streams and waits
+
+These variables are primarily for tests, debugging, or unusual deployments.
+
+### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+
+- Default: `10`
+- Stream write buffering interval.
+- Also available as `streamFlushIntervalMs` on Worlds that expose it.
+
+### `WORKFLOW_FRAMED_STREAM_MAX_RECONNECTS`
+
+- Default: `50`
+- Consecutive reconnect cap for framed stream readers.
+
+### `WORKFLOW_FRAMED_STREAM_MAX_TOTAL_RECONNECTS`
+
+- Default: `1000`
+- Total reconnect cap per stream session.
+
+### `WORKFLOW_WAIT_CONTINUATION_MAX_DELAY_SECONDS`
+
+- Default: `82800` (23 hours)
+- Longest single queue delay used for `sleep()` continuations.
+- If a wait is longer than this, Workflow queues one continuation for the maximum delay, then queues another continuation after that message fires, repeating until the wait's target time is reached.
+
+### `WORKFLOW_NEAR_ELAPSED_WAIT_THRESHOLD_SECONDS`
+
+- Default: `2`
+- Clock-skew tolerance for wait continuations that arrive near their target time.
+
+### `WORKFLOW_DEFERRED_CHECK_DELAY_MS`
+
+- Default: `100`
+- Delay before the unconsumed-event check fires.
+- Minimum: `10`.
+
+### `WORKFLOW_LOCK_POLL_INTERVAL_MS`
+
+- Default: `10`
+- Poll interval for detecting stream lock release.

package/docs/configuration/worlds.mdx

@@ -0,0 +1,228 @@
+---
+title: Worlds
+description: Configure the Workflow backend that stores runs and delivers queue messages.
+type: reference
+summary: Select and configure Local, Postgres, Vercel, or custom Worlds.
+related:
+  - /docs/deploying/world/local-world
+  - /docs/deploying/world/postgres-world
+  - /docs/deploying/world/vercel-world
+---
+
+A [World](/docs/deploying) stores workflow state and delivers queue messages.
+
+## Selecting a World
+
+### `WORKFLOW_TARGET_WORLD`
+
+- Surface: environment variable
+- Default: `local` outside Vercel; automatic Vercel World inside Vercel deployments
+- Selects a non-default World module.
+
+Outside Vercel, Workflow defaults to the Local World. On Vercel, leave `WORKFLOW_TARGET_WORLD` unset for the normal case; Workflow detects the Vercel deployment and selects the Vercel World automatically.
+
+Set `WORKFLOW_TARGET_WORLD` only when you want to use a custom or self-hosted World:
+
+- `local` - alias for `@workflow/world-local`.
+- `@workflow/world-postgres` - Postgres World package.
+- `./my-world.ts` - local module exporting a World, `createWorld()`, or a default factory.
+- Any package specifier - custom World package.
+
+The `vercel` alias exists for manual selection and tooling, but deployed Vercel apps do not need to set it.
+
+Export a configured World from a module when you need factory options instead of pure environment configuration:
+
+```typescript title="my-world.ts" lineNumbers
+import { createWorld } from "@workflow/world-postgres";
+
+export default createWorld({
+  connectionString: process.env.DATABASE_URL!,
+  jobPrefix: "myapp_",
+});
+```
+
+```bash title=".env"
+WORKFLOW_TARGET_WORLD="./my-world.ts"
+```
+
+## Local World
+
+The Local World is the default outside Vercel and is intended for development.
+
+### `dataDir`
+
+- Environment variable: `WORKFLOW_LOCAL_DATA_DIR`
+- Default: `.workflow-data`
+- Directory where runs, steps, events, hooks, streams, and the local manifest are written.
+
+### `baseUrl`
+
+- Environment variable: `WORKFLOW_LOCAL_BASE_URL`
+- Default: inferred from the app port
+- Full base URL used when queue messages call back into the app.
+- Overrides `port` and `PORT`.
+
+### `port`
+
+- Environment variable: `PORT`
+- Default: auto-detected
+- Local app port used to build the callback URL when `baseUrl` is unset.
+
+### `WORKFLOW_LOCAL_QUEUE_CONCURRENCY`
+
+- Factory option: none
+- Default: `1000`
+- Maximum number of concurrent local queue message handlers.
+
+### `WORKFLOW_LOCAL_QUEUE_MAX_VISIBILITY`
+
+- Factory option: none
+- Default: unlimited
+- Maximum seconds a local queue message stays hidden before the handler rechecks the run.
+
+### `recoverActiveRuns`
+
+- Environment variable: none
+- Default: `true`
+- Re-enqueues pending and running local runs when the World starts.
+
+### `tag`
+
+- Environment variable: none
+- Default: unset
+- Scopes local storage files to a tag, mainly for test isolation.
+
+### `streamFlushIntervalMs`
+
+- Environment variable fallback: `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+- Default: `10`
+- Flush interval for buffered stream writes. The World option wins when set.
+
+## Postgres World
+
+The Postgres World is a self-hosted durable backend for long-running server processes.
+
+### `connectionString`
+
+- Environment variable: `WORKFLOW_POSTGRES_URL`, then `DATABASE_URL`
+- Default: `postgres://world:world@localhost:5432/world`
+- PostgreSQL connection string used by the runtime World.
+- The `bootstrap` migration command uses the same precedence.
+
+### `pool`
+
+- Environment variable: none
+- Default: new `pg.Pool`
+- Existing `pg.Pool` to use instead of constructing one from `connectionString`.
+
+### `jobPrefix`
+
+- Environment variable: `WORKFLOW_POSTGRES_JOB_PREFIX`
+- Default: `workflow_`
+- Prefix for Graphile Worker job names.
+
+### `queueConcurrency`
+
+- Environment variable: `WORKFLOW_POSTGRES_WORKER_CONCURRENCY`
+- Default: `50`
+- Number of concurrent workers polling for jobs.
+- Also bounds concurrent parent-to-child workflow return-value polls.
+
+### `maxPoolSize`
+
+- Environment variable: `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
+- Default: `pg` default
+- Maximum size of the internal `pg.Pool` when the World creates the pool.
+
+### `namespace`
+
+- Environment variable fallback: `WORKFLOW_QUEUE_NAMESPACE`
+- Default: none
+- Queue topic namespace. For example, `custom` changes `__wkf_*` topics to `__custom_wkf_*`.
+
+### `streamFlushIntervalMs`
+
+- Environment variable fallback: `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+- Default: `10`
+- Flush interval for buffered stream writes. The World option wins when set.
+
+## Vercel World
+
+The Vercel World is configured automatically inside Vercel deployments. The platform provides the deployment ID, project ID, request authentication, queue integration, storage, and encryption material.
+
+Most applications should not set `WORKFLOW_VERCEL_*` variables on Vercel. They configure tooling that talks to a Vercel Workflow project from outside a deployment, such as the `workflow` CLI, the web UI, CI, or tests. The runtime warns if these variables are set in a deployed Vercel function because they do not control runtime configuration there.
+
+Platform-provided values such as `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, and `VERCEL_DEPLOYMENT_KEY` are read by the runtime inside Vercel deployments. Do not set them yourself.
+
+### `token`
+
+- Environment variable: `WORKFLOW_VERCEL_AUTH_TOKEN`, then `VERCEL_TOKEN`, then Vercel CLI login
+- CLI flag: `--authToken`
+- Default: inferred when possible
+- Vercel API token for external tooling. Keep it secret.
+
+### `projectConfig.environment`
+
+- Environment variable: `WORKFLOW_VERCEL_ENV`
+- CLI flag: `--env` or `-e`
+- Default: `production`
+- Vercel environment targeted by tooling. Accepts `production` or `preview`.
+
+### `projectConfig.projectId`
+
+- Environment variable: `WORKFLOW_VERCEL_PROJECT`
+- CLI flag: `--project`
+- Default: inferred from `.vercel/project.json` when possible
+- Vercel project ID.
+
+### `projectConfig.teamId`
+
+- Environment variable: `WORKFLOW_VERCEL_TEAM`
+- CLI flag: `--team`
+- Default: inferred from `.vercel/project.json` when possible
+- Vercel team ID.
+
+### `WORKFLOW_VERCEL_PROJECT_NAME`
+
+- Factory option: none
+- CLI flag: none
+- Default: inferred when possible
+- Project slug used for dashboard links.
+
+### `WORKFLOW_VERCEL_BACKEND_URL`
+
+- Factory option: none
+- CLI flag: none
+- Default: `https://api.vercel.com/v1/workflow`
+- Workflow API proxy URL for external tooling.
+
+### `VERCEL_WORKFLOW_SERVER_URL`
+
+- Factory option: none
+- CLI flag: none
+- Default: unset
+- Direct workflow-server URL override for testing or custom infrastructure. Normal deployments do not need it.
+
+### `VERCEL_QUEUE_MAX_DELAY_SECONDS`
+
+- Factory option: none
+- CLI flag: none
+- Default: `82800` (23 hours)
+- Maximum delay for one Vercel Queues continuation message when implementing `sleep()`.
+- Longer sleeps schedule another continuation when the first one fires.
+
+`VERCEL_QUEUE_MAX_DELAY_SECONDS` defaults to 23 hours because Vercel Queues message delays are capped by the message TTL, and the default TTL is 24 hours. Workflow stays inside that default and chains continuation messages for longer sleeps.
+
+### `WORKFLOW_REQUEST_TIMEOUT_MS`
+
+- Factory option: none
+- CLI flag: none
+- Default: `60000`
+- Per-request timeout for Vercel World HTTP calls to workflow-server.
+
+### `WORKFLOW_MAX_CHUNKS_PER_REQUEST`
+
+- Factory option: none
+- CLI flag: none
+- Default: `1000`
+- Maximum stream chunks written in one Vercel World request. Larger batches are split.

package/docs/deploying/world/local-world.mdx

@@ -38,7 +38,7 @@ Learn more in the [Observability](/docs/observability) documentation.
 
 ## Configuration
 
-The local world works with zero configuration, but you can customize behavior through environment variables or programmatically via `createLocalWorld()`.
+The local world works with zero configuration, but you can customize behavior through environment variables or programmatically via `createWorld()`.
 
 ### `WORKFLOW_LOCAL_DATA_DIR`
 
@@ -56,22 +56,39 @@ Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected
 
 ### `WORKFLOW_LOCAL_QUEUE_CONCURRENCY`
 
-Maximum number of concurrent queue workers. Default: `100`
+Maximum number of concurrent queue message handlers. Default: `1000`
+
+### `WORKFLOW_LOCAL_QUEUE_MAX_VISIBILITY`
+
+Maximum number of seconds a local queue message can stay hidden before the handler rechecks the run. Default: unlimited.
+
+### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+
+Flush interval, in milliseconds, for buffered stream writes. Default: `10`.
 
 ### Programmatic configuration
 
-{/* @skip-typecheck: incomplete code sample */}
-```typescript title="workflow.config.ts" lineNumbers
-import { createLocalWorld } from "@workflow/world-local";
+Options passed to `createWorld()` take precedence over the environment variables above. Export the configured World from a module and point `WORKFLOW_TARGET_WORLD` at that module:
 
-const world = createLocalWorld({
+```typescript title="my-world.ts" lineNumbers
+import { createWorld } from "@workflow/world-local";
+
+export default createWorld({
   dataDir: "./custom-workflow-data",
   port: 5173,
   // baseUrl overrides port if set
   baseUrl: "https://local.example.com:3000",
+  recoverActiveRuns: true,
+  streamFlushIntervalMs: 10, // overrides WORKFLOW_STREAM_FLUSH_INTERVAL_MS
 });
 ```
 
+```bash title=".env"
+WORKFLOW_TARGET_WORLD="./my-world.ts"
+```
+
+`createWorld()` also accepts `tag`, which scopes local storage files to a suffix. It is mainly used by test harnesses that share one `.workflow-data` directory.
+
 ## Limitations
 
 The local world is designed for development, not production:

package/docs/deploying/world/postgres-world.mdx

@@ -38,7 +38,7 @@ WORKFLOW_TARGET_WORLD="@workflow/world-postgres"
 WORKFLOW_POSTGRES_URL="postgres://user:password@host:5432/database"
 ```
 
-Run the migration script to create the necessary tables in your database. Ensure `WORKFLOW_POSTGRES_URL` is set when running this command:
+Run the migration script to create the necessary tables in your database. Ensure `WORKFLOW_POSTGRES_URL` or `DATABASE_URL` is set when running this command:
 
 <Tabs items={["npm", "pnpm", "Yarn", "Bun"]}>
 
@@ -190,15 +190,17 @@ Learn more in the [Observability](/docs/observability) documentation.
 
 All configuration options can be set via environment variables or programmatically via `createWorld()`.
 
-### `WORKFLOW_POSTGRES_URL` (required)
+### `WORKFLOW_POSTGRES_URL`
 
-PostgreSQL connection string. Falls back to `DATABASE_URL` if not set.
+PostgreSQL connection string used by the runtime World.
 
-Default: `postgres://world:world@localhost:5432/world`
+Precedence: `WORKFLOW_POSTGRES_URL` > `DATABASE_URL` > `postgres://world:world@localhost:5432/world`
+
+The `bootstrap` migration command uses the same precedence.
 
 ### `WORKFLOW_POSTGRES_JOB_PREFIX`
 
-Prefix for graphile-worker queue job names. Useful when sharing a database between multiple applications.
+Prefix for graphile-worker queue job names. Useful when sharing a database between multiple applications. Default: `workflow_`
 
 ### `WORKFLOW_POSTGRES_WORKER_CONCURRENCY`
 
@@ -208,25 +210,46 @@ This value also bounds how many parent→child workflow polls can be in flight s
 
 ### `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
 
-Maximum size of the internal `pg.Pool` used when `createWorld()` constructs the pool. Default: `10`
+Maximum size of the internal `pg.Pool` used when `createWorld()` constructs the pool. Default: the `pg` default (`10`).
 
 For higher worker concurrency, Graphile Worker recommends setting `maxPoolSize` to `10` or `queueConcurrency + 2`, whichever is larger.
 
+### `WORKFLOW_QUEUE_NAMESPACE`
+
+Queue topic namespace shared by build output and the Postgres World. Default: unset.
+
+For example, `custom` changes the queue topic prefixes from `__wkf_workflow_` and `__wkf_step_` to `__custom_wkf_workflow_` and `__custom_wkf_step_`. The value must be lowercase alphanumeric and start with a letter.
+
+### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+
+Flush interval, in milliseconds, for buffered stream writes. Default: `10`.
+
 ### Programmatic configuration
 
 {/*@skip-typecheck: incomplete code sample*/}
 
-```typescript title="workflow.config.ts" lineNumbers
+```typescript title="my-world.ts" lineNumbers
 import { createWorld } from "@workflow/world-postgres";
 
-const world = createWorld({
-  connectionString: "postgres://user:password@host:5432/database",
+export default createWorld({
+  connectionString:
+    process.env.WORKFLOW_POSTGRES_URL ?? process.env.DATABASE_URL!,
   jobPrefix: "myapp_",
+  namespace: "myapp",
   queueConcurrency: 50,
   maxPoolSize: 52, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
+  streamFlushIntervalMs: 10,
 });
 ```
 
+Options passed to `createWorld()` take precedence over the environment variables above. Export the World from a module and point `WORKFLOW_TARGET_WORLD` at that module:
+
+You can also pass an existing `pg.Pool` as `pool` instead of a connection string.
+
+```bash title=".env"
+WORKFLOW_TARGET_WORLD="./my-world.ts"
+```
+
 ## How It Works
 
 The Postgres World uses PostgreSQL as a durable backend:

package/docs/deploying/world/vercel-world.mdx

@@ -89,46 +89,79 @@ Learn more in the [Observability](/docs/observability) documentation.
 
 ## Configuration
 
-The Vercel World requires no configuration when deployed to Vercel. For advanced use cases, you can override settings programmatically via `createVercelWorld()`.
+In a Vercel deployment, you do not configure the Vercel World yourself. The platform injects everything the runtime needs, including `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, per-request OIDC tokens, and `VERCEL_DEPLOYMENT_KEY` for encryption.
+
+Do not set those platform-provided values yourself.
+
+Most users never need to set the `WORKFLOW_VERCEL_*` variables below. They are only overrides for tools running outside Vercel, such as your laptop or CI, when those tools need to inspect or test a remote Vercel Workflow project and cannot infer the project, team, token, or target environment automatically.
+
+For example, you might set them when running `workflow inspect runs --backend vercel` from CI without an interactive `vercel login`, or when running tests against a specific preview deployment. In normal local development, the CLI infers these values from your `.vercel` directory and Vercel CLI login. In a deployed Vercel function, these variables have no effect on runtime configuration, and the runtime warns if they are set there.
 
 ### `WORKFLOW_VERCEL_ENV`
 
-The Vercel environment to use. Options: `production`, `preview`, `development`. Automatically detected.
+The Vercel environment to target. Options: `production`, `preview`. Default: `production`.
 
 ### `WORKFLOW_VERCEL_AUTH_TOKEN`
 
-Authentication token for API requests. Automatically detected.
+Vercel API authentication token (secret — keep it in your environment, not in code). Falls back to `VERCEL_TOKEN`, then to your Vercel CLI login.
 
 ### `WORKFLOW_VERCEL_PROJECT`
 
-Vercel project ID for API requests. Automatically detected.
+Vercel project ID (`prj_...`).
+
+### `WORKFLOW_VERCEL_PROJECT_NAME`
+
+Vercel project name/slug, used for dashboard links.
 
 ### `WORKFLOW_VERCEL_TEAM`
 
-Vercel team ID for API requests. Automatically detected.
+Vercel team ID.
 
 ### `WORKFLOW_VERCEL_BACKEND_URL`
 
-Custom base URL for the Vercel workflow API. Automatically detected.
+Custom base URL for the Vercel workflow API proxy. Default: `https://api.vercel.com/v1/workflow`.
+
+### `VERCEL_WORKFLOW_SERVER_URL`
+
+Custom workflow-server URL for direct runtime requests, or for the proxy to forward to via `WORKFLOW_VERCEL_BACKEND_URL`. Default: unset; normal deployments should not need this.
+
+### `VERCEL_QUEUE_MAX_DELAY_SECONDS`
+
+Maximum delay, in seconds, that Workflow uses for one Vercel Queues continuation message when implementing `sleep()`. If a workflow sleeps longer than this, the runtime schedules another continuation message when the first one fires, repeating until the sleep's target time is reached. Default: `82800` (23 hours).
+
+Vercel Queues can delay messages for up to 7 days, capped by the message TTL. Because the default TTL is 24 hours, Workflow uses a 23-hour continuation hop to stay safely inside that default.
+
+### `WORKFLOW_REQUEST_TIMEOUT_MS`
+
+Per-request timeout, in milliseconds, for Vercel World HTTP calls to workflow-server. Default: `60000`. Minimum: `1`.
+
+### `WORKFLOW_MAX_CHUNKS_PER_REQUEST`
+
+Maximum stream chunks written in one Vercel World request. Larger batches are split across multiple requests. Default: `1000`. Minimum: `1`.
 
 ### Programmatic configuration
 
+`createWorld()` accepts explicit API configuration. It does not read `WORKFLOW_VERCEL_*` automatically, so pass the environment values yourself when you want a configured World module:
+
 {/*@skip-typecheck: incomplete code sample*/}
 
-```typescript title="workflow.config.ts" lineNumbers
-import { createVercelWorld } from "@workflow/world-vercel";
+```typescript title="my-world.ts" lineNumbers
+import { createWorld } from "@workflow/world-vercel";
 
-const world = createVercelWorld({
+export default createWorld({
   token: process.env.WORKFLOW_VERCEL_AUTH_TOKEN,
-  baseUrl: "https://api.vercel.com/v1/workflow",
   projectConfig: {
-    projectId: "my-project",
-    teamId: "my-team",
+    projectId: "prj_...",
+    teamId: "team_...",
     environment: "production",
   },
 });
 ```
 
+```bash title=".env"
+WORKFLOW_TARGET_WORLD="./my-world.ts"
+```
+
 ## Versioning
 
 On Vercel, workflow runs are pegged to the deployment that started them. This means:

package/docs/meta.json

@@ -10,6 +10,7 @@
     "deploying",
     "errors",
     "migration-guides",
+    "configuration",
     "api-reference"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.27",
+  "version": "5.0.0-beta.28",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -57,18 +57,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.27",
-    "@workflow/cli": "5.0.0-beta.27",
-    "@workflow/core": "5.0.0-beta.27",
-    "@workflow/errors": "5.0.0-beta.9",
+    "@workflow/astro": "5.0.0-beta.28",
+    "@workflow/cli": "5.0.0-beta.28",
+    "@workflow/core": "5.0.0-beta.28",
+    "@workflow/errors": "5.0.0-beta.10",
     "@workflow/typescript-plugin": "5.0.0-beta.5",
-    "@workflow/utils": "5.0.0-beta.5",
-    "@workflow/next": "5.0.0-beta.27",
-    "@workflow/nest": "5.0.0-beta.27",
-    "@workflow/nitro": "5.0.0-beta.27",
-    "@workflow/nuxt": "5.0.0-beta.27",
-    "@workflow/sveltekit": "5.0.0-beta.27",
-    "@workflow/rollup": "5.0.0-beta.27"
+    "@workflow/utils": "5.0.0-beta.6",
+    "@workflow/next": "5.0.0-beta.28",
+    "@workflow/nest": "5.0.0-beta.28",
+    "@workflow/nitro": "5.0.0-beta.28",
+    "@workflow/nuxt": "5.0.0-beta.28",
+    "@workflow/sveltekit": "5.0.0-beta.28",
+    "@workflow/rollup": "5.0.0-beta.28"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",