docs: document trusted_member_group_ids (config example + both READMEs + v3.9.0 changelog)

Author: Zakkaus

CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [3.9.0] - 2026-06-23
+
+### Added
+- **Trusted-member group bypass** (`trusted_member_group_ids`) — an applicant who is **already a member
+  of a configured trusted group** is auto-approved without the quiz, so verified members of a trusted
+  group (e.g. the main group) don't re-verify when joining a sub-group. Global default + per-group
+  override (same style as `required_channel_id`). Treated as an **access-control bypass, not a required
+  channel**: it **fails CLOSED** — if the source-group membership can't be confirmed (lookup error / bot
+  not in the group / non-member), the applicant just runs the normal verification; a failed auto-approve
+  is logged + alerted and also falls back, so a request is never left stuck. On a successful bypass it
+  clears any prior failed-verify strikes and records the approval — creating no pending and posting no
+  quiz. The trusted source groups are treated as **known chats** (`IsKnownChat`), so the auto-leave logic
+  never kicks the bot out of a group it needs to read membership from. A startup probe logs whether the
+  bot can read each trusted group's membership.
+
 ## [3.8.1] - 2026-06-23
 
 ### Changed

README.md

@@ -83,7 +83,7 @@ Everything else lives in `config.json` (copy `config.example.json`):
 
 | key | meaning |
 | --- | --- |
-| `groups` | per-group config: `[{id, required_channel_id?, channel_display?, channel_invite_url?, questions?}]`. Each optional field **falls back to the global default** below, so groups can share settings or be configured independently. A bare `group_ids` list (or singular `group_id`) is also accepted and treated as groups with no overrides |
+| `groups` | per-group config: `[{id, required_channel_id?, channel_display?, channel_invite_url?, trusted_member_group_ids?, questions?}]`. Each optional field **falls back to the global default** below, so groups can share settings or be configured independently. A bare `group_ids` list (or singular `group_id`) is also accepted and treated as groups with no overrides |
 | `required_channel_id` | **global default** channel applicants must join; `0` disables it (override per-group in `groups`) |
 | `channel_display` | **global default** channel shown to users, e.g. `@YourChannel` |
 | `channel_invite_url` | **global default** explicit join link; required for a **private** channel (no `@handle`) |
@@ -97,6 +97,7 @@ Everything else lives in `config.json` (copy `config.example.json`):
 | `verify_retry_seconds` | a declined applicant must wait this long before re-applying (default 180; negative = no cooldown) |
 | `verify_max_fails` | failed verifications before an applicant is auto-banned (default 3; negative = never auto-ban) |
 | `required_channel_fail_open` | when the bot can't read the required channel's membership, let verified applicants through (`true`, default) or hold them back (`false`). Admins are alerted either way |
+| `trusted_member_group_ids` | **trusted-member bypass**: an applicant who is **already a member of any of these chats** is auto-approved without a quiz (e.g. a sub-group trusting the main group's members). **Global default; override per-group** in `groups`. Use real chat ids (groups are `-100…`); the bot must be in each listed chat to read membership (they're treated as known chats, never auto-left). Unlike a required channel this **fails closed** — if membership can't be confirmed, the applicant just does the normal verification |
 | `admin_log_chat_id` | optional chat that receives a line per moderation / failed-approve event |
 | `overlays` | `/pkg` GitHub overlays `[{name,repo,branch}]` (default: gentoo-zh + guru) |
 | `news_url` | `/news` source index URL (default: gentoo.org news-items) |

README.zh-CN.md

@@ -68,7 +68,7 @@ GITHUB_TOKEN=ghp_xxx
 
 | 键 | 含义 |
 | --- | --- |
-| `groups` | 每个群单独配置:`[{id, required_channel_id?, channel_display?, channel_invite_url?, questions?}]`。每个可选字段**缺省时回落到下面的全局默认**,所以两个群既能共享设置、也能各自独立配置。也接受裸 `group_ids` 列表(或单数 `group_id`),当作无覆盖的群 |
+| `groups` | 每个群单独配置:`[{id, required_channel_id?, channel_display?, channel_invite_url?, trusted_member_group_ids?, questions?}]`。每个可选字段**缺省时回落到下面的全局默认**,所以两个群既能共享设置、也能各自独立配置。也接受裸 `group_ids` 列表(或单数 `group_id`),当作无覆盖的群 |
 | `required_channel_id` | **全局默认**:申请人必须关注的频道数字 id;`0` 关闭(可在 `groups` 里按群覆盖) |
 | `channel_display` | **全局默认**:展示给用户的频道,如 `@YourChannel` |
 | `channel_invite_url` | **全局默认**:频道邀请链接;**私有频道**(无 `@` 用户名)必填 |
@@ -82,6 +82,7 @@ GITHUB_TOKEN=ghp_xxx
 | `verify_retry_seconds` | 被拒申请人需等待多久才能重新申请(默认 180;负数 = 无冷却) |
 | `verify_max_fails` | 连续验证失败多少次后自动封禁(默认 3;负数 = 永不自动封禁) |
 | `required_channel_fail_open` | 当 bot 读不到必关频道成员状态时,放行已答题的申请人(`true`,默认)还是拦下(`false`)。两种情况都会告警管理员 |
+| `trusted_member_group_ids` | **可信成员免验证**:申请人若**已经是这些群之一的成员**,直接批准、跳过答题(例:子群信任主群的成员)。**全局默认,可在 `groups` 里按群覆盖**。用真实 chat id(群是 `-100…`);bot 必须在每个列出的群里才能读成员状态(它们会被当作已知聊天、不会被自动退出)。与必关频道不同,这里**fail-closed**——读不到成员身份就走正常验证,绝不直接放行 |
 | `admin_log_chat_id` | 可选:接收每次管理操作 / 批准失败的日志 |
 | `overlays` | `/pkg` 的 GitHub overlay `[{name,repo,branch}]`(默认 gentoo-zh + guru) |
 | `news_url` | `/news` 源索引 URL(默认 gentoo.org) |

config.example.json

@@ -1,7 +1,8 @@
 {
   "groups": [
     {"id": -1001234567890},
-    {"id": -1009876543210, "required_channel_id": -1001112223334, "channel_display": "@OtherChannel"}
+    {"id": -1009876543210, "required_channel_id": -1001112223334, "channel_display": "@OtherChannel"},
+    {"id": -1005556667778, "trusted_member_group_ids": [-1001234567890]}
   ],
   "required_channel_id": 0,
   "channel_display": "@YourChannel",
@@ -16,6 +17,7 @@
   "verify_retry_seconds": 180,
   "verify_max_fails": 3,
   "required_channel_fail_open": true,
+  "trusted_member_group_ids": [],
   "admin_log_chat_id": 0,
   "rich_messages": false,
   "user_agent": "",