feat: address all 9 agent-readiness audit findings

[jklaassenjc]

Summary

Addresses all 9 findings from the agent-readiness audit (score: B/77%):

Token Efficiency:

• TE-8: Add --brief flag for compact output (first 2 default fields, ndjson format)

Self-Describing:

• SD-5: Add AGENTS.md with comprehensive agent context documentation
• SD-7: Add actionable error messages for timeout, cancellation, and connection errors
• SD-8: Group 39 top-level subcommands into 7 logical categories in help output

Safety:

• SA-2: Reject path traversal sequences in resource identifiers
• SA-3: Reject control characters in resource identifiers
• SA-4: Add --dry-run as global alias for --plan, covering all 25 delete commands
• SA-5: Add --if-not-exists idempotency flag to users create and groups user create

Predictability:

• PV-1: Add --timeout flag to bound execution time via context deadline

Closes #1, #2, #3, #4, #5, #6, #7, #8, #9

Test plan

• make test passes
• make build succeeds
• Verify --dry-run on a delete command shows plan output
• Verify --brief on a list command shows compact 2-field ndjson
• Verify --timeout 1ms on a slow command exits with timeout error
• Verify path traversal input (../../../etc/passwd) is rejected
• Verify jc --help shows grouped command categories
• Verify jc users create --if-not-exists returns existing user

🤖 Generated with Claude Code

---

Note

Medium Risk
Moderate risk: touches global CLI flag handling, output formatting, and identifier resolution, which can affect many commands’ behavior and error reporting. Changes are largely additive but may alter defaults/outputs in subtle ways (e.g., --brief JSON switching to NDJSON, stricter identifier validation).

Overview
Improves agent/automation ergonomics across the CLI by adding global flags: --brief (token-efficient output that trims to the first 2 default fields and emits NDJSON for JSON output), --dry-run (alias for --plan), and --timeout (applies a context deadline to commands).

Adds idempotent creation via --if-not-exists for jc users create and jc groups user create, returning the existing resource instead of failing when the name already exists.

Hardens and clarifies behavior by rejecting path traversal/control characters in resource identifiers during resolution, improving error mapping for timeouts/cancellation/connectivity, and reorganizing top-level commands into Cobra help groups; also adds AGENTS.md as agent-oriented CLI reference documentation.

^{Reviewed by Cursor Bugbot for commit bca2ed3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 33e0375. Configure here.}