milo-cli 0.4.0

Feature release focused on making one typed function a truthful, composable
contract for terminal users, Python hosts, and MCP clients.

Highlights

• Truthful dispatch everywhere — Generated schemas are enforced across CLI,
  call, call_raw, and MCP. Unknown arguments and constraint failures now
  carry stable, repairable diagnostics instead of reaching handlers or being
  silently discarded.
• MCP Apps end to end — Typed ui:// resources, tool links, capability
  negotiation, gateway-safe URI rewriting, resource transport, verifier checks,
  and a dependency-free interactive example now form one tested contract.
• Downstream CLI adoption — Public positional and option presentation,
  command surface policy, lazy version reports, terminal renderers, shallow
  help, and selected-command parsing support established CLIs without private
  argparse mutation.
• Headless Context — Web servers, workers, and tests can inject their own
  output sink, interaction policy, and approval strategy while terminal defaults
  remain unchanged.
• Launch-ready onboarding — The README now leads with a clean-machine
  60-second CLI-to-MCP proof, backed by stricter verifier coverage and honest
  Milo/FastMCP/Typer guidance.

Added

• Public validate_arguments() enforcement and complete lazy exports for
  runtime effect types.
• Positional, Option, per-command surfaces, custom version reports, and
  terminal-only structured-result rendering.
• MCP Apps resource/tool metadata types, negotiated discovery, security
  metadata, gateway routing, and stable structured errors.
• mcp_apps_in_process, mcp_apps_gateway, and mcp_apps_transport verifier
  checks, including subprocess resource reads and clean-stdout validation.
• OutputSink, ConfirmStrategy, NullOutputSink, and host ctx= injection
  for programmatic command calls.
• MCP server/discover and explicit unsupported-version diagnostics for
  stateless negotiation preparation.

Changed

• Root and group help use command registration metadata without resolving lazy
  leaf schemas. Selected command execution builds only that command path.
• CLI.root_option_specs() is the shared immutable source for built-in and
  user-defined root option metadata.
• The public docs, launch runbook, comparison guide, and framework-neutral
  examples now lead with verified dual CLI/MCP workflows.

Fixed

• CLI, programmatic, and MCP dispatch now agree on schema constraints, unknown
  arguments, middleware repair, hidden commands, lazy-import failures, and
  protocol-safe hook errors.
• Gateway failures preserve structured child repair data and MCP Apps links
  survive collision-safe namespacing and resource reads.
• Bundled terminal components align by display-cell width and preserve wide
  Unicode; panel border styles render through the documented contract.
• Testing helpers reject incomplete saga traces and expose structured MCP repair
  data; example reducers remain deterministic and replayable.
• Onboarding, generated-project, help, form, platform-path, and version-check
  documentation now matches the executable public surfaces.

Compatibility Notes

• Python 3.14+ and the pure-Python kida-templates>=0.9.0,<0.10.0 runtime
  dependency are unchanged.
• No public command flag was removed. Context fields were appended to the frozen
  dataclass, and default stderr, TTY, and terminal confirmation behavior is
  preserved.
• Code that relied on silently ignored programmatic or MCP arguments must remove
  them or update the command signature. This is an intentional contract
  correction: agent calls now receive M-INP-005 repair data.
• MCP clients cannot invoke hidden commands and cannot inject ctx; both now
  fail with structured errors consistent with discovery.

Downstream Adoption

This is the first released version containing the generic contracts required by
the versioned Chirp CLI canary. Downstream integrations should pin milo-cli
0.4.x and advance the supported range only after their CLI, structured output,
MCP, llms.txt, and lazy-startup parity lanes pass.