# 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)