feat: hint at Notecard error and status code meanings

[Bucknalla]

What

When you run a request against a Notecard, the CLI now prints a human-readable hint explaining any recognized {code} in the output, using the definitions from notecard.codes.json.

It fires in two places:

• Errors — e.g. a failed -req whose err contains {template-incompatible}
• Status codes in successful responses — e.g. hub.status returning {connected}{cell-registered}

$ notecard -req '{"req":"hub.status"}'
{"status":"{connected}{cell-registered}"}
hint: {connected} Notecard is connected to the cellular network.
hint: {cell-registered} Wireless service successfully registered.

Source of definitions — fetched, not embedded

notecard.codes.json is fetched through the same fetch-and-cache pipeline used for schema validation (loadOrFetchSchema → /tmp/notecard-schema/), not committed to this repo. The codes URL is derived from the API schema's own $ref base, so:

• It's pulled from the exact same release the API schema points at (the release's notecard.api.json pins its $refs to a tagged version, e.g. refs/tags/v1.3.1) — version-pinned, no drift.
• It automatically follows any NOTE_JSON_SCHEMA_URL override.
• There is no maintained copy in this repo to keep in sync.

If the codes file can't be fetched (offline with a cold cache), hints are simply unavailable — the same network/cache tradeoff the existing validation code already makes.

Why token-scanning rather than driving hints off response-schema validation: only 2 of ~75 .rsp. schemas (hub.status, hub.sync.status) enumerate codes, and the err field isn't modeled with code enums anywhere. Scanning {tokens} in the response/error against the fetched codes file gives full coverage across all request types. (If you want response schema validation as its own feature, that's a separate change.)

Behavior

• Hints go to stderr so JSON on stdout stays clean and pipeable.
• Color auto-disables on non-TTY (fatih/color, already a dependency).
• Unknown/undocumented tokens are silently skipped — zero noise.
• On by default; suppress with the new -nohints flag (grouped under "Communication & Debug" in -h).

Known upstream gap

The upstream codes file covers status codes richly but omits several common error qualifiers note-go defines — {io}, {timeout}, {not-supported}, {syntax}. Tracked in blues/notecard-schema#305; once merged, hints pick them up automatically with no CLI change.

Tests

• notecard/codes_test.go — hermetic unit tests for parseCodeDescriptions (incl. malformed input) and explainCodesWith (multi-token, dedup, undocumented-skip, status-in-response, empty).
• Verified live against the real schema release: URL derivation → fetch → cache → hint, with documented codes hinting and {io} correctly skipped; stdout stays clean JSON. go build / go vet / go test all pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_018ngtas2Zmb7rFBd6y2hV8Y