[Chien Yuan Chang (chienyuanchang)]

Summary

Define the incremental user experience for azd ai cu analyze --pretty and its -p shorthand.

• Specify the boolean/default contract, single-input scope, compatible report output, and validation before authentication or file writes.
• Define Markdown/table/card presentation, terminal versus redirected output, color handling, and content/terminal safety.
• Describe related console-only analysis progress and missing-endpoint guidance.
• Include acceptance criteria and explicit non-goals; this is not a full CU CLI specification.

Related implementation

Implementation: #10784.

This separate, documentation-only PR requests experience review for the contract discussed in #10784 (comment). It includes both --pretty and -p. Approval is pending; creating this PR does not satisfy the implementation's approved-spec requirement by itself.

Review target

Primary review target: terminal pretty-printing experience spec. This branch is based on main and contains only the spec document, not the implementation commits.

Validation

• Documentation spelling and staged whitespace checks passed.
• Cross-checked the contract and acceptance criteria against the implementation and regression coverage in feat(ai-cu): add opt-in terminal Markdown previews #10784.
• No code, generated artifacts, dependency changes, or telemetry instrumentation.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
26 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🔵 Needs a closer look

Human review is still needed to validate the proposed terminal UX, including PTY-dependent rendering, spacing, URL wording, and native Windows/macOS behavior.

No open issues 🎉

What changed in this PR

This documentation-only pull request defines the terminal pretty-printing experience for azd ai cu analyze --pretty and its -p shorthand.

Changes:

• Specifies flag behavior, single-input restrictions, compatible report output, and validation ordering.
• Defines Markdown, table/card rendering, terminal width, color handling, redirection, and safety requirements.
• Documents analysis progress, missing-endpoint guidance, acceptance criteria, and non-goals.

File	Description	Review notes
cli/​azd/​extensions/​azure.ai.content-understanding/​docs/​specs/​terminal-pretty-printing.md	Defines the proposed terminal pretty-printing and related analysis feedback contract.	Update the contract-review link to reference the active implementation thread. Clarify the URL-safety wording so it describes preserving URL meaning/components while allowing one renderer decode.

_{Review effort: Lite}

[Chien Yuan Chang (chienyuanchang)]

Maybe recreate one in internal spec repo. Closing for now.