Epic: Make polkadot-cli agent-ready

Epic: Make polkadot-cli Agent-Ready

Problem

The dot CLI is well-built for human use, but AI agents and MCP server wrappers can't reliably consume its output. Only query and const support --output json — transaction output is spinner-based colored text, inspect/chain/account commands are text-only, and errors are unstructured strings. This makes the CLI unusable for programmatic automation without fragile text parsing.

Goal

Transform dot into the definitive tool for AI agents to investigate on-chain state, decode data, and orchestrate transactions on Polkadot — with structured, predictable output for every command.

Design Principles

1. Structured, deterministic output is the highest-leverage change — an agent calling dot tx ... --output json and getting back a JSON object with txHash, status, events can operate autonomously
2. Errors are data, not messages — agents need {"error":true,"code":"E_CONNECTION","message":"..."} to decide whether to retry or report
3. Introspection without prior knowledge — an agent that can dot inspect --output json and dot decode can figure out anything on any chain
4. Composability before new features — making existing commands machine-readable is more valuable than adding new ones

Sub-Issues

Phase 1 — Foundation (structured output everywhere)

• #64 — --output json for tx, inspect, chain, account commands
• #65 — Structured error output with error codes and context + granular exit codes

Phase 2 — New introspection commands

• #66 — dot decode command for call data, storage values, events
• #67 — dot info command for chain identity (token, decimals, SS58 prefix, runtime version)

Phase 3 — Batch operations

• #68 — Batch query support via stdin JSON

Phase 4 — Real-time monitoring

• #69 — dot watch blocks|storage|events with NDJSON streaming

Priority

Phase 1 is the foundation — everything else depends on it. Phase 2 adds high-value introspection. Phases 3-4 are efficiency and monitoring capabilities.

MCP Server Use Case

An MCP server wrapping this CLI would:

1. dot info --output json on startup to discover chain properties
2. dot inspect --output json to enumerate pallets/calls/storage
3. dot query ... --output json for state reads
4. dot tx ... --output json for writes, parsing NDJSON for progress
5. dot decode call 0x... --output json for opaque hex data

All of this requires Phase 1 + Phase 2 to work.

Start by reviewing the Phase 1 sub-issues, #64 and #65, since this epic identifies structured output and errors as prerequisites. Then use the later sub-issues (#66–#69) to understand the dependent scope; this epic is complete when the planned commands and error handling support predictable machine-readable operation.