V0.1.1 release, close to actual release. Bug & security fixes/improvements.

docs/MODERATION.md

@@ -152,7 +152,7 @@ This is used both for:
 
 ## Global Ban Configuration
 
-Under `[groups]` in the config, the optional `global_ban` flag (default `false`) controls whether punishment commands (`/sban`, `/smute`, `/mute`, `/pban`) are propagated across all known chats where the bot is an administrator.
+The `[groups]` section in the config contains the optional `global_ban` flag (default `false`). When enabled, punishment commands (`/sban`, `/smute`, `/mute`, `/pban`, `/kick`) are propagated across all known chats where the bot is an administrator.
 
 ```toml
 [groups]
@@ -161,7 +161,57 @@ review_group_ids = [-1009876543210]
 global_ban = false
 ```
 
-- When `global_ban = true`, issuing a punishment in any admin group is intended to apply the same action to every known chat (source chats, destination chats, review groups, and configured `admin_group_ids` / `review_group_ids`) where it has admin rights.
+- When `global_ban = true`, issuing a punishment in any admin group applies the same action to every known chat (source chats, destination chats, review groups, and configured `admin_group_ids` / `review_group_ids`) where the bot has admin rights.
 - When `global_ban = false` (default), punishments are local to the group where the command was issued.
 
-**Note:** When `global_ban = true`, the bot propagates the punishment to every configured `admin_group_ids`, `review_group_ids`, and all active forward chats (source, destination, and review groups) where it has administrator rights. Each propagated action is recorded as a separate `punishments` row.
+### Propagation Behavior
+
+Each propagated punishment is recorded as a **separate row** in the `punishments` table, with its own `chat_id`. This means:
+- The background expiration task naturally revokes each per-chat punishment independently.
+- Manual `/rmute` or `/rban` only affects the chat where the revoke command was issued.
+- The bot skips any chat where it is not an administrator and logs a warning.
+
+---
+
+## Hash Blacklist
+
+Migration `007_hash_blacklist.sql` creates the `hash_blacklist` table:
+
+```sql
+CREATE TABLE hash_blacklist (
+    hash BLOB PRIMARY KEY,
+    created_at DATETIME NOT NULL DEFAULT (datetime('now')),
+    reason TEXT
+);
+```
+
+The `HashBlacklistRepo` (in `crates/cgcx-db/src/repos.rs`) provides:
+- `insert(hash, reason)` — Adds a hash to the blacklist (ignored if already present).
+- `contains(hash)` — Returns `true` if the hash is blacklisted.
+
+During file ingestion (`crates/cgcx-file-pipeline/src/lib.rs`), the pipeline computes a **plaintext BLAKE3 hash** and checks it against `hash_blacklist` **before** deduplication and persistence. If the hash is blocked, ingestion is rejected with a `BlockedHash` error and the temporary file is discarded.
+
+---
+
+## Username Tracking
+
+The bot can log username changes to a JSON file for audit and moderation purposes.
+
+### Configuration
+
+Set `uname_changes_path` at the top level of the config (default: `"data/uname_changes.json"`):
+
+```toml
+database_path = "data/db.sqlite"
+uname_changes_path = "data/uname_changes.json"
+```
+
+### How It Works
+
+On every message and callback interaction, the bot calls `UserRepo::ensure_exists(...)`, passing the configured path. If the user's stored username differs from the current one, a JSON line is appended to the file:
+
+```json
+{"timestamp":"2026-05-24T12:34:56Z","user_id":123456789,"chat_id":-1001234567890,"old_username":"old_name","new_username":"new_name"}
+```
+
+The file is opened in append mode and created automatically if it does not exist.