feat(events): document namespaced custom hooks

[gabek]

Related to owncast/owncast#5093 and owncast/owncast#5119.

Summary

• Define custom handler keys as local hook names owned by the declaring plugin.
• Define owncast.events.emit targets as fully qualified <recipient-slug>.<hook> names.
• Update JavaScript and Python SDK comments, types, author guidance, wire protocol, scaffolder templates, and bundled skills.
• Update relay and announcer in both languages to show the full directed round trip.

Verification

Against the matching runtime from owncast/owncast#5119:

• JavaScript relay: 2/2 scenarios passed.
• JavaScript announcer: 1/1 scenario passed.
• Python relay: 2/2 scenarios passed.
• Python announcer: 1/1 scenario passed.
• Independent SDK and documentation review: clean after fixes.

Merge order

Do not merge before owncast/owncast#5119 is released and host-runtime/go.mod is bumped to that build. The current pin keeps custom subscriptions literal. CI uses the matching open Owncast branch so this PR is tested against the new runtime before that release exists.

[Copilot]

Pull request overview

This PR updates the SDK and author-facing documentation to clarify namespaced custom hook ownership: plugins declare local custom hook names, while emitters must target fully qualified <recipient-slug>.<hook> event types. It also updates the bundled templates, skills, and relay/announcer examples to reflect the directed emitter→recipient round trip.

Changes:

• Document that on / @plugin.on(...) custom hooks are local hook keys owned by the declaring plugin, and the host registers them as <plugin-slug>.<hook>.
• Document that owncast.events.emit must target the fully qualified <recipient-slug>.<hook> name.
• Update JS/Python templates, skills, guides, wire protocol docs, and relay examples/tests to use/describe the fully qualified announcer hook.

Reviewed changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
sdks/python/owncast_plugin/template/src/plugin.py	Updates scaffolded example to show local custom hook naming and ownership.
sdks/python/owncast_plugin/template/AGENTS.md	Updates agent guidance table to describe local hook ownership + fully qualified emit targets.
sdks/python/owncast_plugin/template/.agents/skills/create-owncast-plugin-py/SKILL.md	Updates Python skill docs to describe local hook keys and qualified emit targets.
sdks/python/owncast_plugin/init.py	Adds docstrings clarifying local hook registration and fully qualified emit targets.
sdks/js/index.js	Updates top-level runtime comments to describe local custom hook keys and host qualification.
sdks/js/index.d.ts	Updates TypeScript docs for on and owncast.events.emit to reflect namespaced hook behavior.
sdks/js/create-owncast-plugin/template/src/plugin.js	Updates JS template example to show local hook naming and ownership.
sdks/js/create-owncast-plugin/template/AGENTS.md	Updates agent guidance table for local hook ownership + fully qualified emit targets.
sdks/js/create-owncast-plugin/template/.agents/skills/create-owncast-plugin-js/SKILL.md	Updates JS skill docs to describe local hook keys and qualified emit targets.
README.md	Updates repository README to explain local hook declaration vs qualified emit targets and updates the relay→announcer narrative.
examples/python/relay/src/plugin.py	Updates relay example to emit to announcer.announcement.broadcast.
examples/python/relay/README.md	Updates relay example docs to describe targeting announcer’s fully qualified hook.
examples/python/relay/plugin.manifest.json	Updates relay manifest description to reference the qualified target hook.
examples/python/relay/INSTRUCTIONS.md	Updates relay instructions to reference qualified emit target and round trip wording.
examples/python/relay/tests/relay.test.json	Updates relay scenario expectations to assert the qualified emitted event type.
examples/python/README.md	Updates examples catalog descriptions to distinguish emitter targeting vs receiver hook ownership.
examples/python/announcer/README.md	Updates announcer docs to describe local hook ownership and host registration behavior.
examples/python/announcer/plugin.manifest.json	Updates announcer manifest description to reflect hook ownership.
examples/python/announcer/INSTRUCTIONS.md	Updates announcer instructions to describe host routing from qualified target to local hook.
examples/js/relay/src/plugin.js	Updates relay example to emit to announcer.announcement.broadcast.
examples/js/relay/README.md	Updates relay example docs to describe targeting announcer’s fully qualified hook.
examples/js/relay/plugin.manifest.json	Updates relay manifest description to reference the qualified target hook.
examples/js/relay/INSTRUCTIONS.md	Updates relay instructions to reference qualified emit target and round trip wording.
examples/js/relay/tests/relay.test.json	Updates relay scenario expectations to assert the qualified emitted event type.
examples/js/README.md	Updates examples catalog descriptions to distinguish emitter targeting vs receiver hook ownership.
examples/js/announcer/README.md	Updates announcer docs to describe local hook ownership and host registration behavior.
examples/js/announcer/plugin.manifest.json	Updates announcer manifest description to reflect hook ownership.
examples/js/announcer/INSTRUCTIONS.md	Updates announcer instructions to describe host routing from qualified target to local hook.
docs/WIRE_PROTOCOL.md	Documents host-side namespacing of custom hook subscriptions and emitter targeting requirements.
docs/PLUGIN_AUTHOR_GUIDE.md	Updates author guide examples and permission docs to reflect qualified emit targets and local hook ownership.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.