API fails to boot from a copied .env.example: blank VERCEL_* values rejected by config schema

Summary

Copying .env.example to .env — the documented first step of the self-host quickstart — produces an instance whose API crashes at startup with a ZodError, because the example file ships several optional keys with empty values.

Environment

• Windows 10 (10.0.26200), Node v22.23.2, zod 4.4.3
• facility at ae68401

Reproduction

1. cp .env.example .env (or let pnpm dev create it)
2. Fill in the required values
3. Start the stack

Actual

The API process exits during import:

services\api\src\config.ts:187
  const parsed = EnvSchema.parse(env);
                           ^
ZodError: [
  { "code": "too_small", "minimum": 1, "path": [ "VERCEL_TOKEN" ],
    "message": "Too small: expected string to have >=1 characters" },
  { ... "path": [ "VERCEL_OIDC_TOKEN" ] ... },
  { ... "path": [ "VERCEL_TEAM_ID" ] ... },
  { ... "path": [ "VERCEL_PROJECT_ID" ] ... }
]
    at readConfig (services\api\src\config.ts:187:28)
    at <anonymous> (services\api\src\dev.ts:4:16)

Expected

Optional credentials that are present but blank are treated as unset, and the API boots.

Root cause

.env.example declares these keys with no value (lines 44-47):

VERCEL_TOKEN=
VERCEL_OIDC_TOKEN=
VERCEL_TEAM_ID=
VERCEL_PROJECT_ID=

dotenv loads a bare KEY= as an empty string rather than omitting the key, which is easy to confirm:

VERCEL_TOKEN         present=true value=""
VERCEL_OIDC_TOKEN    present=true value=""
VERCEL_TEAM_ID       present=true value=""
VERCEL_PROJECT_ID    present=true value=""

The schema marks the fields optional but validates them with min(1), so "" counts as present and fails:

VERCEL_TOKEN: z.string().trim().min(1).optional(),

z.string().trim().min(1).optional() | absent -> ok | "" -> FAIL (too_small) | "tok" -> ok

Because readConfig uses EnvSchema.parse rather than safeParse, this is fatal rather than a warning.

OptionalUrl in the same file already normalizes blank strings to undefined, so the intended behavior is clear and the affected keys are simply missing that treatment. The same pattern applies to FACILITY_AWS_CODEBUILD_PROJECT, FACILITY_AWS_CODEBUILD_CACHE_BASE_LOCATION and PACKAGE_REGISTRY_TOKEN.

Suggested fix

Normalize blank strings to undefined before validation for these optional fields, so an unset credential stays unset while a whitespace-only value is still rejected rather than silently accepted.

Happy to open a PR for this.

In services/api/src/config.ts, read EnvSchema and the existing OptionalUrl normalization; then check how services/api/src/dev.ts calls readConfig. Reproduce with .env.example and pnpm dev, and verify that blank optional values allow startup while whitespace-only values remain rejected.