Epic: agent-grade CLI contract — uniform JSON envelope, error codes, `changed` reporting, structured plan output

[goosewobbler]

From the July 2026 direction review (§1.3a). Foundation epic — humans, CI, and agents share one surface, and later roadmap items ride on this output contract.

Scope

• Uniform --json envelope across all commands: { schemaVersion, status, data, errors[], warnings[] }. VersionOutput remains the data payload for version — the envelope wraps, it doesn't replace (manifest-compat invariant).
• Structured error codes with retry semantics (retryable: true/false, category), replacing prose-only errors in JSON mode.
• changed reporting: a boolean distinguishing "did work" from "already in desired state" — publish already knows this (skip-if-published); surface it.
• Dry-run as a structured plan diff: the version→notes→publish split is already a plan/apply architecture; expose dry-run output as a machine-readable plan.
• Stream discipline: data on stdout, diagnostics on stderr, never mixed; no interactive prompts on CI paths.
• Update docs/cli.md; JSON contract remains stable across minor versions per the existing guarantee.

Non-goal

An MCP server — decided against in ROADMAP.md (the CLI contract + skill is the agent surface).