#10680: docs: clarify api.on() vs api.registerHook() for plugin hooks

# PR: Document `api.on()` vs `api.registerHook()` for plugin developers **Type:** docs-only ## Problem OpenClaw exposes two hook registration methods in the plugin API: - `api.on(event, handler)` — registers a **typed hook** into `registry.typedHooks`. These are actually executed by the hook runner. - `api.registerHook(events, handler, opts)` — registers hook **metadata** into `registry.hooks`. These are used for UI/diagnostics only and are **never executed** by the hook runner. The names are similar enough that plugin developers naturally reach for `registerHook` first. When they do, registration succeeds without errors, the hook appears to be set up correctly, but the handler never fires. There is no warning logged. This leads to hours of silent-failure debugging. An additional footgun: `registerHook()` silently drops entries when `opts.name` is missing — again, no error, no warning. ## What this PR does - **`docs/plugin.md`**: Adds a "Registering typed hooks (inline)" section with a clear `api.on()` example, and a prominent warning callout explaining the difference between the two methods, including a comparison table and code examples showing correct vs incorrect usage. - **`docs/hooks.md`**: Adds a "Plugin hook registration" section that summarizes the distinction and links to the plugin docs for full details. ## Who this helps Any developer writing an OpenClaw plugin that needs event-driven hooks. This is the kind of trap you only fall into once — but it costs hours when you do. The docs now make the correct path obvious. <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> This docs-only PR clarifies the distinction between plugin hook registration APIs: - Adds a new **“Plugin hook registration”** section to `docs/hooks.md` that explains why `api.on()` is the correct choice for executable typed hooks, while `api.registerHook()` only records metadata for UI/diagnostics. - Expands `docs/plugin.md` under **Plugin hooks** with separate guidance for registering hooks from a directory vs registering typed hooks inline, including a comparison table and examples. - Also documents the naming convention difference between plugin typed hook keys (underscored) and workspace internal hook events (colon-separated) to reduce confusion. <h3>Confidence Score: 5/5</h3> - This PR is safe to merge with minimal risk. - Docs-only changes are internally consistent, follow existing linking conventions, and address the previously noted anchor/event-name concerns without introducing new broken references or contradictory guidance. - No files require special attention <!-- greptile_other_comments_section --> <!-- /greptile_comment -->