[PLT-3072] docs: explain connected account lifecycle recovery

[TheMostlyGreat]

Why

When a connected account expires, operators need to understand the lifecycle event and reconnect the existing account without recreating triggers.

What

• documents connected_account.created, connected_account.expired, and connected_account.reconnected
• explains the tenant-scoped envelope, expiry reasons, subscription, and Dashboard/API recovery
• records the MCP-managed OAuth and reduced-grant boundaries
• extends the unified eventing guide tests with the lifecycle contract

Verification

• full docs suite: 874/874 pass
• executable receiver tests: 11/11 pass
• lint and typecheck: clean
• production build: /en/build/eventing rendered successfully
• branch rebased to contain only five lifecycle commits over the unified guide

Merge gate

Ready for review as a child of #1146. Merge and publication remain intentionally gated on the parent guide and corresponding Engine release.

Linear: https://linear.app/arcadedev/issue/PLT-3072

---

Note

Low Risk
Documentation and contract tests only; no runtime, auth, or data-path changes.

Overview
Adds a Recover expired connected accounts section to the unified eventing guide, placed before the scheduled-event walkthrough.

The new content covers subscribing to connected_account.created, connected_account.expired, and connected_account.reconnected; verifying Standard Webhooks signatures; the expired-event payload and no_refresh_token / refresh_failed reasons; project-scoped subscriptions vs organization-bound connections (no project_id); and recovery via Dashboard Reconnect or POST .../auth/authorize, including scope behavior and trigger health after connected_account.reconnected. It also states that MCP-managed OAuth does not emit these lifecycle events or use the standard reconnect path.

tests/eventing-guide.test.ts gains a section-scoped test that asserts those strings, API paths, and the documented JSON envelope field set.

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 31, 2026 5:10am