feat(spell-server): add dotenv loading and env validation to server config

- Extract shared env resolution module from manifest/parser.ts to
  config/env-resolver.ts (DRY across 3 parsers)
- Add 'dotenv true' toggle in server.kdl to load .env from config dir
- Add env() syntax support to server.kdl (port, auth, webhook-secret,
  goal-token) and channels.kdl (bot-token, upload-dir, default-model,
  default-project, voice API keys)
- Pre-validate all env() references at startup: scan all KDL files
  including autonomy.kdl imports, report all missing vars at once with
  actionable error showing which file needs each var and .env path
- Export parseEnvFile from @oh-my-pi/pi-utils for reuse
- Replace channels-parser local resolveEnvValue with shared resolver
- All parsers accept optional injected env map (testable, no process.env
  mutation in tests)

Author: Spell Bot

!tasks/features/FEAT-260-shared-env-resolution-module-and-env-uti.org

@@ -0,0 +1,73 @@
+#+TITLE: Shared env resolution module and env utilities
+#+STATE: DONE
+#+SESSION_ID: 14ac1a701fd08506
+#+TRANSCRIPT_PATH: [[file:/home/user/.spell/agent/sessions/-code-ora-spell/2026-04-03T11-57-18-847Z_14ac1a701fd08506.jsonl]]
+#+CUSTOM_ID: FEAT-260-shared-env-resolution-module-and-env-uti
+#+EFFORT: 2h
+#+PRIORITY: #B
+#+LAYER: lib
+
+* Initial Message
+
+enable reading from the local .env with a setting toggle on the server kdl when i run spell server and the right config is on in the kdl. show at the start which env variables have been got and which ones are missing. fail if any env required by the kdl is missing, explain with a message which config I need to add
+
+* Scope
+Extract env resolution logic from =manifest/parser.ts= into a reusable module at =config/env-resolver.ts=. Export =parseEnvFile= from =pi-utils= for .env file loading. Add env reference scanning and validation utilities used by the startup reporter.
+
+* Design
+
+** Shared resolver (=config/env-resolver.ts=)
+Moved from =manifest/parser.ts=:
+- =EnvReference= type (name, optional, defaultValue, type)
+- =parseEnvReference(value: string): EnvReference | null=
+- =splitEnvTokens(content: string): string[]=
+- =parseDefaultValue(raw: string): string | number | boolean=
+- =coerceEnvValue(ref, rawValue, expectedType, pathLabel)=
+- =resolveEnvIfNeeded<T>(value, expectedType, pathLabel, env)=
+
+New additions:
+- =EnvReferenceInfo= — =EnvReference= + =source: string= (which KDL file)
+- =scanEnvReferences(text: string, source: string): EnvReferenceInfo[]= — regex-based =env(...)= extraction from raw KDL text
+- =EnvValidationResult= — ={ loaded: EnvReferenceInfo[]; missing: EnvReferenceInfo[]; defaulted: EnvReferenceInfo[] }=
+- =validateEnvReferences(refs: EnvReferenceInfo[], env: Record<string, string | undefined>): EnvValidationResult=
+- =formatEnvReport(result: EnvValidationResult, configDir: string): string= — human-readable startup table
+
+** Export =parseEnvFile= from pi-utils
+=packages/utils/src/env.ts= — change =parseEnvFile= from module-private function to named export. No behavior change.
+
+* Sub-outline (test-first for pure functions)
+
+** define-types
+Types: =EnvReferenceInfo=, =EnvValidationResult=. File: =config/env-resolver.ts=.
+
+** write-tests
+Test the scanner, validator, and formatter in =test/config/env-resolver.test.ts=:
+- Scanner extracts =env(NAME)=, =env(NAME, default=x)=, =env(NAME, optional)=, =env(NAME, type=number)= from KDL text
+- Scanner ignores =env(= inside KDL comments (lines starting with =//-=)
+- Scanner attaches source label
+- Validator classifies refs as loaded / missing / defaulted
+- Formatter produces expected table output
+- =parseEnvFile= export works (import test)
+
+** extract-resolver
+Move functions from =manifest/parser.ts= to =config/env-resolver.ts=. Update =manifest/parser.ts= to import from the new module. Existing manifest tests must still pass.
+
+** implement-scanner-validator
+Implement =scanEnvReferences=, =validateEnvReferences=, =formatEnvReport=.
+
+** export-parseEnvFile
+Export =parseEnvFile= from =packages/utils/src/env.ts=.
+
+* Acceptance
+- =manifest/parser.ts= imports resolution functions from =config/env-resolver.ts= — no duplicated logic
+- All existing =test/manifest/env-resolution.test.ts= tests pass unchanged
+- New =test/config/env-resolver.test.ts= tests pass
+- =parseEnvFile= importable from =@oh-my-pi/pi-utils=
+
+* Files
+| File | Change |
+|---+---|
+| =packages/spell-server/src/config/env-resolver.ts= | new |
+| =packages/spell-server/src/manifest/parser.ts= | modify (import from env-resolver) |
+| =packages/utils/src/env.ts= | modify (export parseEnvFile) |
+| =packages/spell-server/test/config/env-resolver.test.ts= | new |

!tasks/features/FEAT-261-dotenv-toggle-and-env-support-in-server.org

@@ -0,0 +1,122 @@
+#+TITLE: dotenv toggle and env support in serverkdl
+#+STATE: DONE
+#+SESSION_ID: 14ac1a701fd08506
+#+TRANSCRIPT_PATH: [[file:/home/user/.spell/agent/sessions/-code-ora-spell/2026-04-03T11-57-18-847Z_14ac1a701fd08506.jsonl]]
+#+CUSTOM_ID: FEAT-261-dotenv-toggle-and-env-support-in-server
+#+EFFORT: 2h
+#+PRIORITY: #A
+#+LAYER: config
+#+DEPENDS: FEAT-260-shared-env-resolution-module-and-env-uti
+
+
+
+
+NOTE [2026-04-03]: Started Wave 2 server parser env() work: adding dotenv parsing, threading env maps through server parser, and adding focused bun tests.
+
+* Initial Message
+
+enable reading from the local .env with a setting toggle on the server kdl when i run spell server and the right config is on in the kdl. show at the start which env variables have been got and which ones are missing. fail if any env required by the kdl is missing, explain with a message which config I need to add
+
+* Scope
+Add a =dotenv= top-level node to =server.kdl= that enables loading a =.env= file from the config directory. Extend =server-parser.ts= to support =env()= references in all fields using the shared resolver.
+
+* KDL Syntax
+#+begin_example
+dotenv true
+
+http {
+  port 8787
+  auth {
+    username "admin"
+    password "env(HTTP_PASSWORD)"
+  }
+  webhook-secret "env(WEBHOOK_SECRET)"
+  goal-token "incoming" "env(GOAL_TOKEN_INCOMING)"
+}
+#+end_example
+
+=dotenv true= loads =<configDir>/.env=. =dotenv "./secrets/.env"= loads from a path relative to the config directory.
+
+When =dotenv= is absent, no .env loading occurs (backward compatible). The =env()= references still resolve against =process.env= regardless of dotenv toggle — the toggle only controls whether a .env file is loaded before resolution.
+
+* Design
+
+** =parseDotenvConfig= (separate from server config)
+The dotenv setting is loader-level config, not server runtime config. It does NOT belong in =SpellServerConfig=.
+
+#+begin_src typescript
+interface DotenvConfig {
+  enabled: boolean;
+  /** Relative path to .env file, defaults to ".env" */
+  path: string;
+}
+
+function parseDotenvConfig(kdlText: string): DotenvConfig | null;
+#+end_src
+
+** server-parser env support
+=parseServerConfig= gains an =env= parameter:
+#+begin_src typescript
+function parseServerConfig(
+  kdlText: string,
+  env?: Record<string, string | undefined>
+): SpellServerConfig;
+#+end_src
+
+All =expectStringArgument= / =expectNumberArgument= calls delegate to =resolveEnvIfNeeded= from the shared module.
+
+** loader two-pass flow
+In =loadConfig()=:
+1. Read =server.kdl= text
+2. Call =parseDotenvConfig(text)= to extract dotenv setting
+3. If enabled, load =.env= from config dir using =parseEnvFile= into =process.env=
+4. Build env map from =process.env=
+5. Parse =server.kdl= / =channels.kdl= / =autonomy.kdl= with the env map
+
+* Sub-outline
+
+** define-parseDotenvConfig
+Add =parseDotenvConfig()= to =server-parser.ts=. Parses the =dotenv= node from KDL text.
+
+** write-tests
+In =test/config/server-env.test.ts=:
+- =dotenv true= detected by =parseDotenvConfig=
+- =dotenv "./secrets/.env"= returns custom path
+- No =dotenv= node returns null
+- =env(NAME)= resolves in port (type=number), auth.username, auth.password, webhook-secret, goal-token
+- Missing required env var throws with variable name in error
+- =env(NAME, default=fallback)= works for optional fields
+- Literal values still work (backward compat)
+
+** update-server-parser
+Refactor =parseServerConfig= to accept env map. Replace local =expectStringArgument= / =expectNumberArgument= with shared =resolveEnvIfNeeded=.
+
+** update-loader
+Two-pass server.kdl loading. .env file loading when dotenv is enabled.
+
+* Acceptance
+- =parseDotenvConfig= correctly extracts dotenv settings
+- =parseServerConfig= resolves =env()= references against provided env map
+- Existing server config tests pass with no env parameter (backward compat)
+- New env() tests pass
+- =loadConfig()= loads .env before parsing when dotenv is enabled
+
+* Files
+| File | Change |
+|---+---|
+| =packages/spell-server/src/config/server-parser.ts= | modify (add env support, parseDotenvConfig) |
+| =packages/spell-server/src/config/loader.ts= | modify (two-pass loading, .env loading) |
+| =packages/spell-server/test/config/server-env.test.ts= | new |
+| =packages/spell-server/test/cli/server-start.test.ts= | modify (add dotenv integration test) |
+
+
+- Added `DotenvConfig` + `parseDotenvConfig()` to `server-parser.ts`.
+- Threaded optional env map through `parseServerConfig()` helpers so port/auth/webhook-secret/goal-token fields resolve shared `env()` references.
+- Added focused `server-env.test.ts` coverage for dotenv parsing, env map resolution, missing env failures, defaults, and literal backward compatibility.
+
+
+Completion report (server parser wave):
+- Exported `DotenvConfig` and `parseDotenvConfig()` from `packages/spell-server/src/config/server-parser.ts`.
+- `parseServerConfig(kdlText, env?)` now resolves env-backed port/auth/webhook-secret/goal-token values through the shared env resolver.
+- Added `packages/spell-server/test/config/server-env.test.ts` covering dotenv parsing, env resolution, missing vars, defaults, and literal backward compatibility.
+- Verified with `bun test packages/spell-server/test/config/server-env.test.ts` (pass).

!tasks/features/FEAT-262-unify-env-resolution-in-channels-kdl-par.org

@@ -0,0 +1,76 @@
+#+TITLE: Unify env resolution in channelskdl parser
+#+STATE: DONE
+#+SESSION_ID: 14ac1a701fd08506
+#+TRANSCRIPT_PATH: [[file:/home/user/.spell/agent/sessions/-code-ora-spell/2026-04-03T11-57-18-847Z_14ac1a701fd08506.jsonl]]
+#+CUSTOM_ID: FEAT-262-unify-env-resolution-in-channels-kdl-par
+#+EFFORT: 1h
+#+PRIORITY: #B
+#+LAYER: config
+#+DEPENDS: FEAT-260-shared-env-resolution-module-and-env-uti
+
+
+
+
+NOTE [2026-04-03]: Started delegated implementation for Wave 2: replace channels parser local env resolution with shared env-resolver, thread injected env through parser/tests, and verify targeted Bun tests.
+
+* Initial Message
+
+enable reading from the local .env with a setting toggle on the server kdl when i run spell server and the right config is on in the kdl. show at the start which env variables have been got and which ones are missing. fail if any env required by the kdl is missing, explain with a message which config I need to add
+
+* Scope
+Replace the local =resolveEnvValue()= in =channels-parser.ts= with the shared resolver from =config/env-resolver.ts=. Extend =env()= support to all string-valued fields in channels.kdl, not just voice API keys.
+
+Currently =channels-parser.ts= has its own simpler =resolveEnvValue()= that:
+- Only handles =env(NAME)= and =env(NAME, default=fallback)=
+- Reads directly from =process.env= (no injected env map)
+- Only applied to voice config API keys
+
+After this change:
+- Uses shared =resolveEnvIfNeeded= from =env-resolver.ts=
+- Accepts an injected =env= map parameter (like manifest parser)
+- =env()= works in all string fields: =bot-token=, =upload-dir=, =default-model=, voice API keys, etc.
+- Full =env()= syntax including =type== and =optional= flags
+
+* Sub-outline
+
+** write-tests
+In =test/config/channels-parser.test.ts= (extend existing):
+- =env(NAME)= resolves in =bot-token=
+- =env(NAME)= resolves in =upload-dir=
+- =env(NAME)= resolves in =default-model=
+- =env(NAME)= resolves in voice API keys (migration of existing voice-config tests)
+- Missing required env var throws
+- Literal values still work (backward compat)
+
+** update-parser
+- Add =env= parameter to =parseChannelsConfig= signature
+- Delete local =resolveEnvValue()= function
+- Replace all calls with shared =resolveEnvIfNeeded= or a thin string-specific wrapper
+- Thread env through to voice config parsing
+
+** update-loader
+Pass env map to =parseChannelsConfig()= from =loader.ts=.
+
+** update-existing-tests
+=test/config/voice-config-parser.test.ts= — update to use injected env instead of =process.env= manipulation.
+
+* Acceptance
+- Local =resolveEnvValue= removed from =channels-parser.ts=
+- =parseChannelsConfig= accepts and uses injected env map
+- All existing =test/config/channels-parser.test.ts= tests pass
+- All existing =test/config/voice-config-parser.test.ts= tests pass
+- New env() tests for bot-token, upload-dir, default-model pass
+
+* Files
+| File | Change |
+|---+---|
+| =packages/spell-server/src/config/channels-parser.ts= | modify (use shared resolver, add env param) |
+| =packages/spell-server/src/config/loader.ts= | modify (pass env to channels parser) |
+| =packages/spell-server/test/config/channels-parser.test.ts= | modify |
+| =packages/spell-server/test/config/voice-config-parser.test.ts= | modify |
+
+NOTE [2026-04-03]: Implemented channels-parser env injection: parseChannelsConfig now accepts optional env map, string fields bot-token/upload-dir/default-model/default-project resolve via shared resolveEnvString, voice API keys use shared resolver, and channels-specific local resolveEnvValue has been removed. Updated channels/voice parser tests to use injected env maps and added parser coverage for env-backed telegram string fields.
+
+
+- Completion report (2026-04-03): Replaced channels-parser local env() resolver with shared env-resolver usage, threaded optional env maps through parseChannelsConfig/voice parsing, added telegram string-field env coverage in channels-parser tests, and migrated voice parser tests away from process.env mutation to explicit injected env maps.
+- Verification: `bun test packages/spell-server/test/config/channels-parser.test.ts && bun test packages/spell-server/test/config/voice-config-parser.test.ts`

!tasks/features/FEAT-263-startup-env-validation-and-reporting.org

@@ -0,0 +1,102 @@
+#+TITLE: Startup env validation and reporting
+#+STATE: DONE
+#+SESSION_ID: 14ac1a701fd08506
+#+TRANSCRIPT_PATH: [[file:/home/user/.spell/agent/sessions/-code-ora-spell/2026-04-03T11-57-18-847Z_14ac1a701fd08506.jsonl]]
+#+CUSTOM_ID: FEAT-263-startup-env-validation-and-reporting
+#+EFFORT: 2h
+#+PRIORITY: #A
+#+LAYER: config
+#+DEPENDS: FEAT-260-shared-env-resolution-module-and-env-uti FEAT-261-dotenv-toggle-and-env-support-in-server FEAT-262-unify-env-resolution-in-channels-kdl-par
+
+* Initial Message
+
+enable reading from the local .env with a setting toggle on the server kdl when i run spell server and the right config is on in the kdl. show at the start which env variables have been got and which ones are missing. fail if any env required by the kdl is missing, explain with a message which config I need to add
+
+* Scope
+After loading =.env= (if dotenv enabled) and before fully parsing configs, scan all KDL files for =env()= references, validate against =process.env=, print a formatted status report, and fail with an actionable error listing missing variables and the =.env= path to add them to.
+
+* Output format
+
+When dotenv is enabled and some vars are missing:
+#+begin_example
+spell-server: loaded .env from /home/user/project/.spell/.env (3 variables)
+spell-server: environment check:
+  HTTP_PASSWORD        loaded
+  WEBHOOK_SECRET       loaded
+  DEEPGRAM_API_KEY     MISSING (required by channels.kdl)
+  MAX_COST             loaded (default: 10)
+
+Error: missing required environment variables:
+
+  DEEPGRAM_API_KEY     required by channels.kdl
+
+Add to /home/user/project/.spell/.env:
+
+  DEEPGRAM_API_KEY=
+#+end_example
+
+When all vars are present:
+#+begin_example
+spell-server: loaded .env from /home/user/project/.spell/.env (3 variables)
+spell-server: all 4 env references resolved
+#+end_example
+
+When dotenv is disabled but env() references exist and all resolve from process.env:
+No output (silent success, backward compatible).
+
+When dotenv is disabled and env() references are missing:
+Normal parser errors (unchanged behavior — individual parser throws on first missing var).
+
+The pre-validation scan runs only when dotenv is enabled. When disabled, the existing parser-level validation handles missing vars as before.
+
+* Design
+
+** Scan flow (in =loader.ts=)
+After dotenv loading, before full config parsing:
+1. Read all three KDL file texts (server.kdl, channels.kdl, autonomy.kdl)
+2. For =autonomy.kdl=, regex-extract =import "<path>"= directives and read those files too
+3. Call =scanEnvReferences(text, sourceLabel)= on each
+4. Deduplicate by env var name (keep first source)
+5. Call =validateEnvReferences(refs, process.env)=
+6. If =result.missing.length > 0=: print report via =console.error=, throw aggregated error
+7. If all present: =logger.debug(...)=
+
+** Import following
+Simple regex: =/^import\s+"([^"]+)"/gm= on autonomy.kdl text. Resolve relative to config dir. No recursive following of nested imports — the manifest parser catches those at parse time.
+
+** Error message
+The thrown error includes:
+- Count of missing vars
+- Each missing var name and which KDL file references it
+- The .env file path where the user should add them
+- Skeleton entries (=VAR_NAME==) ready to copy-paste
+
+* Sub-outline
+
+** write-tests
+In =test/config/env-startup-validation.test.ts=:
+- Full config dir with dotenv enabled + all vars present: loads successfully, no error
+- Full config dir with dotenv enabled + missing required var: throws with var name and source file
+- Full config dir with dotenv enabled + var with default: loads successfully (default used)
+- Multiple missing vars: error message lists all of them, not just the first
+- Manifest with =import= directive: imported file's env() refs are also scanned
+- No dotenv node: no .env loading, env() resolves from process.env directly
+- .env file missing when dotenv enabled: warns but continues (the .env file itself is optional — it's the env vars that are required)
+
+** implement-scan-step
+In =loader.ts=, add the scan flow between dotenv loading and config parsing.
+
+** implement-report
+Wire =formatEnvReport= and error throwing in =loader.ts=.
+
+* Acceptance
+- =spell server= with dotenv enabled and all vars present: server starts, log shows env loaded count
+- =spell server= with dotenv enabled and missing required var: server fails with clear error listing all missing vars, their source files, and .env path
+- =spell server= without dotenv: no behavioral change (backward compat)
+- All missing vars shown in one error (not one-at-a-time failures)
+
+* Files
+| File | Change |
+|---+---|
+| =packages/spell-server/src/config/loader.ts= | modify (scan + validate + report) |
+| =packages/spell-server/test/config/env-startup-validation.test.ts= | new |