initial: identity resolution plugin

- Plugin manifest (plugin.yaml) with pre_gateway_dispatch + on_session_start hooks
- /identity slash command for config management
- Honcho injector patch docs (6 lines in plugins/memory/honcho/__init__.py)
- Config file at /opt/data/identity-config.json for persistence
- Kanban task body convention: context_peer: <name>
- Sample config with thierry/catherine mappings

Architecture: user-installed plugin (hooks + CLI) + 6-line Honcho bundled plugin change

README.md

@@ -1,3 +1,101 @@
-# hermes-identity-plugin
+# Hermes Identity Plugin
 
-Hermes identity resolution plugin — maps platform IDs and kanban boards to stable Honcho peer names across Discord, Telegram, terminal, and kanban workers.
+Maps platform-specific user IDs (Discord snowflake, Telegram UID, terminal
+session) and kanban boards to stable Honcho peer names. Eliminates
+`user-default-t_*` peers from kanban workers and unifies a user's identity
+across platforms (Discord + Telegram → same Honcho peer).
+
+## Architecture
+
+```
+                     ┌──────────────────────┐
+                     │  identity-config.json │
+                     │  /opt/data/           │
+                     └──────┬───────────────┘
+                            │ read on init
+         ┌──────────────────┼──────────────────┐
+         │                  │                  │
+         ▼                  ▼                  ▼
+  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
+  │ pre_gateway  │  │  on_session  │  │  Honcho      │
+  │ dispatch     │  │  start hook  │  │  injector    │
+  │ hook (log)   │  │  (log/track) │  │  (session.py)│
+  └──────────────┘  └──────────────┘  └──────┬───────┘
+                                             │
+                                    resolves peer_name
+                                    before Honcho init
+```
+
+Two components work together:
+
+1. **This plugin** (user-installed) — provides `/identity` slash command for
+   config management, `pre_gateway_dispatch` logging, and `on_session_start`
+   tracking. Installed via `hermes plugins install`.
+
+2. **Honcho injector** (~6 lines in `plugins/memory/honcho/session.py`) — reads
+   the config file and `HERMES_KANBAN_TASK` env var to inject the correct
+   `runtime_user_peer_name` into Honcho's session initialization. See
+   [`docs/honcho-injector.md`](docs/honcho-injector.md).
+
+## Installation
+
+```bash
+# 1. Install the plugin
+hermes plugins install gitea:code.lazyworkhorse.net/Hermes/hermes-identity-plugin
+
+# 2. Apply the Honcho injector patch (see docs/honcho-injector.md)
+# 3. Create the config file
+cp config.sample.json /opt/data/identity-config.json
+# 4. Edit /opt/data/identity-config.json with your mappings
+# 5. Restart gateways
+```
+
+## Config file: `/opt/data/identity-config.json`
+
+```json
+{
+  "mappings": [
+    {"platform": "discord", "id": "479136126737711105", "peer": "thierry"},
+    {"platform": "telegram", "id": "123456789", "peer": "thierry"}
+  ],
+  "boards": {
+    "default": "thierry",
+    "catherine": "catherine"
+  },
+  "fallback_peer": "user",
+  "enforce_context_peer": true
+}
+```
+
+## Task body convention
+
+Every kanban task MUST include a `context_peer` in its body:
+
+```markdown
+Do research on Postgres migration costs.
+
+```metadata
+context_peer: thierry
+```
+```
+
+Profiles (Claire, Ashley, Finn, Matt) MUST include this when calling
+`kanban_create`. The `enforce_context_peer` config flag controls whether
+missing `context_peer` causes an error.
+
+## Commands
+
+- `/identity status` — show current config and resolved peer
+- `/identity list` — list all mappings
+- `/identity add discord <id> <peer>` — add a new mapping
+- `/identity rm <index>` — remove mapping
+- `/identity board <slug> <peer>` — set board peer
+- `/identity help` — full help
+
+## Enforcing the convention
+
+Add this to the kanban-worker skill or the profile's system prompt:
+
+> When creating a kanban task with `kanban_create`, you MUST include
+> `context_peer: <peer_name>` in the task body as a metadata block.
+> Use the user's Honcho peer name — not your own profile name.