SEO guide /guides/ai-agent-events/ documents two event types that no code emits (integration.event, task.assigned)

[lilyshen0722]

/guides/ai-agent-events/ shipped in #1388 (merged 90b93d6c) documents a five-row event-type table, and two of the rows name events that no code in this repository emits. The page is static, crawlable, and now live on main at frontend/src/content/guides.json:2689.

I filed this as a blocking review finding on #1388 before it merged; recording it as an issue so it survives the merge rather than sitting on a closed PR.

Measured against origin/main:

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

integration.event does not exist

It appears only under 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: produced in the backend and a member of TYPING_EVENT_TYPES at backend/services/agentEventService.ts:351.

The guide is faithful to our own docs here. The docs are wrong, which is why this needs fixing in two places or it will be re-seeded by the next writer.

task.assigned is a category error

It exists, but as an AgentRun.trigger value, not an AgentEvent.type:

• backend/models/AgentRun.ts:116 — enum: ['mention','heartbeat','task.assigned','chat.message','pod.join','first_contact','manual']
• backend/services/nativeRuntimeService.ts:609 — if (raw === 'task.assigned') return 'task.assigned';

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 who follows it will poll for an event that never arrives.

The table also omits the highest-volume real event

message.posted has 6 literal producers and is the entire wake-on-message path. A reader gets a five-row taxonomy that leaves it out while including two types that do not exist.

Why CI is green on this

The guard added in #1388 is:

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

It pins the string, never the referent, so it stays green whether or not the kernel emits any of them. This is the failure mode TASK-074 was filed against — a doc asserting a kernel mechanism that no test guards — now on a page with crawl reach.

Suggested fix

1. frontend/src/content/guides.json — integration.event → integration.summary; drop the task.assigned row or relabel it explicitly as a run trigger, not a polled event; consider adding message.posted.
2. docs-site/agents/events.mdx, docs-site/agents/runtime-protocol.mdx, docs-site/integrations/webhooks.mdx — same correction upstream, or the error regenerates.
3. If the event vocabulary is worth guarding, the assertion has to resolve against the producer set rather than the rendered string.

[lilyshen0722]

Recurrence confirmed, one PR later — and a second instance of the same upstream defect.

#1393 (/guides/ai-agent-discord-integration/, head c00693ba) cites integration.event again:

"Commonly's agent event reference includes integration.event for external integration events, with source and data in the payload; its example uses source: "discord"."

That is true as written — docs-site/agents/events.mdx:89 includes it with exactly that example. Which is the point of this issue: the docs-site/ entry is the source, and it re-seeds on every new writer who consults it. That took one PR.

Ordering note: because #1393 phrases it as a claim about the reference rather than the runtime, fixing this issue upstream makes that sentence false. The two changes are coupled and should land together.

---

Second instance found while gating #1393: DISCORD_GUILD_ID has no consumer.

Documented at docs-site/deployment/environment-variables.mdx:60 and wired in k8s/helm/commonly/templates/core/backend-deployment.yaml:247. Zero hits in backend/ (control run with DISCORD_BOT_TOKEN on the same query returns hits, so the query is sound).

The guild id is resolved from the Integration record instead — backend/services/discordService.ts:240:

const guildId =
  integration.platformIntegration?.serverId ||
  integration.config?.serverId;

and the command deployer requires only two variables — backend/scripts/deploy-discord-commands.js:51:

const required = ["DISCORD_CLIENT_ID", "DISCORD_BOT_TOKEN"];

So an operator following the docs sets a variable that does nothing, and may conclude guild scoping is env-configured when it is per-integration data.

Suggested scope change for this issue: it is no longer one wrong row in one guide. docs-site/ is a documentation surface with no test tier and no producer-side check, and it is now demonstrably the input to public SEO pages. Three known-wrong entries so far — integration.event, task.assigned (a run trigger documented as an event), and DISCORD_GUILD_ID. A guard that resolves documented identifiers against the code that emits or reads them would catch all three and every future one; without it the next guide inherits the next error.

[lilyshen0722]

Third recurrence: #1396 (/guides/what-is-an-ai-agent-runtime/) carries both rows again, this time as direct assertions in a table headed "What it means for a runtime".

Rather than gate a fourth copy, I fixed the source: #1397.

Two corrections to what I proposed in this issue, both found by checking before editing:

1. My suggested integration.event → integration.summary was imprecise. Discord emits discord.summary, not integration.summary — schedulerService.ts:741 branches on integration.type === 'discord'. Since the docs example uses source: "discord", the single-type replacement I suggested would have been wrong for the exact case the example shows.
2. The scope was larger than three files. The same fabricated heartbeat payload (memoryFiles, recentMessages, pendingTasks, context) appears in five files, and agents/memory.mdx builds an instruction on it: "agents don't need to manually fetch MEMORY.md and HEARTBEAT.md every cycle." An agent following that reads undefined. The mention payloads were also wrong (text where the producer writes content).

#1397 corrects all of it against the producers, cited by file and line. The remaining half of this issue — a guard that resolves a documented identifier against the code that emits or reads it — is still open, and is the only thing that prevents the next one.