---
summary: Actionable startup errors — ZodError converted to ConfigurationError banner, parseEnvConfig helper, maintenance skill rewrite, dep sync
breaking: false
---

# 0.5.0 — 2026-04-20

Fixes the "raw ZodError on startup" UX problem (#35) at the framework level — every consumer server now gets an actionable configuration error banner instead of a JSON dump with a stack trace when env vars are missing. Adds an opt-in `parseEnvConfig` helper for env-var-aware error messages, rewrites the `maintenance` skill around the real workflow, and cleans up package.json resolutions after `bun update --latest`.

## Added

- **`parseEnvConfig(schema, envMap, env?)`** (#35) — new export from `/config`. Maps schema paths to env var names so validation errors name the actual variable at fault (`MY_API_KEY is missing`) instead of the internal Zod path (`apiKey: expected string`). Opt-in; servers that keep calling `schema.parse(process.env)` still benefit from framework-level error formatting. Fully tested (7 cases covering valid input, defaults, single/multi missing vars, fallback to path, default `process.env`).
- **Framework-level ZodError conversion at startup** (#35) — `composeServices` now wraps the `setup(core)` invocation in a `try/catch`. A `ZodError` propagating up is converted to a `ConfigurationError` (via `configurationError()`), and `createApp` prints a formatted banner to `stderr` and exits with code `1`. Full stack trace is gated behind `DEBUG=true`. Banner uses ASCII dividers for universal log-capture compatibility. `McpError` instances from `setup()` pass through unchanged; non-Zod errors are preserved.
- **`skills/maintenance/SKILL.md`** — rewritten (v1.2 → v1.3) around the two-mode flow: (A) full dependency-update workflow and (B) post-update review. Step 3 delegates to the `changelog` skill, Step 4 adds a framework-specific adoption-check table plus a fresh-read template review, Step 5 introduces a two-phase skill sync (package → project → agent dirs), Step 7 uses `bun run rebuild` (preferred over `bun run build`).

## Changed

- **Dependencies updated** — `@cloudflare/workers-types` → `^4.20260420.1`, `@supabase/supabase-js` (dev + peer) → `^2.104.0`, `bun-types` → `^1.3.13`, `vite` → `8.0.9`.
- **`package.json` resolutions cleanup** — removed six redundant pins (`@hono/node-server`, `chrono-node`, `diff`, `dotenv`, `hono`, `zod`) that duplicated direct or peer dependencies. Bumped two stale transitive pins: `brace-expansion` `1.1.13 → 1.1.14`, `path-to-regexp` `8.4.0 → 8.4.2`. Kept six security/compat pins at latest-in-major (`flatted`, `handlebars`, `lodash`, `picomatch`, `protobufjs`, `yaml`). Lockfile shrank by 92 lines confirming the redundancy was real.
- **Framework `CLAUDE.md` / `AGENTS.md`** — expanded `runtimeCaps` inline definition, added `parseEnvConfig` to the `/config` exports table, added auth scope naming convention table, elevated form-client safety to the Adding a Tool section, clarified server-config precedence (`package.json` → `name`/`version`), modernized the Commands table (`rebuild`, `format`, corrected `build`/`devcheck` descriptions), replaced the post-commit "Publishing" paragraph with a pointer to the `release` skill. Removed the standalone "Code Navigation" and "Subagent Rules" sections (moved to the global system prompt).
- **Template `CLAUDE.md` / `AGENTS.md`** — removed the First Session Bun-migration step (kept dual-compat), added a "Runtime:" note above the Commands table (both `npm run` and `bun run` work), updated `server-config.ts` example to use `parseEnvConfig`, expanded the forbidden `z.*` list, updated the maintenance skill description, added `add-app-tool` to the skill list in `AGENTS.md` (sync fix).
- **`skills/api-config/SKILL.md`** — updated server-config example to use `parseEnvConfig`.
- **`skills/setup/SKILL.md`** — added `npx` prefix, clarified bootstrap (creates dir) vs. Phase B refresh (existing only).
- **`README.md`** — fixed `rebuild` description (`clean + build`), removed stale `template_echo_app` row (absorbed into `template_data_explorer`), corrected `devcheck` description to include MCP definition linting + audit + outdated.

## Tests

- **9 new test cases**: 7 in `tests/unit/config/parseEnvConfig.test.ts` (valid parsing, defaults, env var names in errors, multiple missing vars, fallback to path, default `process.env` source), 2 in `tests/unit/core/app.test.ts` (ZodError from `setup()` converts to `ConfigurationError`, non-Zod errors pass through unchanged).
- Full suite: **2248 passed** / 10 skipped, 0 regressions. `bun run devcheck` green (typecheck, biome, depcheck, security, outdated, all tests). 0 vulnerabilities, 0 outdated after dep sync.
