docs(webhooks): restyle per-arm wire reference (table layout)

[Yan Xue (yanxue06)]

Summary

The previous per-arm reference under Per-arm wire reference was a stack of <Accordion> rows (one per Content arm) that rendered as a cramped, chevron-collapsed list — name + one-line description visible, the actual wire fields hidden behind a click. Switched to a clean table for at-a-glance scannability, matching the style used by the CLI flags reference and similar tabular sections elsewhere in the docs.

• Option A (table) — chosen because the chevron-collapsed accordion view was hiding the field-level info anyway, so collapsing each arm into one row with the wire fields inline gives readers more useful information at a glance, not less. Field types are inlined into the third column (field: type, comma-separated) so nothing is lost; the existing per-field "Discriminator." rows just disappear (the discriminator value is the row label).
• Forward-compat arms (rename + the unknown-future-arm fallback) are pulled into a small separate table below the main one, prefixed with Forward-compat arms in bold prose, so they're visually distinguished from the 12 published arms.
• Substantive footnotes that lived inside individual accordion bodies (byte-stripping for attachment/voice/contact.photo, target slim-ref pointer for reaction/reply/edit, richlink OG-fetch rationale, generic-fallback guidance) are preserved as a short bullet list between the two tables and as a closing reminder, rather than being repeated inside each row.

No content changes — every arm previously documented (text, attachment, voice, contact, richlink, reaction, reply, edit, group, effect, typing, custom, rename, plus the unknown-future-arm fallback) is still documented, just in a cleaner layout. The section heading anchor (#per-arm-wire-reference) is preserved, as is the lead-in paragraph, the surrounding Content shapes section, the byte-bearing <Warning>, and the Target refs section below.

Net change: 1 file, +28 / -120 lines.

Test plan

• pnpm docs:generate — vellum builds successfully, all 32 templates render
• pnpm typecheck:docs — all code blocks type-check and format clean
• pnpm lint — clean

Merge conflicts

Will conflict with the other in-flight PRs that touch docs-src/webhooks/events.mdx.vel:

• docs(webhooks): drop poll and avatar content arms — not officially supported #61 — already merged (poll/poll_option/avatar removal); no conflict, this PR is based on its merge.
• wire-format compatibility notes — adds a <Note> block immediately above the <AccordionGroup>. Conflict at the boundary line; trivial to resolve (keep the <Note>, then this PR's two tables).
• byte-retrieval section — likely lands either before or inside the <Warning> above this section; should not collide with the per-arm tables themselves.

The changes are in disjoint sub-sections within the same surrounding ## Body shape parent — resolve at merge time.

Made with Cursor

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}

Summary by CodeRabbit

• Documentation
  • Reorganized webhook content field reference documentation from accordion sections to a consolidated table format for improved readability and clearer guidance on all content types and forward-compatibility handling.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ba84ad6e-27f8-4da8-b1e0-7fb98a37147e

📥 Commits

Reviewing files that changed from the base of the PR and between 84505e5 and 3061733.

📒 Files selected for processing (1)

• docs-src/webhooks/events.mdx.vel

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

📝 Walkthrough

Walkthrough

This PR restructures the webhook content documentation from multiple per-arm accordions into a single unified reference table. It enumerates wire-projected fields for each content.type arm and adds explicit forward-compat handling for rename and unknown future arms, plus clarifying cross-cutting rules about byte metadata, target shape, and richlink constraints.

Changes

Webhook Content Wire Reference Documentation

Layer / File(s)

Summary

Per-arm wire reference consolidation docs-src/webhooks/events.mdx.vel

Accordion descriptions for each content.type arm (text, attachment, voice, contact, raw, richlink, reaction/reply/edit, group, effect, typing, custom) are replaced with a unified table listing post-projection wire fields. Forward-compat handling for rename and unknown arms is added alongside cross-cutting notes on metadata-only byte-bearing arms, slim target references, and richlink-only url field.

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• photon-hq/docs#62: Both PRs update the same "Per-arm wire reference" section with wire-format compatibility guidance for webhook content arms and field normalizations.
• photon-hq/docs#60: Both PRs modify content documentation for content.type projections including forward-compat handling for rename and message reference shapes.

Poem

🐰 A table emerges from accordion folds,
Wire fields shine, their story retold—
Forward-compat whispers in every row,
Clarity blooms where accordions used to go! 📚✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/per-arm-reference-restyle

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[github-actions]

Resolved merge conflict with main after #62 (wire-format compatibility notes) landed.

Conflict: docs-src/webhooks/events.mdx.vel, lines 188–222, at the boundary of the Per-arm wire reference section.

• main added a <Note> block (wire-format compatibility notes for May 2026) immediately above the existing <AccordionGroup>.
• This branch removed the <AccordionGroup> entirely and replaced it with two tables.

Git auto-applied the AccordionGroup removal everywhere except at the boundary line where main had inserted the <Note>, so the conflict region surfaced as the <Note> block + the leftover <AccordionGroup> opening with the first text accordion still inside it.

Resolution: Kept main's <Note> block (preserving the May 2026 compat notes) immediately above this PR's main table, and dropped the residual <AccordionGroup> / <Accordion title="text"> stub. The PR's structure (Note → main table → cross-cutting bullets → forward-compat arms table → Target refs) is preserved, with the compat-notes block now sitting between the section intro and the main table.

Verified: pnpm install --frozen-lockfile, pnpm lint, and pnpm typecheck:docs all pass clean.

[Yan Xue (yanxue06)]

Added a follow-up commit cross-linking MessageRef / Content / SerializedInboundMessage in the per-arm table cells. The previous version referenced those types as bare text, which left readers without a way to jump to the definitions; they're now anchor links to the appropriate in-file sections.

• MessageRef → #target-refs
• Content → #content-shapes (self-referential — points back to the per-arm table itself)
• SerializedInboundMessage → #message (existing inbound-message shape section that already serves as the canonical definition; matches the convention used on the top-level payload row See [Message](#message) below.)

No new sections were added — all three anchors already existed in the file. Build / typecheck / lint clean.

[Yan Xue (yanxue06)]

Heads up — the cross-linking follow-up I pushed in 57051a0 on this branch (added after the merge, never landed) used a code-span / link-bracket adjacency pattern (`target: `[`MessageRef`](#target-refs)) that's fragile across Mintlify's production MDX pipeline — @mdx-js/mdx and mint dev parse it correctly, but adjacency-sensitive renderers can merge the surrounding code spans and drop the <a> entirely.

Superseded by #67, which uses the same shape already proven to render in production ([`field: Type`](#anchor) — the existing [ErrorCode](#error-codes) pattern in error-handling.mdx.vel). Once #67 lands, all four cells (reaction, reply, edit, group) will be properly clickable on the live docs site.