feat: agent-ready CLI and embedded MCP server

[nsollazzo]

Makes fic zero-shot drivable by coding agents — Phases 2+3 of the original design (CLI → Skill → MCP). Inspired by the positronick CLI's agent surface and the go-api-cli playbook.

What changed

Structured error contract

• JSON error envelope on stderr in json mode (the default): {"error":{"code","message","hint"?,"fields"?,"totals"?}}; --output table keeps human plaintext. Exit codes 0–7 unchanged.
• The error code is the error's canonical identity (fic.core.errors.error_code), shared by the CLI envelope and the MCP tool-error surface so they can't disagree.
• New console entry point renders click usage errors (exit 2) through the same envelope.

fic agent-docs — self-describing manual (JSON, or markdown via --output table) walking the live Typer tree: every command, flag, exit code, and the envelope shape. Command descriptions and the allowed --type values were added so the CLI surface is self-sufficient.

fic mcp serve — embedded MCP stdio server (fic/mcp/) exposing 13 tools over fic.core via per-resource dispatch adapters. Reads are free; the 6 write tools take a required boolean confirm (fail-closed, checked before any network), and errors carry the code prefixed into the tool message ([not_found] …). The mcp SDK is an optional fic[mcp] extra, imported lazily so the base CLI never needs it. TTY guard prints client setup instead of hijacking the terminal.

Write-gate parity — docs convert and einvoice send now require --yes (extracted to a shared require_yes), matching the MCP confirm gate; a bad/missing document type is now a recoverable validation error (exit 4).

Docs — README "Use with an AI agent" section, skills/fic/SKILL.md, AGENTS.md, and the design spec (with its adversarial-review resolutions).

How it was verified

• 155 tests pass; ruff + mypy clean; core-purity guard intact (no network in tests).
• Drove the real CLI and a real MCP stdio session against the live account: a read returned 22 clients; fic_delete without confirm refused as a tool error with no network call; missing/invalid type → recoverable validation error; MCP errors arrive as [not_found] … / [validation] ….
• Shaped by two adversarial review rounds (pre-code design review + post-code red-team), each of which caught real blockers (a pydantic confirm-coercion bypass; a documented-but-missing --yes gate; the MCP error-code contract gap) that were fixed and re-verified.

🤖 Generated with Claude Code