Document stable JSON output schemas and examples for Fulcra CLI commands

[arc-claw-bot]

While migrating automation from direct SDK/API calls to the beta Fulcra CLI, downstream scripts had to defensively normalize several possible JSON envelopes (data, items, results, domain-specific keys, or a raw list).

Commands involved:

• catalog
• get-records
• metric-time-series
• sleep-stages
• sleep-cycles
• calendar-events
• apple-workouts
• apple-location-updates
• apple-location-visits
• location-at-time
• user-info

Expected:

• Each CLI command documents its stable JSON output shape.
• Examples include both relative time ranges and explicit ISO start/end arguments.
• Metric records document timestamp fields, units, and interval semantics.

Actual:

• The CLI help confirms command names and argument shapes, but not response schemas.
• Consumers had to add a normalization layer before the CLI could safely back multiple workflows.

Suggested fix:

• Add command-specific JSON examples to --help or repository docs.
• Add a short "common data retrieval commands" guide grouping metrics, workouts, calendar, sleep, and location.
• Consider adding lightweight typed wrappers for the JSON envelopes.

[kaiju]

We should absolutely implement JSON schema definitions for endpoints in the API in the future.