hermes-identity-plugin/README.md

# Hermes Identity Plugin

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.