update readmes

ChecklistsBot/README.md

@@ -0,0 +1,75 @@
+# ChecklistsBot
+
+This example shows how to receive Telegram checklist messages and checklist service events with
+the TelegramBotAPI behaviour builder. It mirrors each checklist as a formatted text reply; it does
+not create or edit checklists and stores no state.
+
+## Behaviour
+
+The bot uses long polling and installs these handlers:
+
+| Incoming update | Response |
+| --- | --- |
+| A message containing a checklist | Replies to that message with the checklist's current contents. |
+| Tasks marked as done or not done | Replies to the checklist-status service message with the full current checklist. If at least one task was newly marked done, the reply includes the first such task's ID as `checklist_task_id`; an event containing only newly reopened tasks gets a normal message-level reply. |
+| Tasks added to a checklist | Replies to the original checklist and targets the first newly added task with `checklist_task_id`, then includes the full current checklist. |
+
+The text snapshot preserves the title and task text entities. Each task is rendered on its own line
+as `• [x] task` when it has a completion date or `• [ ] task` otherwise; the marker is formatted as
+code and the task text as bold.
+
+There are no bot commands. On startup the bot prints the result of `getMe`, and it prints every raw
+update it receives. The optional `debug` flag additionally sends TelegramBotAPI diagnostic logs to
+standard output.
+
+## Telegram setup
+
+1. Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token.
+2. Start the example, open a private chat with the bot, and send it a checklist. Telegram Premium is
+   currently required to create a checklist in Telegram clients. Use the checklist's own options if
+   other participants should be allowed to add tasks or change their completion state.
+3. For group testing, ensure the bot may send messages and can receive the original checklist.
+   Ordinary checklist messages are hidden by the default Group Privacy Mode, so make the bot a group
+   administrator or disable privacy with BotFather and re-add the bot to the group.
+
+No Telegram Business connection or business-bot right is required: the example only receives
+checklists and sends ordinary text replies. Telegram restricts the `sendChecklist` Bot API method,
+which this example does not use, to connected business accounts.
+
+## Run
+
+From the repository root:
+
+```bash
+./gradlew :ChecklistsBot:run --args="<BOT_TOKEN>"
+```
+
+The token must be first. The remaining optional flags are exact, case-sensitive strings and may be
+supplied in either order:
+
+| Argument | Required | Meaning |
+| --- | --- | --- |
+| `<BOT_TOKEN>` | Yes | Bot token; it must be the first argument. |
+| `debug` | No | Enables verbose TelegramBotAPI logging on standard output. |
+| `testServer` | No | Uses Telegram's Bot API test environment (`/test`) instead of production. |
+
+For example:
+
+```bash
+./gradlew :ChecklistsBot:run --args="<BOT_TOKEN> debug testServer"
+```
+
+Do not run another webhook or long-polling consumer with the same token while this example is
+running.
+
+## API concepts demonstrated
+
+- `onChecklistContent` for checklist content messages.
+- `onChecklistTasksDone` for service messages that contain both completed and reopened task IDs.
+- `onChecklistTasksAdded` for task-addition service messages.
+- Entity-aware output with `buildEntities`, `code`, and `bold`.
+- Replies to a specific checklist item through `checklist_task_id`.
+
+See Telegram's [Checklist and ChecklistTask objects](https://core.telegram.org/bots/api#checklist)
+and [checklist launch announcement](https://telegram.org/blog/checklists-suggested-posts#checklists)
+for the underlying platform behaviour.

ChecklistsBot/src/main/kotlin/ChecklistsBot.kt

@@ -46,6 +46,17 @@ import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.first
 
+/**
+ * Starts a long-polling bot that renders incoming checklists as formatted text and reports
+ * checklist task additions and completion-state changes with task-aware replies.
+ *
+ * The first argument is the required bot token. The optional, case-sensitive `debug` and
+ * `testServer` arguments enable verbose library logging and Telegram's Bot API test environment,
+ * respectively. The bot identity and every received update are printed to standard output in all
+ * modes.
+ *
+ * @param args bot token followed by optional `debug` and `testServer` flags
+ */
 suspend fun main(vararg args: String) {
     val botToken = args.first()
 
@@ -65,7 +76,6 @@ suspend fun main(vararg args: String) {
         CoroutineScope(Dispatchers.Default),
         testServer = isTestServer,
     ) {
-        // start here!!
         val me = getMe()
         println(me)