feat(cases): fix create flag path, add comment subcommands, split case-management agent

[avidal]

Summary

Two related changes bundled under "improve case management":

1. CLI fixes for pup cases:

   • cases create flag path was sending malformed JSON (type_id stuffed into data.attributes.type instead of data.attributes.type_id, no way to attach a project relationship). Replaced the hand-rolled JSON with the typed CaseCreateRequest from the API client.
   • Added --project-id <uuid> flag to cases create so the flag path can assign a project on create (previously only --file could).
   • Added cases comment <case-id> --body "..." and cases delete-comment <case-id> --comment-id <id> subcommands wrapping comment_case / delete_case_comment. Previously the only path to commenting was raw pup api -X POST v2/cases/<id>/comment with hand-built JSON.
   • Added cases update-description <case-id> --description "..." subcommand wrapping update_case_description. The API method existed but wasn't exposed. Combined with the comment-API gaps, the description is the only case-level surface that's both updatable and discoverable via CLI, so this unlocks the "synthesize rollup status in the description" workflow.
   • Changed cases search --page-number default from 0 to 1. The API rejects 0 with page number must be > 0, so the documented default never produced a successful call.
   • Extracted a shared parse_priority helper (was duplicated between create_from_flags and update_priority).

2. Agent docs refactor — extract case-management from incident-response:

   • Created agents/case-management.md covering the full pup cases ... surface. Case Management is a standalone Datadog product used by Incident Response, Error Tracking, Security Signals, and ad-hoc operator workflows — burying it inside incident-response made it harder for non-incident consumers to find.
   • Slimmed agents/incident-response.md (834 → 714 lines) to reference case-management for case ops, keeping only the short incident-flow snippets that chain into case actions.
   • Updated agents/error-tracking.md to point at the new agent for its case mention.
   • Fixed inaccurate CLI examples that didn't match the actual pup CLI (e.g., pup cases list → pup cases search; pup cases update CASE --status=X → pup cases update-status CASE --status X; --user=<email> → --user-id <uuid>; etc.).

Why these came up together

These fixes surfaced while using pup cases end-to-end against real cases — opening cases, leaving PR-link comments, synthesizing rollup status, etc. The CLI gaps (no --project-id, malformed create body, no comment subcommand, no description-update subcommand, --page-number 0 rejected) forced repeated raw-API workarounds, and the agent docs documented behavior that didn't match the actual CLI. Single PR keeps the "improve case management" thread coherent rather than splitting closely-related fixes.

Changes

CLI (src/)

• src/commands/cases.rs — rewrote create_from_flags to use typed CaseCreateRequest + add project_id: Option<&str> parameter
• src/commands/cases.rs — new comment, delete_comment, and update_description functions
• src/commands/cases.rs — extracted parse_priority helper; update_priority now uses it
• src/main.rs — cases search --page-number default → 1
• src/main.rs — new project_id flag on the Create clap struct
• src/main.rs — new Comment, DeleteComment, and UpdateDescription clap variants + routing

Tests

• src/commands/cases.rs:tests — added tests for create_from_flags (happy path + with --project-id + invalid priority), comment, delete_comment, update_description, parse_priority (valid + invalid). All 13 case tests pass.

Docs (agents/)

• agents/case-management.md — new, ~290 lines, full case CLI surface + known API gaps (no list-comments endpoint, comment text not search-indexed, comment_count always 0 on get and only populated by search). Recommends synthesizing rollup-style status in the description rather than comments when CLI discoverability matters.
• agents/incident-response.md — slimmed to 714 lines, references case-management for case ops, fixed inaccurate CLI snippets in remaining workflow sections.
• agents/error-tracking.md — pointer to case-management for its case mention.

Test plan

• cargo build — clean
• cargo test --bin pup cases:: — 13 tests pass
• cargo fmt --check — clean
• cargo clippy -- -D warnings — clean
• Manual verification against live cases:
  • pup cases get <human-key> — works with the human key
  • pup cases search --query "project_id:<uuid>" — no --page-number needed (default 1)
  • pup cases comment <case-id> --body "..." — posts; response includes the new comment id
  • pup cases delete-comment <case-id> --comment-id <id> — deletes; second-delete returns 404 confirming the first took effect
  • Search-indexing observation: comment text is NOT indexed (free-text queries for unique comment substrings return 0); title/description text IS indexed

Known API gaps (not addressed in this PR — upstream Case Management API team)

• No list-comments endpoint at this API client revision; documented in the new case-management agent.
• comment_count is always 0 on the get_case response — only populated by search_cases results.
• search_cases does not index comment text (title and description only).

The new agent documents these so users know to fall back to the UI for comment-based discovery.