feat: final platform plugin parity — webhook delivery, platform hints, docs

Closes remaining functional gaps and adds documentation.

## Functional fixes

webhook.py: Cross-platform delivery now checks the plugin registry
  for unknown platform names instead of hardcoding 15 names in a tuple.
  Plugin platforms can receive webhook-routed deliveries.

prompt_builder: Platform hints (system prompt LLM guidance) now fall
  back to the plugin registry's platform_hint field. Plugin platforms
  can tell the LLM 'you're on IRC, no markdown.'

PlatformEntry: Added platform_hint field for LLM guidance injection.

IRC adapter: Added acquire_scoped_lock/release_scoped_lock in
  connect/disconnect to prevent two profiles from using the same IRC
  identity. Added platform_hint for IRC-specific LLM guidance.

Removed dead token-empty-warning extension for plugin platforms
  (plugin adapters handle their own env vars via check_fn).

## Documentation

website/docs/developer-guide/adding-platform-adapters.md:
  - Added 'Plugin Path (Recommended)' section with full code examples,
    PLUGIN.yaml template, config.yaml examples, and a table showing all
    18 integration points the plugin system handles automatically
  - Renamed built-in checklist to clarify it's for core contributors

gateway/platforms/ADDING_A_PLATFORM.md:
  - Added Plugin Path section pointing to the reference implementation
    and full docs guide
  - Clarified built-in path is for core contributors only

website/docs/developer-guide/adding-platform-adapters.md

@@ -7,7 +7,9 @@ sidebar_position: 9
 This guide covers adding a new messaging platform to the Hermes gateway. A platform adapter connects Hermes to an external messaging service (Telegram, Discord, WeCom, etc.) so users can interact with the agent through that service.
 
 :::tip
-Adding a platform adapter touches 20+ files across code, config, and docs. Use this guide as a checklist — the adapter file itself is typically only 40% of the work.
+There are two ways to add a platform:
+- **Plugin** (recommended for community/third-party): Drop a plugin directory into `~/.hermes/plugins/` — zero core code changes needed. See [Plugin Path](#plugin-path-recommended) below.
+- **Built-in**: Modify 20+ files across code, config, and docs. Use the [Built-in Checklist](#step-by-step-checklist) below.
 :::
 
 ## Architecture Overview
@@ -26,7 +28,152 @@ Every adapter extends `BasePlatformAdapter` from `gateway/platforms/base.py` and
 
 Inbound messages are received by the adapter and forwarded via `self.handle_message(event)`, which the base class routes to the gateway runner.
 
-## Step-by-Step Checklist
+## Plugin Path (Recommended)
+
+The plugin system lets you add a platform adapter without modifying any core Hermes code. Your plugin is a directory with two files:
+
+```
+~/.hermes/plugins/my-platform/
+  PLUGIN.yaml      # Plugin metadata
+  adapter.py       # Adapter class + register() entry point
+```
+
+### PLUGIN.yaml
+
+```yaml
+name: my-platform
+version: 1.0.0
+description: My custom messaging platform adapter
+requires_env:
+  - MY_PLATFORM_TOKEN
+  - MY_PLATFORM_CHANNEL
+```
+
+### adapter.py
+
+```python
+import os
+from gateway.platforms.base import (
+    BasePlatformAdapter, SendResult, MessageEvent, MessageType,
+)
+from gateway.config import Platform, PlatformConfig
+
+
+class MyPlatformAdapter(BasePlatformAdapter):
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform("my_platform"))
+        extra = config.extra or {}
+        self.token = os.getenv("MY_PLATFORM_TOKEN") or extra.get("token", "")
+
+    async def connect(self) -> bool:
+        # Connect to the platform API, start listeners
+        self._mark_connected()
+        return True
+
+    async def disconnect(self) -> None:
+        self._mark_disconnected()
+
+    async def send(self, chat_id, content, reply_to=None, metadata=None):
+        # Send message via platform API
+        return SendResult(success=True, message_id="...")
+
+    async def get_chat_info(self, chat_id):
+        return {"name": chat_id, "type": "dm"}
+
+
+def check_requirements() -> bool:
+    return bool(os.getenv("MY_PLATFORM_TOKEN"))
+
+
+def validate_config(config) -> bool:
+    extra = getattr(config, "extra", {}) or {}
+    return bool(os.getenv("MY_PLATFORM_TOKEN") or extra.get("token"))
+
+
+def register(ctx):
+    """Plugin entry point — called by the Hermes plugin system."""
+    ctx.register_platform(
+        name="my_platform",
+        label="My Platform",
+        adapter_factory=lambda cfg: MyPlatformAdapter(cfg),
+        check_fn=check_requirements,
+        validate_config=validate_config,
+        required_env=["MY_PLATFORM_TOKEN"],
+        install_hint="pip install my-platform-sdk",
+        # Per-platform user authorization env vars
+        allowed_users_env="MY_PLATFORM_ALLOWED_USERS",
+        allow_all_env="MY_PLATFORM_ALLOW_ALL_USERS",
+        # Message length limit for smart chunking (0 = no limit)
+        max_message_length=4000,
+        # LLM guidance injected into system prompt
+        platform_hint=(
+            "You are chatting via My Platform. "
+            "It supports markdown formatting."
+        ),
+        # Display
+        emoji="💬",
+    )
+
+    # Optional: register platform-specific tools
+    ctx.register_tool(
+        name="my_platform_search",
+        toolset="my_platform",
+        schema={...},
+        handler=my_search_handler,
+    )
+```
+
+### Configuration
+
+Users configure the platform in `config.yaml`:
+
+```yaml
+gateway:
+  platforms:
+    my_platform:
+      enabled: true
+      extra:
+        token: "..."
+        channel: "#general"
+```
+
+Or via environment variables (which the adapter reads in `__init__`).
+
+### What the Plugin System Handles Automatically
+
+When you call `ctx.register_platform()`, the following integration points are handled for you — no core code changes needed:
+
+| Integration point | How it works |
+|---|---|
+| Gateway adapter creation | Registry checked before built-in if/elif chain |
+| Config parsing | `Platform._missing_()` accepts any platform name |
+| Connected platform validation | Registry `validate_config()` called |
+| User authorization | `allowed_users_env` / `allow_all_env` checked |
+| Cron delivery | `Platform()` resolves any registered name |
+| send_message tool | Routes through live gateway adapter |
+| Webhook cross-platform delivery | Registry checked for known platforms |
+| `/update` command access | `allow_update_command` flag |
+| Channel directory | Plugin platforms included in enumeration |
+| System prompt hints | `platform_hint` injected into LLM context |
+| Message chunking | `max_message_length` for smart splitting |
+| PII redaction | `pii_safe` flag |
+| `hermes status` | Shows plugin platforms with `(plugin)` tag |
+| `hermes gateway setup` | Plugin platforms appear in setup menu |
+| `hermes tools` / `hermes skills` | Plugin platforms in per-platform config |
+| Token lock (multi-profile) | Use `acquire_scoped_lock()` in your `connect()` |
+| Orphaned config warning | Descriptive log when plugin is missing |
+
+### Reference Implementation
+
+See `plugins/platforms/irc/` in the repo for a complete working example — a full async IRC adapter with zero external dependencies.
+
+---
+
+## Step-by-Step Checklist (Built-in Path)
+
+:::note
+This checklist is for adding a platform directly to the Hermes core codebase — typically done by core contributors for officially supported platforms. Community/third-party platforms should use the [Plugin Path](#plugin-path-recommended) above.
+:::
 
 ### 1. Platform Enum