feat: unify JSON envelope with the fleet core schema

Breaking JSON contract change, schema_version 2026-07-25 (ADR-0003):
the top-level errors array becomes a single error object (extras in
error.details), warnings move under meta, and meta gains profile,
duration_ms, and request_id while dropping generated_at. Adds a global
--pretty flag. Secret references migrate from the {env: NAME} map form
to the fleet-wide env:NAME string (setup wizard and docs updated; no
back-compat shim). All gocritic exclusions removed with the ~190
findings fixed in code, so .golangci.yml is canonical.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: thedavidweng

.golangci.yml

@@ -24,12 +24,6 @@ linters:
         - diagnostic
         - performance
         - style
-      disabled-checks:
-        - hugeParam
-        - rangeValCopy
-        - paramTypeCombine
-        - nestingReduce
-        - unnamedResult
     misspell:
       locale: US
     nolintlint:

JSON_SCHEMA.md

@@ -1,7 +1,9 @@
 # JSON Envelope Schema
 
 All commands emit a standard JSON envelope when invoked with `--json`.
-The current schema version is `0.1`.
+The current schema version is `2026-07-25`.
+
+Output is compact by default; pass the global `--pretty` flag for indented JSON.
 
 ## Success Envelope
 
@@ -11,60 +13,61 @@ The current schema version is `0.1`.
   "data": { ... },
   "meta": {
     "command": "transactions.list",
-    "schema_version": "0.1",
-    "generated_at": "2026-05-10T00:00:00Z",
+    "profile": "default",
+    "duration_ms": 12,
+    "schema_version": "2026-07-25",
+    "request_id": "3f8a1c2e-9b4d-4e6a-8f21-0c5d7e2a1b9c",
     "pagination": {
       "limit": 50,
       "offset": 0,
       "has_more": false
     }
-  },
-  "warnings": [],
-  "errors": []
+  }
 }
 ```
 
 ### Fields
 
 - `ok` — always `true` on success.
 - `data` — command-specific payload. Collections are object-wrapped: `data.accounts`, `data.transactions`, `data.categories`, `data.tags`, `data.recurring`.
+- `error` — omitted on success (see below).
 - `meta` — request metadata (always present).
 - `meta.command` — dot-separated command name.
-- `meta.schema_version` — semver string.
-- `meta.generated_at` — ISO 8601 timestamp.
-- `meta.demo` — `true` when running in demo mode.
+- `meta.profile` — active configuration profile (`default` unless overridden).
+- `meta.duration_ms` — wall-clock time spent handling the invocation, in milliseconds.
+- `meta.schema_version` — envelope schema version as a date string.
+- `meta.request_id` — UUID v4 generated once per invocation.
+- `meta.demo` — `true` when running in demo mode (omitted otherwise).
 - `meta.pagination` — present on list commands (`limit`, `offset`, `has_more`, `total` when available).
-- `warnings` — array of structured warning objects with `code`, `message`, `category`.
-- `errors` — empty array on success.
+- `meta.warnings` — array of structured warning objects (`code`, `message`, `category`); omitted when empty.
 
 ## Error Envelope
 
 ```json
 {
   "ok": false,
   "data": { ... },  // omitted when empty (omitempty)
+  "error": {
+    "code": "SYNC_PARTIAL_FAILURE",
+    "message": "One or more provider items failed to sync",
+    "category": "api",
+    "retryable": true
+  },
   "meta": {
     "command": "sync",
-    "schema_version": "0.1",
-    "generated_at": "2026-05-10T00:00:00Z"
-  },
-  "warnings": [],
-  "errors": [
-    {
-      "code": "SYNC_PARTIAL_FAILURE",
-      "message": "One or more provider items failed to sync",
-      "category": "api",
-      "retryable": true
-    }
-  ]
+    "profile": "default",
+    "duration_ms": 240,
+    "schema_version": "2026-07-25",
+    "request_id": "b1e6c7d4-2a3f-4c8b-9d10-6f2e5a7c3d81"
+  }
 }
 ```
 
 ### Error Fields
 
 - `ok` — always `false` on error.
-- `errors` — array of error objects (supports multi-error envelopes for partial failures).
-- Each error: `code`, `message`, `category`, `retryable`.
+- `error` — a single structured error object. When several errors are aggregated (e.g. multi-item partial failures), the primary error is the object and the remaining errors are carried in `error.details`.
+- Each error: `code`, `message`, `category`, `retryable`, and optional `details` (an array of the same shape).
 
 ## Error Taxonomy
 
@@ -113,6 +116,9 @@ Provider errors are classified as:
 
 ## Schema Versioning
 
-- **Major** — breaking contract changes.
-- **Minor** — additive compatible fields.
-- **Patch** — implementation-only changes (no schema change).
+`schema_version` is a date string. It bumps to the date of the change on any
+breaking change to the envelope shape; additive, backward-compatible fields do
+not bump it. The `2026-07-25` version unified the envelope with the CLI fleet:
+a single `error` object replaced the previous `errors[]` array, warnings moved
+under `meta.warnings`, `meta` gained `profile`, `duration_ms`, and `request_id`,
+and the redundant `meta.generated_at` was dropped.

docs/ARCHITECTURE.md

@@ -212,23 +212,18 @@ After setup finishes writing configuration, it should create or open the encrypt
 ```yaml
 database:
   path: ~/.money/data/money.db
-  encryption_key:
-    env: MONEY_DB_ENCRYPTION_KEY
+  encryption_key: "env:MONEY_DB_ENCRYPTION_KEY"
 
 providers:
   plaid:
-    client_id:
-      env: PLAID_CLIENT_ID
-    secret:
-      env: PLAID_SECRET
+    client_id: "env:PLAID_CLIENT_ID"
+    secret: "env:PLAID_SECRET"
     environment: sandbox
     products: [transactions]
     country_codes: [US]
   bridge:
-    client_id:
-      env: BRIDGE_CLIENT_ID
-    client_secret:
-      env: BRIDGE_CLIENT_SECRET
+    client_id: "env:BRIDGE_CLIENT_ID"
+    client_secret: "env:BRIDGE_CLIENT_SECRET"
 ```
 
 ## Implementation Tooling

docs/CONFIG.md

@@ -4,33 +4,27 @@
 
 ## Config Shape
 
-Secret references use YAML objects with exactly one `env` key:
+Secret references use the string form `env:NAME`, which resolves to the value of environment variable `NAME` at load time (an error is raised if it is unset):
 
 ```yaml
 database:
   path: ~/.money/data/money.db
-  encryption_key:
-    env: MONEY_DB_ENCRYPTION_KEY
+  encryption_key: "env:MONEY_DB_ENCRYPTION_KEY"
 
 providers:
   plaid:
-    client_id:
-      env: PLAID_CLIENT_ID
-    secret:
-      env: PLAID_SECRET
+    client_id: "env:PLAID_CLIENT_ID"
+    secret: "env:PLAID_SECRET"
     environment: sandbox
     products: [transactions]
     country_codes: [US]
     additional_consented_products: [investments]
     required_if_supported_products: [liabilities]
     optional_products: [auth]
-    redirect_uri:
-      env: PLAID_REDIRECT_URI
+    redirect_uri: "env:PLAID_REDIRECT_URI"
   bridge:
-    client_id:
-      env: BRIDGE_CLIENT_ID
-    client_secret:
-      env: BRIDGE_CLIENT_SECRET
+    client_id: "env:BRIDGE_CLIENT_ID"
+    client_secret: "env:BRIDGE_CLIENT_SECRET"
 ```
 
 Direct scalar values are allowed only for non-secrets such as `database.path`, `providers.plaid.environment`, `products`, `country_codes`, and Plaid Link consent product lists. Direct scalar secrets are accepted for manually edited files, but config loading emits a structured warning recommending `.env` references.
@@ -61,7 +55,7 @@ Profile names must be alphanumeric, hyphen, or underscore only; path traversal c
 7. Validate required fields for the command being executed.
 8. Return config values plus structured warnings, such as direct secrets in YAML or broad env-file permissions.
 
-Environment variables complete explicit references; they do not form a magic override chain. For example, `PLAID_SECRET` is used only when config says `secret: { env: PLAID_SECRET }` or a setup/configure command writes that reference.
+Environment variables complete explicit references; they do not form a magic override chain. For example, `PLAID_SECRET` is used only when config says `secret: "env:PLAID_SECRET"` or a setup/configure command writes that reference.
 
 Plaid Dashboard OAuth bootstrap state is stored outside YAML at `plaid-dashboard-auth.json` beside the resolved config file. It is local bootstrap state for `money plaid login`, written `0600`, and may include Dashboard access/refresh tokens plus selected `team_id` and `client_id`. Provider API credentials still use the normal `.env` plus YAML `env:` references model.
 

docs/CONTRACTS.md

@@ -1,6 +1,6 @@
 # Command Contracts
 
-`money` commands write one JSON envelope to stdout when `--json` is set. Human mode may print compact text, but automation should use JSON.
+`money` commands write one JSON envelope to stdout when `--json` is set. Human mode may print compact text, but automation should use JSON. JSON output is compact by default; pass `--pretty` for indented output.
 
 ## Envelope
 
@@ -12,21 +12,20 @@ All JSON commands use:
   "data": {},
   "meta": {
     "command": "transactions.list",
-    "schema_version": "0.1",
-    "generated_at": "2026-05-10T00:00:00Z",
-    "demo": false,
+    "profile": "default",
+    "duration_ms": 12,
+    "schema_version": "2026-07-25",
+    "request_id": "3f8a1c2e-9b4d-4e6a-8f21-0c5d7e2a1b9c",
     "pagination": {
       "limit": 50,
       "offset": 0,
       "has_more": false
     }
-  },
-  "warnings": [],
-  "errors": []
+  }
 }
 ```
 
-Errors use `ok: false` and `errors[]` entries with `code`, `message`, `category`, and `retryable`. JSON mode does not require stderr parsing.
+Errors use `ok: false` and a single `error` object with `code`, `message`, `category`, and `retryable` (plus optional `details[]` when errors are aggregated). Warnings, when present, are carried under `meta.warnings`. JSON mode does not require stderr parsing.
 
 ## Read Commands
 
@@ -133,6 +132,7 @@ All commands support:
 - `--config` (config file path)
 - `--profile` (configuration profile, default "default")
 - `-j, --json` (write JSON envelope to stdout)
+- `--pretty` (indent JSON output)
 
 The `--profile` flag selects a named configuration profile. The default profile uses `~/.money/config.yaml`; custom profiles use `~/.money/profiles/<name>/config.yaml`.
 
@@ -308,4 +308,4 @@ These commands never include Plaid API secrets, Dashboard OAuth tokens, masked s
 
 ## Monarch Compatibility Notes
 
-The command names and stdout/stderr discipline follow Monarch CLI habits where useful. `money` differs by using object-wrapped collection fields, multi-error envelopes, explicit source provenance, encrypted local storage, and BYOK Provider adapters.
+The command names and stdout/stderr discipline follow Monarch CLI habits where useful. `money` differs by using object-wrapped collection fields, a single structured `error` object (with aggregated errors in `error.details`), explicit source provenance, encrypted local storage, and BYOK Provider adapters.

docs/adr/0002-json-envelope-and-exit-codes.md

@@ -1,6 +1,6 @@
 # JSON envelope and exit-code contract
 
-Status: Accepted
+Status: Accepted (envelope shape superseded by ADR-0003; exit-code contract still current)
 
 ## Context
 

docs/adr/0003-fleet-envelope-core.md

@@ -0,0 +1,38 @@
+# Fleet envelope core
+
+Status: Accepted (amends ADR-0002)
+
+## Context
+
+`money` is one of five sibling CLIs (canvas, zenodo, flickr, monarch, money) that
+all emit a machine-readable JSON envelope. Round 1 aligned the tools on a shared
+core, but `money` still carried three shapes the rest of the fleet did not: a
+top-level `errors[]` array, a top-level `warnings[]` array, and a `meta.generated_at`
+timestamp. Divergent envelopes force agents and scripts to special-case each tool,
+which is the opposite of what a fleet-wide contract is for.
+
+ADR-0002 froze the previous shape (`{ ok, data, meta, warnings, errors }` with an
+errors array "never a single object" and `meta` carrying `command`, `schema_version`,
+`generated_at`). That decision predates the fleet-unification effort and its
+envelope clauses are superseded here.
+
+## Decision
+
+Adopt the fleet core envelope. This is a breaking change; `schema_version` becomes
+the date string `2026-07-25`.
+
+- `errors[]` collapses to a single `error` object `{ code, message, category, retryable, details? }`. When multiple errors are aggregated (e.g. multi-item partial failures) the primary error is the object and the remainder go into `error.details`. `error` is omitted on success.
+- Top-level `warnings[]` moves to `meta.warnings` (omitted when empty).
+- `meta` gains `profile` (the active configuration profile), `duration_ms` (wall-clock handling time), and `request_id` (a UUID v4 generated once per invocation).
+- `meta.generated_at` is dropped; it was redundant with request-scoped timing and non-deterministic in golden tests.
+
+Tool-specific additive `meta` fields (`demo`, `pagination`) are retained. A single
+`runtimeState.writeEnvelope` chokepoint stamps the request-scoped fields and honors
+the global `--pretty` flag, so envelope bytes cannot drift between commands.
+
+## Consequences
+
+- Consumers that read `errors[0]` must read `error`; consumers that read top-level `warnings` must read `meta.warnings`. There is no compatibility shim.
+- `request_id` gives each invocation a stable correlation id for logs and audits; `duration_ms` exposes handling latency without a wall-clock timestamp.
+- `JSON_SCHEMA.md`, `docs/CONTRACTS.md`, and every inline/e2e envelope assertion were updated to the new shape.
+- `github.com/google/uuid` is a direct dependency, matching the sibling tools.

go.mod

@@ -4,6 +4,7 @@ go 1.26.4
 
 require (
 	charm.land/huh/v2 v2.0.3
+	github.com/google/uuid v1.6.0
 	github.com/ncruces/go-sqlite3 v0.34.1
 	github.com/olekukonko/tablewriter v0.0.5
 	github.com/plaid/plaid-go/v40 v40.1.0