Gonna also share some feedback the agent had after implementing this

src-cli Architecture Improvements

1) Shared REST/RPC Client Layer

• Add a small internal package for non-GraphQL API patterns (request builder, JSON marshal/unmarshal, standard error handling, retries, polling helpers).
• Today each command reimplements similar HTTP + JSON boilerplate.

2) Typed Endpoint Clients

• For stable /api/* endpoints, use generated or hand-typed request/response structs instead of map[string]any.
• Benefits: compile-time safety, easier refactors, clearer docs in code.

3) Standard Async Operation Helper

• Create reusable polling utilities (WaitUntil, terminal-state predicates, timeout handling, jitter/backoff).
• Avoid each command implementing bespoke wait loops.

4) Unified Output Abstractions

• Standardize table/json/template output behavior across commands.
• Reuse one set of helpers for columns, formatting, and user-facing defaults.

5) Command Design Consistency

• Encourage subcommand style (resource verb) for complex workflows.
• Keep aliases for convenience, but document one canonical UX pattern.

6) Error Contract Helpers

• Normalize ConnectRPC/HTTP error decoding into structured errors.
• Expose helpers for user-friendly error messages while preserving raw details in -json/debug modes.

7) Compatibility Layer Strategy

• Explicitly isolate legacy fallbacks in a dedicated compatibility package.
• This keeps stable implementations clean and makes legacy paths easy to remove later.

8) Test Tooling

• Add shared fake API server helpers for command tests (assert request shape, provide scripted response sequences).
• Add snapshot tests for CLI output variants.

9) Docs as Tests

• Add lightweight checks that example payloads in docs match expected request structs.
• Reduces drift between docs, OpenAPI artifacts, and command implementation.

src deep-search Future UX Improvements

Command UX

• Split into subcommands for clarity:
  • src deep-search ask <question>
  • src deep-search get <id|name|url|token>
  • src deep-search list
  • src deep-search follow-up <conversation> <question>
  • src deep-search cancel <conversation>
• Keep current single-command flags as aliases for backward compatibility.

Output UX

• Add -format templates like other src commands.
• Add rich default table output for -list (name, title, state, updated).
• Add -show-sources and -show-metadata toggles for answer rendering.
• Add -raw-state to output exact state oneof mapping for debugging.

Async/Wait UX

• Add -watch mode with live spinner and elapsed time.
• Add configurable terminal-state policy flags:
  • -fail-on-error-state (default true)
  • -fail-on-timeout (default true)
• Add -timeout defaults tuned by operation (ask vs get).

Read/List UX

• Add -page-token and -all for pagination.
• Add list filters if API supports them (state/date/title query).
• Add -resolve-url=false if users want strict resource names only.

Data Model + Parsing

• Prefer typed structs over map[string]any for stable APIs.
• Keep legacy parser only in a narrow compatibility path for token URLs.
• Add schema fixtures for stable responses to prevent future shape regressions.

Testing/Verification

• Add integration tests against a test server with realistic stable payloads.
• Add golden output tests for default/plain/json modes.
• Add regression tests for malformed responses and partial answers.