fix(copy): trigger copy claimed a push the transport does not do; retire "wake an agent"

[choraria]

What

triggers.wait is a caller-driven short poll over the durable event log (ADR-0106). Server-push was considered and rejected there — MCP's server-initiated messages are at-most-once and drop events across a disconnect — and survives only as a possible future latency hint, "never the guarantee itself."

First-contact copy said the opposite. Found while a user registered a trigger, POSTed to their ingest URL, and watched nothing happen — then went debugging a working system against a mental model we handed them.

The two defects

1. "Push, not poll" (false). The dashboard triggers page read "a pushed trigger, not a poll." /mcp/wake-an-agent's frontmatter said "an event-driven primitive, not polling" while line 63 of the same page correctly called it a short poll. quickstart.mdx told readers to have an agent "block on triggers.wait until a matching webhook lands."

The deep layers — ADR-0106, /mcp/trigger-semantics, the db and contract comments (packages/db/src/agent-triggers.ts:4 literally says "It does not push or 'wake' the agent") — were always honest. The drift concentrated in ledes, frontmatter descriptions, and nav blurbs: exactly where the mental model forms.

2. Fabricated eventTypes (worse). The /product/agent-triggers visual showed triggers.create { endpointId, eventTypes: ["issue.updated"] }. There is no eventTypes on a trigger — it binds to one endpoint and yields everything that endpoint captures. The field belongs to subscriptions.create, and the input schema strips unknown keys rather than rejecting them. So a developer following the card would send a filter, have it silently dropped, and receive the endpoint's full stream believing it was filtered. Nothing errors, anywhere.

Changes

Copy — dashboard, docs, README, MCP tool descriptions, CLI help now say who drives the cadence. triggers.create's tool description states outright that nothing will call you and that a client which only registers receives nothing; that text is read by the model writing the client. /mcp/wake-an-agent gets a callout aimed at the reader whose POST did nothing, and its flow diagram's last hop now originates at the agent, because it does. /mcp/trigger-semantics gets a new "one endpoint, everything it captures" section documenting the absent filter and the silent strip.

Guards — scripts/trigger-copy-guard.mjs bans phrases false in any context (negation-aware, so the honest "does NOT block until" still passes) and adds a positive obligation: pages introducing the primitive must name the mechanism, so a page can't drop the lie and leave a vague claim. Surfaces are discovered by content, not listed — the first cut of this guard carried 13 hand-picked files and went green while quickstart.mdx lied. agent-trigger-card.test.tsx now validates shown arguments against the capability input schema; the old test pinned tool names, which is why an invented argument sailed through for a year.

Verification

Each guard confirmed RED on the real defect before the fix — including re-introducing eventTypes to check the new assertion fails with the right message (triggers.create has no "eventTypes" input — it would be silently ignored).

Green: full lint chain, 652 script tests, www 553, web 1552, mcp 120, cli 839, 33/33 typecheck.

⚠️ Needs human eyeball before merge

Per the AGENTS.md human-UI-testing hard stop, this is all user-facing copy and I can't verify rendering. Please check:

• Dashboard /org/<slug>/triggers — the lede is longer than before and now contains an inline <code>; check it doesn't wrap badly, and the same for the revoke dialog.
• Docs — <Warning> on /mcp/wake-an-agent and <Note> on /mcp/trigger-semantics render correctly, and the rewritten mermaid diagram (now with a bidirectional agent↔log pair) lays out sensibly.
• Judgement call to confirm: I kept the "wake an agent" page names, URLs, and nav titles. An agent is woken — by its own loop — and the URLs are indexed. I made the mechanism honest at first contact rather than renaming the feature. Say the word if you'd rather retire the framing entirely.

🤖 Generated with Claude Code

https://claude.ai/code/session_012hee4wHe7WLq6xTafqNDRY

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
webhook-co	🟢 Ready	View Preview	Jul 24, 2026, 7:45 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[choraria]

Follow-up: framing retired (founder call)

/mcp/wake-an-agent → /mcp/agent-triggers, /recipes/wake-an-agent → /recipes/agent-triggers.

The verb was the dishonest part, not the noun — "trigger" is what triggers.*, the dashboard, and /product/agent-triggers already call it, so keeping it leaves the docs connected to the surface they document. Both old URLs are indexed, so docs.json gains a permanent redirects block rather than 404ing every inbound link.

The MCP page is rewritten from the ground truth rather than patched — it opens with what a trigger is (a durable subscription to one endpoint, plus a cursor) and derives the three properties that follow: can't miss an event, can't process one twice, can't be fooled. Steps are numbered. The dashboard lede shrank to the same shape and no longer needs the word "woken" at all.

Re-verified: lint chain, docs-nav-guard (114 pages, links resolve), trigger-copy-guard (34 surfaces), web 1552, www 553, 33/33 typecheck.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
webhook-co	🟡 Building	–	Jul 24, 2026, 7:45 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.