feat(cli-v2): add --json global flag with structured error envelope

[iamnamananand996]

Description

Linear ticket: Refs FER-10016

Wave-2 R13 of the cli-v2 error UX/DX cleanup: a --json global flag that renders failures as a structured JSON envelope on stderr, so CI pipelines and agents can parse error details without scraping human output.

Stacked on #16040 (wave-1 renderer + --debug). Re-target to main after #16040 merges.

Envelope shape

{
  "ok": false,
  "code": "AUTH_ERROR",
  "message": "You are not logged in.",
  "hint": "Run `fern auth login`.",
  "docsLink": "https://buildwithfern.com/learn/cli/auth",
  "violations": [
    { "severity": "error", "message": "...", "file": "fern.yml", "line": 7, "column": 13 }
  ],
  "logFile": "~/.fern/v1/logs/2026-05-20T18-58-00.log",
  "debug": { "stack": "...", "causes": ["..."] }
}

• code is null for non-CliError failures (plain Error, unknown throwables).
• violations is populated for ValidationError and SourcedValidationError; the latter includes file/line/column from the YAML source.
• logFile is only set when there's something written to the per-run debug log.
• debug only appears when --debug (or FERN_DEBUG=1) is also on.
• TaskAbortSignal (Ctrl+C) still returns null — no envelope is emitted on clean shutdowns.

Changes Made

• New ErrorEnvelope / ErrorEnvelopeViolation / ErrorEnvelopeDebug types and buildErrorEnvelope() in packages/cli/cli-v2/src/errors/renderError.ts. renderError(error, { json: true }) short-circuits to the JSON path.
• packages/cli/cli-v2/src/context/GlobalArgs.ts: added json?: boolean.
• packages/cli/cli-v2/src/cli.ts: registers --json as a global yargs option (commands that already declared a local --json for success output continue to work — yargs merges the definitions).
• packages/cli/cli-v2/src/context/withContext.ts: threads args.json through to handleError, passes the log-file absolute path into the envelope, and suppresses the dim "Logs written to:" hint in JSON mode so the envelope is the only thing on stderr.
• packages/cli/cli-v2/src/commands/_internal/yargsFailHandler.ts: yargs .fail runs before parsing finishes, so it inspects process.argv for --json/--no-json/--json=true and routes through the same renderer. Help block is suppressed in JSON mode.
• Unreleased changelog entry: packages/cli/cli/changes/unreleased/cli-v2-json-error-envelope.yml (feat).

Testing

• Unit tests added/updated — 13 new renderError --json mode cases covering TaskAbortSignal, CliError, ValidationError, SourcedValidationError, plain Error, non-Error throwables, logFile, debug=true, debug=false, and ANSI-free output. All 22 renderError.test.ts tests pass; the full cli-v2 suite (725 tests) is green.
• Manual testing completed — pnpm format, pnpm lint:biome, pnpm check, pnpm turbo run compile --filter @fern-api/cli-v2 all clean.
• Updated README.md generator (N/A — public CLI surface; will land alongside R15's user-facing errors README)

Link to Devin session: https://app.devin.ai/sessions/c00fe336eaa44387a47db9083451e93c
Requested by: @iamnamananand996

[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 and CI monitoring

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}