Version Packages (beta)

.changeset/hook-claim-guarded-release.md

@@ -0,0 +1,5 @@
+---
+'@workflow/world-local': patch
+---
+
+Fix a stalled hook token claim release deleting the next claimant's live claim

.changeset/hook-received-after-dispose.md

@@ -0,0 +1,5 @@
+---
+'@workflow/world-local': patch
+---
+
+Fix a `resumeHook` racing `hook.dispose()` being recorded after the disposal, which corrupted the receiving run's replay

.changeset/world-factories-create-world.md

@@ -0,0 +1,12 @@
+---
+"@workflow/builders": patch
+"@workflow/world-local": patch
+"@workflow/world-postgres": patch
+"@workflow/world-vercel": patch
+"@workflow/core": patch
+"@workflow/next": patch
+"@workflow/nest": patch
+"workflow": patch
+---
+
+Standardize first-party World packages on `createWorld()`, support relative target World modules consistently, and align the Postgres World `DATABASE_URL` fallback with bootstrap.

AGENTS.md

@@ -186,6 +186,7 @@ This project uses pnpm with workspace configuration. The required version is spe
 - README.md files in each package must accurately reflect the current functionality and purpose of that package
 - READMEs should not contain outdated or incorrect information about package capabilities
 - When modifying package functionality, ensure corresponding README updates are included
+- Document every user-configurable environment variable in the docs.
 - When modifying skill files in `skills/`, always bump the `version` field in the frontmatter metadata
 
 ### Docs Preview Links in PR Descriptions

docs/content/docs/v5/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.

docs/content/docs/v5/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.