feat(seo): add AI agent events guide

[lilyshen0722]

Summary

• publish the static, light-shell guide at /guides/ai-agent-events/
• add sitemap/canonical Article metadata, hub entry, and four approved reciprocal links
• cover the client route and placeholder-only acknowledgement curl

Verification

• node --test scripts/generate-seo-pages.test.mjs
• npx jest --runInBand src/v2/__tests__/V2Login.test.tsx
• npm run typecheck
• npm run build
• npm test -- --watch=false (86 suites, 485 tests)

[lilyshen0722]

Gated at 90b93d6c. Two of the five rows in the event-type table name events that no code in this repository emits. Everything else checks out, and the generator work is clean.

Measured against origin/main efadbc3d:

row	status
chat.mention	real — 3 literal producers, plus MENTION_EVENT_TYPES
thread.mention	real — agentMentionService.ts:144
heartbeat	real — producers in registry/admin.ts:435, registry/pod-agents.ts:150, agentStateService.ts:151
task.assigned	not an event type
integration.event	no producer anywhere in the repo

integration.event appears only in docs-site/ — agents/events.mdx:89 (with a full JSON example), agents/runtime-protocol.mdx:62, integrations/webhooks.mdx:26. Zero hits in backend/. The real type for that slot is integration.summary, which is produced once in the backend and is a member of TYPING_EVENT_TYPES at agentEventService.ts:351. So the guide is faithful to our docs, and our docs are wrong — the error is inherited, not invented here.

task.assigned is a category error rather than a fiction. It exists, but as an AgentRun.trigger value — models/AgentRun.ts:116 (enum: ['mention','heartbeat','task.assigned','chat.message','pod.join','first_contact','manual']) and nativeRuntimeService.ts:609. Nothing constructs an AgentEvent with that type. The guide's prose commits to the stronger reading — "The task.assigned event carries the task and its current status" — so an agent author following it will poll for an event that never arrives.

The table is also missing the highest-volume real event. message.posted has 6 literal producers and is the whole wake-on-message path; a reader gets a five-row taxonomy that omits it while including two that do not exist.

Why the tests don't catch this, and why that matters here specifically. The new guard is

for (const eventType of ['chat\\.mention','thread\\.mention','task\\.assigned','heartbeat','integration\\.event']) {
  assert.match(eventsHtml, new RegExp(eventType));
}

which pins the string, not the referent. It will stay green forever whether or not the kernel emits any of them — this is exactly the failure mode TASK-074 was filed against, arriving on a page with crawl reach.

Suggested fix, smallest version: integration.event → integration.summary; drop the task.assigned row or re-label it as a run trigger rather than a polled event; and file the docs-site/agents/events.mdx correction separately, since that is the upstream source and will keep re-seeding this.

What is verified good:

• payload.deliveryId echoed on ack is exactly the implemented contract — agentsRuntime.ts:1115–1145, including the isDeliveryNonceRequired gate and the ADR-026 D6 note.
• Rendered all 24 pages through renderStaticPage in a scratch tree: 0 hits for [object Object], stray undefined, or NaN. node --test scripts/generate-seo-pages.test.mjs is 2/2 on Node 22.
• assert.doesNotMatch(eventsHtml, /cm_agent_[A-Za-z0-9]{8,}/) is a genuine addition — a real-token leak guard with a shape that would actually fire, not a presence assertion.
• Base is current main (0 behind), so #1386 is already included and there is no parallel-merge hazard with it.
• Test & Coverage is still pending; the other 10 are green.