docs(integration-toolkit): document monitoring and alerting, fix stale facts

[karlrank]

Monitoring was 998 of the section's ~34,600 words, and the one page it had documented the narrowest capability in the whole surface — how a middleware pushes its own spans in. The Hub's Monitoring and Notifications tabs, the code taxonomy, replay, retention and the entire alerting engine had no page at all.

Corrections

These were actively costing partners time:

Was	Now
23 curl examples on erp-integration.sls.epilot.io — NXDOMAIN	integration-toolkit.sls.epilot.io, matching the spec's servers block
POST /v1/monitoring/events + /v1/monitoring/stats — never existed in any version of the spec	Short stub with one correct v2 example, linking to the new section
erp:read / erp:write / erp:events / erp:monitoring — appear nowhere in the codebase	integration:view / integration:manage / integration:consume, plus a per-endpoint table
ACK example sent a status field not in the contract, and sourced ack_id from a webhook header	ack_id is the only field; it arrives as the _ack_id payload field on every core event
Monitoring marked In progress	Split into Monitoring / Alerting & Notifications / ACK Tracking, all Stable

New monitoring/ section

Six pages, written UI-first with the API alongside — the people who live in this are operators, not middleware developers.

• overview — levels (including why info is excluded from the success rate), codes, the event_id vs correlation_id distinction, use case lanes, General/__unknown__, retention, entity sync-status
• codes — all 80 codes, generated (below)
• investigating — traces, what body capture stores and elides, replay, querying, and a "which number am I looking at" section for the monitoring vs incoming source split that silently under-reports past 14 days
• alerting — six rule types, auto thresholds, scoping, recipients/channels, digests, muting, notification history
• acks — lifecycle, timeout, per-use-case ack_tracking
• external-events — the existing page, moved in. Slug unchanged, so the published URL does not break.

The codes page is generated

scripts/update-monitoring-codes.js builds it from a snapshot erp-integration-api emits and asserts in CI — the same pattern this repo already uses for entity-api schemas and event-catalog-api events. The descriptions previously lived only in the integration hub, so a backend taxonomy was owned by a frontend. The producer owns them now and this page is a consumer, so the published reference cannot drift from what the code emits.

Companion changes already on integration-toolkit-api main: fd09f5d (v2 level taxonomy) and 2746cb2 (catalog + snapshot).

Notes on two judgement calls

• Retention figures are stated (90 days monitoring, 14 days received payloads). The 14-day one is a hard ceiling on replay that operators otherwise discover by failing.
• Body-capture redaction is documented as a guarantee, not a match list, with a pointer to the secure proxy for custom auth headers — publishing the exact list would double as a map of what isn't matched.

Verification

npm run build passes with onBrokenLinks: 'throw'. Cross-file anchors verified separately, since Docusaurus does not validate those by default.

🤖 Generated with Claude Code