skills/creating-plugins hooks reference omits content:beforeSave's id (added in #2897)

[cyface]

Description

skills/creating-plugins/references/hooks.md documents the content:beforeSave event as:

Event: `{ content: Record<string, unknown>, collection: string, isNew: boolean }`

It is missing id, which #2897 added and which shipped in 0.37.0.

The rest of the project is consistent and correct — this is only the skills/ copy drifting:

Source	Documents id?
ContentHookEvent typings (dist/types-*.d.mts, 0.37.0)	yes, with a doc comment
docs site — reference/hooks	yes, full interface
docs site — plugins/creating-plugins/hooks	yes
skills/creating-plugins/references/hooks.md	no

#2897 updated docs/src/content/docs/plugins/creating-plugins/hooks.mdx and docs/src/content/docs/reference/hooks.mdx, but not the parallel skills/ copy. That file does appear to be maintained alongside changes like this normally — #2858, #2617, #1659 and #1658 all touched it — so this looks like an oversight rather than intent.

Why it seemed worth reporting

The skills/ files are written to be read by coding agents. An agent building a plugin from this reference will not learn that event.id exists, and will reach for a workaround to get at the stored item — which is the exact situation the changeset for #2897 gives as the reason for adding the field.

The correct text is already written; it is the sentence #2897 put in hooks.mdx:

On an update, id is the ID of the existing item and content holds only the submitted field values; load the stored item with ctx.content.get(event.collection, event.id).

One thing I could not check from outside: scripts/sync-template-skills.sh suggests these skills propagate somewhere, so it may be worth confirming nothing downstream inherited the stale copy.

Steps to reproduce

1. Check out main (verified 2026-09-10; also identical in the emdash@0.37.0 tag).
2. Open skills/creating-plugins/references/hooks.md and find the content:beforeSave section.
3. Read the Event: line — { content, collection, isNew }, no id.
4. Compare against ContentHookEvent in the published typings, or against either docs-site page above, both of which include id?: string.

Environment

• emdash version: 0.37.0 (also present on main at time of writing)
• Node.js version: 24
• Runtime: Cloudflare Workers
• OS: macOS

Screenshots

Not applicable — this is a documentation file, not interface behaviour.

Logs / error output

Not applicable. For reference, the shipped typings this file disagrees with:

interface ContentHookEvent {
  content: Record<string, unknown>;
  collection: string;
  isNew: boolean;
  /**
   * ID of the existing item on `content:beforeSave` for an update. Absent on
   * creates, where the ID is assigned when the save completes, and on
   * `content:afterSave`, where `content.id` carries it.
   */
  id?: string;
}

---

_{Found while re-vendoring these skills for a 0.36.0 → 0.37.0 upgrade. Investigated and drafted with Claude Code (Claude Opus 5); the findings above were each verified against main and the published package before filing.}

[dchaudhari7177]

This looks resolved on main now: skills/creating-plugins/references/hooks.md documents the content:beforeSave event as { content, collection, isNew, id?: string, actor?: … }, adding that "On updates, id identifies the existing item" (last touched in 36a021c1), so the issue could probably be closed.

[cyface]

Thanks for checking — confirmed, and closing.

skills/creating-plugins/references/hooks.md on main now reads:

Event: { content: Record<string, unknown>, collection: string, isNew: boolean, id?: string, actor?: { id: string, role: number } }. Authenticated REST, visual editing, and MCP saves include a read-only actor snapshot; internal writes may omit it. On updates, id identifies the existing item.

For the record, since it may help anyone who lands here from a search: the fix came in incidentally rather than as a targeted change. 36a021c1 is "separate revision author from entry owner and pass actor to content hooks (#2881) (#3057)", which rewrote that Event: line to add actor and picked up id along the way. So there is no commit or PR that references this issue.

One note for anyone hitting the original symptom: 36a021c1 landed 2026-09-11 and the newest published release is still 0.37.0 (2026-09-09), so the emdash@0.37.0 tag's copy of the file is unchanged. It will be correct from the next release onwards. Nothing to do here — just flagging why a version-pinned read may still show the old text for now.