Review agent developer experience: CLAUDE.md, contribution docs, and agent UX

[crtahlin]

Goal

Ensure this repo is well-prepared for developers using AI coding agents (Claude Code, Cursor, Copilot, etc.) and for agents contributing directly.

Checklist

• CLAUDE.md / AGENTS.md exists — provides context for AI agents working on this codebase (architecture, conventions, key files, test commands)
• Contributing guide — clear instructions for how to contribute (setup, PR process, code style) that agents can follow
• README setup instructions — can an agent clone, install, and run tests without ambiguity?
• Test commands documented — single command to run full test suite, clearly stated
• Code style / linting — automated formatting so agent PRs don't fail on style
• Agent UX review — are error messages, CLI output, and API responses clear enough for an agent to understand and act on? Are suggestions surfaced?

Context

Part of the Provenance Toolkit agent-readiness initiative. As AI coding agents become standard developer tools, our repos should be easy for them to work with — both for contributing code and for using the tools programmatically.

[crtahlin]

Partial progress check (2026-04-14):

• CLAUDE.md / AGENTS.md exists — comprehensive CLAUDE.md covering project overview, Docker and local build/test, architecture, contract details, deployment instructions
• Contributing guide — no CONTRIBUTING.md
• README setup instructions — README exists
• Test commands documented — covered in CLAUDE.md
• Code style / linting — no automated formatting config
• Agent UX review — not started