update readmes

CommunitiesBot/README.md

@@ -1,12 +1,50 @@
 # CommunitiesBot
 
-Demonstrates Communities support introduced in Telegram Bot API 10.2.
+This long-polling example demonstrates Communities support introduced in Telegram Bot API 10.2: typed service events when a chat joins or leaves a community, and inspection of a chat's current community.
 
-Add the bot to a chat that belongs to a community. It reports when the chat is added to or removed from a
-community, and `/community` prints the chat's current community (read from `getChat().community`).
+## Behavior, commands, and triggers
+
+At startup, the bot calls `getMe` and prints its bot information. It also prints every received update to standard output.
+
+| Command or trigger | Behavior |
+| --- | --- |
+| `community_chat_added` service message | `onCommunityChatAdded` logs the chat and community name/ID, sends a join notice, then calls `getChat` and logs its nullable `community`. |
+| `community_chat_removed` service message | `onCommunityChatRemoved` logs the chat and sends a leave notice. This event is fieldless, so it has no former-community details. |
+| `/community` | Calls `getChat` and replies with the current community name/ID, or says the chat is not in a community. |
+| `/wait_community_added` | Waits without a timeout for the next added event in the command's chat, then replies with the community name/ID. |
+| `/wait_community_removed` | Waits without a timeout for the next removed event in the command's chat, then replies with the chat ID. Its initial waiting reply currently says "added." |
+
+Commands use no positional arguments; other commands only appear in the generic update log. Each wait first sends a waiting reply, filters events with `sameChat`, and takes the first match.
+
+## API concepts
+
+- `CommunityChatAdded` carries a `Community` with a `CommunityId` and name; `CommunityChatRemoved` carries no fields.
+- `onCommunityChatAdded` and `onCommunityChatRemoved` provide typed handlers for the service events.
+- `getChat(...).community` exposes the nullable community on `ExtendedChat` without a subtype cast.
+- `waitCommunityChatAddedEventsMessages` and `waitCommunityChatRemovedEventsMessages` expose typed event-message flows.
+
+## Telegram setup and permissions
+
+1. Create a bot with BotFather and obtain its token.
+2. Add it to the target chat before changing that chat's community membership if you want to observe both service events.
+3. Allow it to send messages so notifications and command replies succeed.
+
+The bot does not create or modify communities. It calls no administrator-only method and does not inspect arbitrary user messages, so it needs neither administrator rights nor disabled Group Privacy Mode. The user changing community membership still needs the appropriate Telegram rights. API failures are left to the library's normal error handling.
+
+## Arguments
+
+The token is required as the first argument. Optional flags are exact and case-sensitive, may follow in either order, and unknown extra arguments are ignored.
+
+| Argument | Effect |
+| --- | --- |
+| `BOT_TOKEN` | Bot token; omitting it fails before polling starts. |
+| `debug` | Sends tgbotapi/KSLog diagnostics to standard output. |
+| `testServer` | Uses Telegram's Bot API test environment. |
 
 ## Launch
 
+From the repository root:
+
 ```bash
-../gradlew :CommunitiesBot:run --args="BOT_TOKEN"
+./gradlew :CommunitiesBot:run --args="BOT_TOKEN"
 ```

CommunitiesBot/src/main/kotlin/CommunitiesBot.kt

@@ -22,21 +22,17 @@ import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.first
 
 /**
- * This bot demonstrates Communities support introduced in Telegram Bot API 10.2.
+ * Starts a long-polling bot that demonstrates Telegram Communities.
  *
- * A community groups several chats together. When a chat is added to (or removed from) a community, the bot
- * receives a service event in that chat.
+ * [onCommunityChatAdded] receives the joined [dev.inmo.tgbotapi.types.communities.Community], while
+ * [onCommunityChatRemoved] receives a fieldless removal event. `/community` reads
+ * [dev.inmo.tgbotapi.types.chat.ExtendedChat.community] with [getChat]. The two wait commands use
+ * [waitCommunityChatAddedEventsMessages] and [waitCommunityChatRemovedEventsMessages] to take the first same-chat
+ * event without a timeout. The bot prints its [getMe] result and every received update.
  *
- * Key concepts demonstrated:
- * - [onCommunityChatAdded] — trigger for the `community_chat_added` service event. The handler receives a
- *   [dev.inmo.tgbotapi.types.message.abstracts.ChatEventMessage] carrying a
- *   [dev.inmo.tgbotapi.types.communities.CommunityChatAdded] whose `community` is the
- *   [dev.inmo.tgbotapi.types.communities.Community] (`id`: [dev.inmo.tgbotapi.types.communities.CommunityId],
- *   `name`) the chat was added to
- * - [onCommunityChatRemoved] — trigger for the fieldless `community_chat_removed` service event
- * - [waitCommunityChatAdded] — expectation returning a flow of [dev.inmo.tgbotapi.types.communities.CommunityChatAdded]
- * - [dev.inmo.tgbotapi.types.chat.ExtendedChat.community] — the community a chat belongs to
- *   (`ChatFullInfo.community`), available directly from [getChat] without any cast
+ * @param args the bot token followed by the optional, case-sensitive `debug` and `testServer` flags; unknown trailing
+ * arguments are ignored
+ * @throws NoSuchElementException when the required bot token is absent
  */
 suspend fun main(vararg args: String) {
     val botToken = args.first()
@@ -89,14 +85,14 @@ suspend fun main(vararg args: String) {
             )
         }
 
-        // waitCommunityChatAdded expectation: suspend until this chat is added to a community
+        // Suspend until the next community-added event message from this chat.
         onCommand("wait_community_added") { origin ->
             reply(origin, "Waiting for this chat to be added to a community...")
             val event = waitCommunityChatAddedEventsMessages().filter { it.sameChat(origin) }.first().chatEvent
             reply(origin, "Chat added to community: ${event.community.name} (id=${event.community.id.long})")
         }
 
-        // waitCommunityChatAdded expectation: suspend until this chat is added to a community
+        // Suspend until the next community-removed event message from this chat.
         onCommand("wait_community_removed") { origin ->
             reply(origin, "Waiting for this chat to be added to a community...")
             waitCommunityChatRemovedEventsMessages().filter { it.sameChat(origin) }.first()