# Communication

This document describes the trigger rules, the trust model, the commands, and the trigger log.

## Trigger rules

A message is a trigger when one of these conditions is true:

- The message is a direct message to the puppet. A direct message is a one-to-one DM, not a group.
- The message mentions the puppet. This applies in guild channels and group DMs.

All other messages are ignored.

## Trust model

The puppet has one owner and a trust list.

- The owner is always trusted. The default owner is `177117296140091393` (zzib).
- The trust list holds additional user IDs.
- A trusted user gets the 100-entry log. An untrusted user gets the 30-entry log.

The owner controls the trust list. Commands from other users do not change the list.

## Commands

The owner sends commands from Discord. In a direct message, the text is the command. In a guild or
a group DM, mention the puppet first.

| Command | Effect |
| --- | --- |
| `whitelist list` | Show the owner and the trusted users. |
| `whitelist add @user` | Add one or more users to the trust list. |
| `whitelist remove @user` | Remove one or more users from the trust list. |

Notes:

- The owner cannot be removed.
- The command accepts mentions and raw user IDs.
- The daemon replies with a confirmation. The reply uses the same pacing as all other sends.

## Trigger log

The log has two ring buffers.

| Buffer | Limit | Content |
| --- | --- | --- |
| Trusted | 100 entries | Triggers from the owner and trusted users |
| Untrusted | 30 entries | Triggers from all other users |

One entry holds these fields:

| Field | Meaning |
| --- | --- |
| `id` | The message ID |
| `channelId` | The channel ID |
| `guildId` | The guild ID, or absent for a DM |
| `authorId` | The author user ID |
| `authorName` | The author username |
| `content` | The raw message content |
| `timestamp` | The message timestamp |
| `trusted` | True for a trusted author |
| `command` | The parsed command text, when the message is a command |

## Event flow

1. The client receives a `MESSAGE_CREATE` gateway event.
2. The core renderer normalizes the event.
3. The core bridge pushes the event to the daemon.
4. The daemon applies the trigger rules.
5. The daemon adds a qualifying message to the log.
6. The daemon runs a trusted command, when the message is a command.

## State file

The daemon stores the owner ID and the trust list in JSON.

- Default path: `poc/.veskslop-state.json`.
- Override: `VESKSLOP_STATE_FILE`.
- The trigger log is in memory only. The log resets at restart.

## How to add a trigger rule

1. Add the rule in `poc/src/puppet.ts`, in `handleEvent`.
2. Keep the rule small and testable.
3. Add a unit test in `poc/src/test-communication.ts` when the rule is pure logic.
4. Run `pnpm test:comm`.