fix: make authentication remediation safe for headless use

[francoischalifour]

Why

The CLI’s first-run authentication guidance was optimized for an interactive human terminal, but it was also emitted to agents, JSON consumers, and non-TTY environments.

That created several rough edges:

• doctor led headless callers toward browser login or interactive --scope configuration, neither of which can complete safely in automation.
• Some remediation examples placed secrets directly in command arguments.
• A failed lakehouse query said only “No credentials,” making the affected authentication plane unclear.
• Login and configure errors include multiple lines of guidance, but the human error renderer sanitized their newline characters into literal \x0a.
• Configuration failures also appended a command EXAMPLES section, which is useful for parser/usage errors but noisy and misleading when configuration is the actual problem.
• Documentation promises a [ERROR] prefix, while the CLI rendered ERROR.

This PR keeps the existing interactive path for humans while making failure guidance safe and actionable for programmatic callers.

What changed

Context-aware doctor remediation

doctor now carries an explicit interactive property in its check context. It is true only for a human terminal with TTY stdin and without --json or --agent.

For an interactive human terminal, doctor preserves the existing login-first guidance:

Run: altertable login
Or run: altertable profile configure --scope <plane>

For --agent, --json, or non-TTY stdin, doctor instead provides plane-specific, non-interactive remediation.

Management authentication:

Run: printf '%s' "$KEY" | altertable profile configure --api-key-stdin --env <name>
Or set: ALTERTABLE_API_KEY and ALTERTABLE_ENV

Lakehouse authentication:

Run: printf '%s' "$PASSWORD" | altertable profile configure --user <username> --password-stdin
Or set: ALTERTABLE_BASIC_AUTH_TOKEN or ALTERTABLE_LAKEHOUSE_USERNAME and ALTERTABLE_LAKEHOUSE_PASSWORD

The same mode-aware recommendations are used for failed management and lakehouse API checks, not only missing credentials. This avoids directing agents toward a browser or interactive wizard after a probe failure.

Safe non-interactive login and configure guidance

When login is invoked without an interactive terminal, its error now recommends piping an API key through --api-key-stdin or using management environment variables.

The non-TTY profile configure error similarly replaces the API-key-on-argv example with --api-key-stdin. This avoids suggesting that secrets be exposed in process listings.

Clearer lakehouse query failures

The missing credential error raised by the lakehouse query path now says “No lakehouse credentials,” making it clear that the data-plane authentication is missing rather than management authentication.

Human error presentation

Human-readable errors now:

• Use the documented [ERROR] prefix.
• Preserve trusted multiline messages as actual terminal lines.
• Continue sanitizing terminal control characters on each rendered line.
• Suppress command examples for configuration errors; examples remain available for usage and parser errors.

JSON error envelopes are unchanged.

Tests

Added or updated coverage for:

• JSON doctor remediation for both authentication planes.
• Non-TTY human doctor remediation.
• Interactive human doctor remediation retaining login-first behavior.
• Agent-mode doctor remediation even when stdin is a TTY.
• API-probe remediation in non-interactive mode.
• Missing query credentials identifying the lakehouse plane.
• Multiline login and profile configure errors.
• [ERROR] rendering and multiline sanitization.
• Suppression of command EXAMPLES for configuration failures.

[albert20260301]

Required before merge: rename this PR with a Conventional Commit prefix (for example, fix(cli): make authentication remediation safe for headless use). The semantic-title check is currently the only failing check; the rest of the CI matrix is green.

[albert20260301]

Title corrected and required checks are now green; approving.