70 lines
3.2 KiB
Markdown
70 lines
3.2 KiB
Markdown
# 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)
|