CLI Presentation Contract

The CLI presentation contract separates operation facts from terminal policy. Commands and application services produce semantic results; the CLI root decides once how those facts reach a person or machine.

Start with Command Discovery for the graph that selects the command.

One Semantic Result

OperationResult carries:

• success, no-op, planned, partial, degraded, conflict, or failed status;
• planned and completed changes;
• warnings and degradations;
• per-action conflicts and handled failures;
• next actions.

It carries no glyphs, terminal prose, color, prompt, animation, or exit code. Command-stopping expected failures remain typed until the outer boundary.

One Root Boundary

Effect v4 command execution does not expose a leaf handler result from Command.runWith. Each semantic leaf therefore publishes its result once through the root presentation sink. The root supplies that sink, selects the output mode, renders the captured outcome, and owns stdout, stderr diagnostics, and process exit status.

command -> application facts -> OperationResult -> root sink -> selected presenter
                                                       |-> interactive
                                                       |-> plain
                                                       `-> JSON

JSON takes precedence when requested, stays non-interactive, and writes one valid document. Redirected plain output is deterministic and contains no ANSI. Unexpected diagnostics stay off JSON stdout.

Prompts remain an input concern. Their interaction boundary owns reader creation, keyboard and raw-terminal state, and exact cleanup; it does not become part of OperationResult.

Renderer Ownership

One production renderer owns semantic hierarchy, wrapping, theme, glyphs, compact command headings, and interactive-versus-plain policy. The large HI title is limited to root help, the root screen, and explicit welcome flows.

The developer catalog consumes that renderer in one direction. It exercises six environment anchors with 11 frames each, 66 frames total, across dark, light, no-color, standard-width, and narrow-width conditions. It has no command side effects and does not ship in the npm package.

Current screenshot evidence lives under apps/cli/test-fixtures/ui-catalog/screenshots/. Those repo paths are the durable evidence targets; commit-specific GitHub links remain pending the convergence commit SHA.

Preserved Contracts

• IP322 operator results retain scope, immutable identity, compatibility, legacy observations, project roots, agent bindings, mixed outcomes, guarded retry context, removal barriers, reinspection facts, and reload guidance.
• IP323 baseline-aware commands retain stable, bundled, and exact-version behavior.
• Product logic remains in the current application services and platform layers.

This article explains the contract. The executable result schema, recursive registry, root sink, renderer, and tests remain the authorities.