docs(listener): add API usage cookbook with workflow examples (#139)

[zeroknowledge0x]

Closes #139

Summary

Adds a workflow-oriented companion to listener/API.md that demonstrates how to combine endpoints to ship common integrations. Each workflow has a curl one-liner, an expected response shape, and a follow-on command so contributors can copy-paste-test against a running listener.

Workflows covered

1. Stream live contract events — curl + jq tail polling loop
2. Schedule a future notification — Discord reminders with chained events
3. Accept signed webhooks — HMAC-SHA256 signing from bash and Node.js
4. Manage per-user notification preferences — patch-style updates
5. Health-check a deployment — K8s readiness probe + dependency dump
6. Diagnose a failing request — X-Request-Id / X-Correlation-Id tracing
7. Recover from a Discord outage — detection, re-queue, prevention

Plus a Troubleshooting matrix (symptom → cause → fix) and a one-page field reference for the most common JSON envelopes.

Files changed

• listener/API_USAGE_COOKBOOK.md — new file, +558 lines, 7 workflows + troubleshooting + field reference
• listener/INSTALLATION.md — +5 lines, cross-link from install path so the cookbook is discoverable

Acceptance criteria mapping

• Add request examples — every workflow shows the exact curl/Node snippet
• Add response examples — every workflow shows the expected JSON envelope
• Cover authentication flows — Workflow 3 demonstrates HMAC verification, INSTALLATION.md cross-link mentions token header
• Include troubleshooting tips — full troubleshooting matrix at the end of the cookbook

How to verify locally

# After `./install.sh`, the listener exposes:
curl -s http://localhost:8080/healthz | jq .
# Should return: {"status":"ok",...}

# Stream events (Workflow 1):
curl -sN http://localhost:8080/events/stream | jq -c '.'

All 7 workflows use only the documented listener API surface — no undocumented endpoints.

Cross-links

The cookbook is discoverable from listener/INSTALLATION.md (Step 6 → 'See API_USAGE_COOKBOOK.md for end-to-end workflow examples') so contributors who finish install can immediately try the workflows.

Labels

This issue carries the GrantFox triple label (Maybe Rewarded + GrantFox OSS + Official Campaign). Happy to follow any additional GrantFox claim workflow after merge.

---

Signed-off-by: zeroknowledge0x zeroknowledge0x@users.noreply.github.com