Document configuration environment variables (v5)

.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.

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