feat: improve human and agent experience

[francoischalifour]

This PR improves the CLI experience across both human and agent workflows.

For people using the CLI directly, output is now much easier to read, scan, and act on. Tables, query results, management responses, configure flows, context display, help text, and errors have been revisited with clearer spacing, better alignment, safer truncation, terminal-aware styling, and more useful summaries. The goal is for every screen to answer “what happened?”, “what matters?”, and “what should I do next?” without forcing users to parse raw API-shaped output.

For agents and scripts, this introduces an explicit --agent mode that favors stable, JSON-consumable output and disables terminal affordances like colors, pagers, and human-only formatting. Human output can now stay optimized for readability, while machine consumers get structured data they can reliably parse.

Preview

Screenshot.-.Ghostty.-.Caaltertable-cli.-.2026-06-27.at.18.53.13.mp4

What changed

• Added a global --agent preset for structured JSON output without pager, color, or terminal styling.
• Improved human-readable output across CLI screens, including query results, management commands, profile/configuration views, context, and API route listings.
• Added terminal-aware table rendering with better column sizing, alignment, truncation, and wide-output handling.
• Improved query display with --layout auto|table|line, --max-width, JSON/CSV/Markdown formats, type-aware cell formatting, relative timestamps, UUID shortening, and redaction for sensitive-looking fields.
• Added an interactive altertable configure wizard with plane-specific flows for management and lakehouse credentials.
• Added altertable context as the clearer replacement for whoami, showing the active profile, environment, planes, credentials status, and authenticated identity when available.
• Improved help/usage output with examples and more readable sections.
• Added --no-color support and centralized terminal styling behavior.
• Expanded tests around formatting, command output modes, configure flows, context, global flags, pagination, and scripting behavior.
• Updated README and development docs to reflect the new human and agent output contracts.

Why

The CLI serves two different audiences:

1. Humans reading terminal screens.
2. Agents, scripts, and CI systems consuming structured output.

Before this change, those needs competed with each other. Human output had to stay close to raw shapes so it remained scriptable, while scripts had to account for terminal-oriented formatting. This PR separates those concerns.

Human mode is now designed for clarity and scanability. Agent mode is designed for predictable structured consumption.

Testing

• Added and updated unit coverage for output rendering, query formatting, terminal styling, configure flows, context, global flags, and scripting contracts.
• Updated shell integration coverage for human and machine-readable command behavior.

[albert20260301]

Local verification is failing for me with the full suite:

bash scripts/verify.sh
...
3 tests failed:
- renderAltertableUsage active context > shows active context on root help when stdout is a TTY
- errors > renderCliError formats CliError
- errors > unknown errors render without stack traces

The failures look order-dependent. Running the failing test files alone passes, but in the full suite earlier terminal/color tests leave color enabled for later assertions, so renderCliError returns \u001b[31mERROR\u001b[39m x where the test expects plain ERROR x, and the root help output is colorized enough to miss the plain PROFILE assertion.

Please make the terminal color test setup/teardown hermetic. The likely culprit is the query-format color helper deleting/restoring only part of the env/state; it should restore NO_COLOR, TERM, FORCE_COLOR, ALTERTABLE_COLOR, TEST, CI, TTY flags, and setTerminalColorMode consistently after enabling color.