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

agent2_batch10.md

@@ -0,0 +1,69 @@
+# Batch 10 — Documentation Updates
+
+## Summary
+Updated `docs/COMMANDS.md` and `docs/MODERATION.md` to reflect changes from the refinement pass.
+
+---
+
+## docs/COMMANDS.md Changes
+
+### 1. `/get_id` — now available in channels too (admin-only)
+- Changed section header from **"Admin Commands (Group-only)"** to **"Admin Commands (Groups & Channels)"**.
+- Added note: "They work in groups, supergroups, and channels where the bot is present."
+- Updated `/get_id` descriptions to mention it works in groups, supergroups, and channels.
+
+### 2. `/help` — `[arg]` format note
+- Added note to `/help` description: "Argument placeholders in the help text use `[arg]` format to avoid Telegram HTML parse errors with angle brackets."
+
+### 3. `/blacklist_uid` and `/whitelist_uid` — stricter restrictions + usage info
+- Updated descriptions to explicitly state: **"Restricted to configured admin groups; the caller must be an admin there."**
+- Added the exact usage info shown when args are missing:
+  - `/blacklist_uid`: `Usage: /blacklist_uid <user_id>`
+  - `/whitelist_uid`: `Usage: /whitelist_uid <user_id>`
+
+### 4. Punishment commands — propagation note
+- Added to `/sban`, `/smute`, `/mute`, `/pban`, `/kick` descriptions:
+  - **"Propagates across all known chats when `global_ban = true`."**
+
+### 5. Forward submission review buttons
+- Added new **"Review Message Buttons"** subsection under Forward Submissions.
+- Documents the inline keyboard layout on review messages:
+  - Row 1: `[ Approve ]`, `[ Ignore ]`
+  - Row 2: `[ Blackl. ]`, `[ Ban ]`, `[ Ban/BL u. ]`
+- Notes these correspond to the existing `v1:fwd:...` callbacks.
+
+---
+
+## docs/MODERATION.md Changes
+
+### 1. `global_ban` config option under `[groups]`
+- Reworded the **Global Ban Configuration** intro to clarify: "The `[groups]` section in the config contains the optional `global_ban` flag (default `false`)."
+- Included `/kick` in the list of propagated commands.
+
+### 2. Propagated punishments recorded per-chat
+- Added **"Propagation Behavior"** subsection.
+- Documents that each propagated punishment is a **separate row** in `punishments` with its own `chat_id`.
+- Explains implications:
+  - Background expiration revokes each independently.
+  - Manual `/rmute`/`/rban` only affects the local chat.
+  - Bot skips chats where it is not an admin and logs a warning.
+
+### 3. Hash blacklist behavior (migration 007, `HashBlacklistRepo`)
+- Added new **"Hash Blacklist"** section.
+- Includes the `007_hash_blacklist.sql` schema.
+- Documents `HashBlacklistRepo::insert` and `HashBlacklistRepo::contains`.
+- Describes pipeline behavior: BLAKE3 plaintext hash is checked against the blacklist **before** deduplication and persistence; blocked hashes raise `BlockedHash` and discard the temp file.
+
+### 4. Username tracking (`uname_changes_path` config)
+- Added new **"Username Tracking"** section.
+- Documents config placement (top-level, default `"data/uname_changes.json"`).
+- Explains trigger: `UserRepo::ensure_exists` on every message/callback.
+- Shows JSON line format with `timestamp`, `user_id`, `chat_id`, `old_username`, `new_username`.
+- Notes append-mode file handling.
+
+---
+
+## Changed Files
+- `docs/COMMANDS.md`
+- `docs/MODERATION.md`
+- `progress.md` (updated)