feat(12factor-env): opt-in dotenv support

[pyramation]

Summary

Context: constructive-planning#1645 — @agentic-kit/pi hard-codes readFile(path.join(cwd, '.env')) with a hand-rolled dotenv parser as the only config lane. This gives 12factor-env a canonical home for the "environment first, .env as a local-dev convenience" rule so packages stop re-deriving it.

Purely additive — nothing about env()/cleanEnv changes, and no .env is read unless you call the new helper:

// opt-in: an input builder, never mutates process.env
const config = env(dotenv(), { DATABASE_URL: str() }, { PORT: port({ default: 3000 }) });

dotenv(options?: {
  path?: string;         // explicit file path (wins over cwd/file)
  cwd?: string;          // default process.cwd()
  file?: string;         // default '.env'
  environment?: Record<string, string | undefined>; // default process.env
  override?: boolean;    // default false: real env vars win over file values
})

Key semantics:

• Merge order defaults to environment wins (12-factor); override: true flips it for desktop-style "the project file is the source of truth" hosts.
• A missing file is not an error — the base environment is returned unchanged, so the same code path works in containers and local dev.
• Parsing uses Node's built-in util.parseEnv (Node ≥20.12; repo requires 22) — no new dependency, no hand-rolled parser. Exported as parseDotenv(source) for direct use (e.g. to replace pi's local parseEnv).

Follow-up (separate PR, tracked in #1645): migrate agentic/pi/src/context.ts onto dotenv({ cwd, environment: {}, override: true }) / injectable resolvers so headless hosts can use process.env.

Link to Devin session: https://app.devin.ai/sessions/450ce6d6659c47759c184ae6ec19a2a8
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

Superseded by a correctly-named branch PR (branch naming convention).