cg_api_secure-webshare/agent2_batch10.md

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)