grok-telegram-bot 2.4.0 → 2.6.0

package/.env.example

@@ -6,8 +6,11 @@
 # REQUIRED — Telegram bot token from @BotFather (https://t.me/BotFather)
 TELEGRAM_BOT_TOKEN=
 
-# RECOMMENDED — comma-separated Telegram user IDs allowed to use the bot.
-# Get yours from @userinfobot. If empty, ANYONE can use the bot (unsafe).
+# RECOMMENDED — comma-separated Telegram user IDs allowed to use the bot
+# (private chats AND groups / forum topics). Get yours from @userinfobot.
+# Example: ALLOWED_USERS=123456789,987654321
+# If empty, ANYONE can use the bot (unsafe — especially with TOPIC_GROUP_ID).
+# Unauthorized group members are ignored silently (no ⛔ spam in the group).
 ALLOWED_USERS=
 
 # ── Grok Build CLI ───────────────────────────────────────────────────────────
@@ -96,6 +99,36 @@ NOTIFY_OTHER_SESSIONS=true
 #   2) second
 # SUGGESTIONS_AUTO_APPROVE_PCT=95
 
+# ── Forum topics (optional project workspace) ────────────────────────────────
+# Telegram forum supergroup id (negative for supergroups). When set, the bot
+# probes the group at startup / /forum_setup:
+#   • not admin (or no Manage Topics) → ignore group for topic features
+#   • Topics off → best-effort try to enable (Bot API has no official method;
+#     if it fails, enable Topics manually in group settings and re-run setup)
+#   • Topics on + admin → creates "AI Chat" + optional per-project topics
+#     (TOPIC_AUTO_CREATE), paced + 429-retried for large catalogs
+#   • pins favicon / MSIX logo when found; user topics auto-bind on exact
+#     catalog name match only (else absolute path / exact name)
+# Messages in a topic run Grok sessions in that topic's project path.
+# TOPIC_GROUP_ID=
+# TOPIC_AUTO_CREATE=true
+# TOPIC_AI_CHAT_NAME=AI Chat
+
+# ── Sibling Telegram bots (agent "MCP-like" tools via JSON actions) ──────────
+# Comma-separated usernames (with or without @) the agent may call with
+# bot_command / list_bots after the first-prompt Telegram bridge directive.
+# Example: ALLOWED_TELEGRAM_BOTS=helperbot,other_bot
+# ALLOWED_TELEGRAM_BOTS=
+# Optional command catalogs (shown by list_bots / first-prompt teaching).
+# Compact:  TELEGRAM_BOT_COMMANDS=helperbot:status,help,ping;otherbot:start|Start,info
+# JSON:     TELEGRAM_BOT_COMMANDS={"helperbot":["status","help"],"otherbot":[{"command":"start","description":"Start"}]}
+# TELEGRAM_BOT_COMMANDS=
+# Hard timeout waiting for a sibling bot after /cmd@bot (ms). Default 45000.
+# TELEGRAM_BOT_REPLY_TIMEOUT_MS=45000
+# Quiet settle after last message/edit from that bot (ms) — "typing done" for
+# streaming bots that edit one message. Default 2000.
+# TELEGRAM_BOT_SETTLE_MS=2000
+
 # ── Self-recheck (once per user prompt, gated) ───────────────────────────────
 # After a successful user turn (queue empty), the bot may run one quality pass.
 # Flow:
@@ -110,6 +143,9 @@ NOTIFY_OTHER_SESSIONS=true
 # Optional: when set AND the AI decides recheck is needed, use this template
 # instead of the AI-written recheck body ({{USER}} / {{DONE}} placeholders).
 # SELF_RECHECK_PROMPT=
+# Max wait (ms) for quiet meta prompts (recheck decision + suggestions JSON).
+# On timeout the session prompt is cancelled so ✅ Done is not blocked forever.
+# QUIET_PROMPT_TIMEOUT_MS=90000
 
 # ── MCP servers (/mcp) ───────────────────────────────────────────────────────
 # /mcp lists MCP servers the bot can discover and health-checks them. Grok Build

package/CHANGELOG.md

@@ -7,7 +7,194 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 The latest section is published verbatim as the GitHub Release notes by
 `.github/workflows/release.yml` when a `vX.Y.Z` tag is pushed.
 
-## [Unreleased]
+## [2.6.0] - 2026-08-30
+
+General becomes a chat-like **manager** for the forum group: memory-first
+routing, `send_prompt` into project topics with job report-back, and **visible
+short replies** (the previous notify-only quiet path looked like the bot was
+dead). Also bumps runtime deps (`tsx`, `grammy`).
+
+### Added
+
+- **General manager mode.** The forum **General** topic (`thread id 1`) is an
+  OpenClaw-style orchestrator, not a coding workspace. It keeps user messages,
+  starts a **new parallel session** per message (reply-to continues the same
+  session), streams **prose only** (no tools / progress / Done spam), and
+  dispatches real work into project topics.
+- **Manager directive + auto context.** First General prompt injects how to
+  behave (delegate, memory-first, no git-first). Every user turn also gets a
+  capped **MANAGER CONTEXT** block: topic catalog, recent General chat, ranked
+  memory hits, and in-process manager jobs.
+- **Manager jobs + work reports.** `send_prompt` from General registers a job
+  (`list_jobs`). When the child topic turn finishes, General is woken with a
+  structured `MANAGER WORK REPORT` so the manager can tell you done / failed.
+- **Bridge: `notify`, `list_topics`, `list_jobs`, `session_id`.**
+  - `notify` — optional extra ping (not required in General; prose is shown).
+  - `list_topics` / `list_jobs` — catalog and dispatch status for the agent.
+  - `send_prompt.session_id` — resume a **specific** Grok session (full UUID or
+    short prefix from memory). Topic may be omitted; path → forum topic is
+    inferred. Placeholder topics (`…`) are rejected / inferred from memory.
+- **Group memory ranking.** `search_memory` scores **relevance + recency**
+  (newest session per project path wins) so “last modifications” does not
+  surface stale Done notes. Hits include `[Xm/h/d ago]` stamps.
+- **Outbound General thread helper.** Telegram rejects `message_thread_id: 1`.
+  Sends/edits to General omit that field (`outboundThreadExtra`); inbound
+  routing still treats missing thread id as General.
+
+### Changed
+
+- **General UX.** User messages are **kept** (not replaced by prompt anchors).
+  Replies thread to the user message. A `Starting…` / `Thinking…` bubble is
+  edited in place into the short answer. Independent General messages no longer
+  coalesce into one queued turn.
+- **Prose is the user-facing channel.** The manager is told the user **sees**
+  free-form chat text. `notify` is optional. Bridge-result follow-ups (after
+  `search_memory` / `list_topics`) stream the real answer instead of staying
+  silent. If the model emits no prose, the Thinking bubble is replaced with a
+  short fallback — never deleted leaving an empty chat.
+- **Streamer prose-only mode.** General streams agent text only (no thoughts,
+  tools, plan board, or progress bar), seeded on the Thinking placeholder.
+- **Forum send path.** `sendMessage` / stream edits / auth deny / prompt
+  anchors / photos / docs use `outboundThreadExtra` so General posts succeed.
+- **Dependencies.** `tsx` `^4.19.2` → `^4.23.13`; `grammy` and `@types/node`
+  updated to current 1.x / 22.x wanted versions.
+
+### Fixed
+
+- **Bot not responding in General after manager-mode work.** Notify-only +
+  deleting `Thinking…` when `search_memory` chained made every answer vanish.
+  General now streams short prose, keeps the status bubble across bridge
+  follow-ups, and never drops the placeholder without a visible line.
+- **`message_thread_id: 1` rejected by Telegram** (“message thread not found”)
+  on General sends — omit the field for General; keep it for real topics.
+- **Manager context path trap.** Recent General history no longer treats every
+  session under the workspace root as General chat (title + exact cwd only).
+
+### Docs
+
+- **[docs/GROUP.md](./docs/GROUP.md)** — General = manager, memory-first
+  dispatch, `session_id`, `list_jobs`, prose vs `notify`.
+- **AGENTS.md** — General manager conventions for future changes.
+- **README** — General manager + expanded bridge actions.
+
+## [2.5.0] - 2026-08-05
+
+Forum project topics, cross-topic Telegram bridge, prompt anchors, and a more
+reliable Done / stop path for multi-topic groups.
+
+### Added
+
+- **Forum project topics (optional).** `TOPIC_GROUP_ID` manages a Telegram forum
+  supergroup: default **AI Chat** topic (workspace), optional auto-create one
+  topic per catalog project (`TOPIC_AUTO_CREATE`), favicon/MSIX logo discovery
+  pinned in the topic, and path-binding when users create new topics. Messages
+  in a topic run sessions in that project path.
+- **Telegram bridge actions (agent JSON).** On the first prompt of a session the
+  bot injects how-to-work memory: the agent may emit a fenced `json` block with
+  `"telegram": [ actions ]` to create forum topics, search session/topic memory,
+  list allowlisted sibling bots, and call them via `/cmd@bot` (MCP-like). Results
+  are fed back as a quiet follow-up turn (not a Done). Configure bots with
+  `ALLOWED_TELEGRAM_BOTS`, optional `TELEGRAM_BOT_COMMANDS` catalogs, reply
+  timeout / settle (`TELEGRAM_BOT_REPLY_TIMEOUT_MS`, `TELEGRAM_BOT_SETTLE_MS`).
+  Sibling-bot waits only accept content from the triggered bot (prefer reply-to
+  our trigger), collect edits until idle, and timeouts continue the session.
+  Bridge plumbing stays out of the chat (no “continuing session” / queue spam);
+  only durable side-effects like topic creation are announced.
+- **Cross-topic bridge actions.** From General / AI Chat (`GROK_WORKSPACE`), the
+  agent can orchestrate other forum topics via telegram JSON:
+  - `create_topic` with optional path
+  - **`set_path`** — bind/rebind a topic to an absolute path or exact catalog name
+  - **`send_prompt`** — inject a prompt into another topic’s session (`ran`/`queued`;
+    does not wait for that turn). Optional `new_session`.
+  Multiple actions run in order (cap **9**; up to **5** `send_prompt` per turn).
+  **New project paths:** agent `create_topic` / `set_path` with an absolute path
+  that does not exist yet **creates the folder** on disk, then binds the topic.
+- **New session on the persistent bar + `/new`.** Private chat: bar is
+  ☰ Menu · 🆕 New session / 🧭 Running · ⏹ Stop (not the inline Menu message).
+  Slash command `/new` (Telegram command list) starts a fresh session. Forum
+  topics keep New on the topic inline menu because reply keyboards are unreliable.
+- **Instant command feedback.** Slash commands and bar taps are deleted
+  immediately; handlers post bot status messages (e.g. `/new` →
+  “Creating new session…”) so the chat feels alive while the CLI/ACP starts.
+- **Prompt anchors + `#prompt_<id>`.** User prompts (text, photos, docs, voice,
+  `/btw`, suggestion taps) are re-posted as bot messages with a searchable
+  `#prompt_` tag; the originals are best-effort deleted. Photos, documents, and
+  voice/audio are re-attached on the anchor via Telegram `file_id` so media is
+  not lost when the user message is removed. All AI stream bubbles, Done/error
+  notices, and queue acks for that turn reply to the anchor and carry the same
+  tag (alongside `#proj_` / `#sess_`).
+
+### Changed
+
+- **Session card comments.** Cards (`/running`, `/sessions`, `/active`, status
+  panel) now show the **last user prompt** (max 250 chars). While a session is
+  running, a second line shows the **last AI agent thinking** (max 250). Idle
+  cards no longer use last-turn assistant outcome summaries as the comment.
+- **Stronger self-recheck prompts.** Decision + default recheck briefs now push
+  production-related completeness for the same feature (e.g. water→waves,
+  auth→rate limits), **finish-all** (no “still need…” / incomplete honest
+  leftovers that force critical follow-up buttons), and a required **per-bug
+  recheck checklist** at the end of the pass. Compose always injects those
+  rules when an AI brief looks complete (headers only) but omitted them.
+  `/new`, bar **New**, and inline **New** share the same success copy.
+
+### Fixed
+
+- **Missing `✅ Done` after a turn.** Done no longer waits on suggestion JSON
+  (send Done first, then attach buttons). Quiet meta prompts (recheck decision
+  + suggestions) use `QUIET_PROMPT_TIMEOUT_MS` (default 90s) and cancel the
+  session prompt on timeout so a hung meta call cannot block Done forever
+  (does not set user-cancelled / does not kill the agent). Chat shows
+  “Checking if a quality pass is needed…” while deciding recheck. Done text is
+  rebuilt after that wait so `/stop` mid-decision shows ⏹ Stopped. `notify`
+  retries truncated/plain text if the first send fails; a finally safety net
+  forces a short Done when one was expected but never delivered.
+- **`/stop` / `/cancel` must not kill the bot or other sessions.** Stop is
+  session-scoped only: soft ACP `session/cancel`, cancel pending permissions
+  for that session, and force-complete that session’s in-flight prompt after a
+  short grace if the agent is slow — **never** kill the shared `grok agent`
+  process (which multiplexes every chat/topic). `killPid` also refuses to
+  target the bot’s own Node process.
+- **`grok-tg install|start|restart` hang on Windows.** The service VBS is a
+  forever-restart loop (`Run …, True` waits for the bot). Launching it with
+  `execFileSync` made the CLI wait forever. Startup launches now use detached
+  `spawn` so the CLI returns immediately.
+- **No silent process death.** Exit paths always log reason + code to stderr/file;
+  instance-lock conflict uses exit 1; polling classifies 429/409/401/network with
+  backoff; interactive runs recover in-process (no detach re-exec that blanks the
+  terminal); ref'd keepalive every 5m; `beforeExit` keeps the process up if the
+  event loop empties unexpectedly. Updater re-exec inherits TTY stdio.
+- **Markdown / tool path rendering.** File paths in tool cards (Edit/Read/…) are
+  no longer wrapped in bold (Windows `C:\…` paths broke MarkdownV2 and fell
+  back to plain text that clients soft-render as `**Edit C:**`). Paths use
+  inline code; plain fallback demotes `**`/fences so soft-render cannot mangle
+  them. Chunked fences preserve tick length when reopening.
+- **Group / topic stop controls.** Forum topic menu leads with **Stop** + Running;
+  `/cancel` and `/stop` work in topics; group slash-command menu is a short,
+  sorted list with cancel first (private keeps the full sorted catalog). Stop
+  confirms in-thread (not only a toast).
+- **Forum topic bind: exact name only.** New user topics auto-bind when the
+  topic title exactly matches a catalog project (case-insensitive). Path prompts
+  and first messages no longer use fuzzy/partial project search (which could
+  bind the wrong folder). Unmatched topics still accept an absolute path or an
+  exact catalog name.
+- **Forum bulk topic create.** Startup/`/forum_setup` walks the **full** project
+  catalog (not a 200-item cap), paces creates, and retries on Telegram 429
+  (`retry_after`) and transient network errors so large catalogs (1000+) can
+  finish reliably across restarts.
+- **Forum group readiness.** Setup probes the configured group: if the bot is
+  not admin (or lacks Manage Topics), the group is **ignored** for topic
+  features. If Topics are off, the bot best-effort tries to enable them (no
+  official Bot API method today), otherwise ignores the group with a clear
+  status. Re-probes on promotion via `my_chat_member`; `/forum_setup` reports
+  ready vs disabled reason.
+
+### Docs
+
+- **README** updated for forum topics, bridge, prompt anchors, suggestions,
+  self-recheck, and related config.
+- **[docs/GROUP.md](./docs/GROUP.md)** — how to set up and use a forum project
+  group (binding, bridge actions, access control, troubleshooting).
 
 ## [2.4.0] - 2026-08-01
 
@@ -814,6 +1001,8 @@ from a single chat and switch between them, on a redesigned, compact menu.
   diffs, MarkdownV2 rendering, scheduled tasks, multi-image prompts, and a
   cross-platform 24/7 background service.
 
+[2.6.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.6.0
+[2.5.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.5.0
 [2.4.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.4.0
 [2.3.1]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.3.1
 [2.3.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.3.0

package/README.md

@@ -27,9 +27,16 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 | Capability | What it does |
 |---|---|
 | 🗂 **Projects** | `/projects` browses your folders and runs Grok in the one you pick. |
+| 🏷 **Forum project topics** | Optional forum supergroup: **General** manager, **AI Chat** workspace, one topic per project, exact-name bind, `/forum_setup`. See **[docs/GROUP.md](./docs/GROUP.md)**. |
+| 🎛 **General manager** | Forum General is a chat-like orchestrator: memory-first, short replies, `send_prompt` into project topics, report-back when child work finishes. |
+| 🌉 **Telegram bridge** | Agent can `create_topic`, `set_path`, `send_prompt` (optional `session_id`), `notify`, `search_memory`, `list_topics` / `list_jobs`, and call allowlisted sibling bots via JSON actions. |
+| 🔖 **Prompt anchors** | Each user prompt is re-posted with a searchable `#prompt_…` tag; stream/Done messages reply to that anchor (media re-attached). |
+| 🆕 **New session** | `/new` or the bar **New** button starts a fresh session; forum topics keep New on the topic menu. |
+| 💡 **Post-turn suggestions** | After Done, 1–3 scored follow-ups as buttons; high-score items can auto-queue as one multi-step prompt. |
+| 🔍 **Gated self-recheck** | After file-changing turns, an optional quality pass runs once before Done (`SELF_RECHECK`). |
 | ♻️ **Resume sessions** | `/sessions` lists recent Grok sessions; tap to resume one (`grok --session <id>`). |
 | 🟢 **Connect to live sessions** | `/active` shows sessions running **right now** on your PC. Watch them live, or continue them — see below. |
-| 🛑 **Kill a session / PID** | Each live `/sessions` · `/active` card has a **🛑 Kill · pid N** button (confirm-guarded) that stops that session's process and its child tree; `/killall` stops them all. The bot's own agent is never killable. |
+| 🛑 **Kill a session / PID** | Each live `/sessions` · `/active` card has a **🛑 Kill · pid N** button (confirm-guarded) that stops that session's process and its child tree; `/killall` stops them all. The bot's own agent is never killable. **Stop** only cancels the current session turn — never the shared agent. |
 | 📡 **Live watch** | Follow a running session read-only in real time (tails its event log). |
 | 🧭 **Always-visible menu** | A persistent keyboard plus a pinned status panel that appears while a task runs (and clears when idle), showing your current **project, agent, reasoning effort, model, session and queue**. |
 | ⏰ **Scheduled tasks** | Create prompts that run on a schedule (once / daily / weekly / monthly / every-N-minutes) in a chosen project, delivered back to your chat. |
@@ -49,7 +56,7 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 | 💬 **Quality markdown** | Converts agent markdown to Telegram **MarkdownV2** with safe escaping and code-fence-aware splitting. |
 | 🔁 **Self-healing** | Auto-restarts the Grok agent with backoff and re-binds your session. |
 | 🖥 **Runs 24/7** | 1-click install as a background service that starts on boot — Windows, Linux, macOS, auto-detected. |
-| 🔒 **Access control** | Restrict to specific Telegram user IDs. |
+| 🔒 **Access control** | Restrict to specific Telegram user IDs (private chats **and** forum groups). |
 
 ---
 
@@ -59,6 +66,9 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 |---|:---:|:---:|
 | Connect Grok CLI to Telegram (ACP) | ✅ | ✅ |
 | Switch between projects | ✅ | ❌ |
+| **Forum topics = projects** + AI Chat workspace | ✅ | ❌ |
+| **General manager** (memory-first, dispatch + report-back) | ✅ | ❌ |
+| **Cross-topic agent bridge** (create / bind / send_prompt / session_id) | ✅ | ❌ |
 | Resume saved sessions | ✅ | ❌ |
 | Attach to **live** PC sessions (watch / fork) | ✅ | ❌ |
 | **Kill a session by PID** (or all at once) | ✅ | ❌ |
@@ -69,6 +79,7 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 | **Session auto-approve** + **pinned** interactive permissions | ✅ | ❌ |
 | Multiple isolated sessions | ✅ | ❌ (single shared) |
 | Queued follow-ups while busy | ✅ | ❌ |
+| **Post-turn suggestions** + gated self-recheck | ✅ | ❌ |
 | **Scheduled tasks** (cron-like) | ✅ | ❌ |
 | **Multi-image** prompts (albums) | ✅ | ❌ |
 | Unified **edit diffs** | ✅ | ❌ |
@@ -216,14 +227,16 @@ Logs are written to `logs/grok-telegram-bot.log` (rotated at 5 MB).
 /tasks        Manage scheduled tasks
 /newtask      Create a scheduled task (wizard)
 /history      Show recent conversation history
-/new          Start a fresh session here
+/new          Start a fresh session here (also bar: 🆕 New session)
+/forum_setup  Re-probe / create forum topics (use inside the configured group)
 /status       Current session, project & queue
 /usage        Account info & current context usage
 /btw <text>   Run it now if idle, else queue to run right after the current task
 /flush        Send queued follow-ups now
 /queue        Show queued follow-ups
 /clearqueue   Clear the queue
-/cancel       Stop the current turn
+/cancel       Stop the current turn (session-scoped — never kills the shared agent)
+/stop         Same as /cancel
 /unwatch      Stop following a live session
 /model <id>   Switch the model for this session
 /restart      Restart the Grok agent
@@ -237,13 +250,28 @@ running, your messages are queued and sent automatically when it finishes.
 
 ---
 
+## 🏷 Forum project group (optional)
+
+Drive **many projects in parallel** from one Telegram forum supergroup: each
+topic is bound to a folder, and **AI Chat** stays on `GROK_WORKSPACE` for
+orchestration. Set `TOPIC_GROUP_ID`, make the bot admin with Manage Topics, and
+run `/forum_setup`. Full walkthrough (binding rules, agent bridge, access
+control, troubleshooting):
+
+**→ [docs/GROUP.md](./docs/GROUP.md)**
+
+---
+
 ## 🧭 The menu & status panel
 
-A tiny **persistent bar** sits under the message box — **☰ Menu · 🧭 Running ·
-⏹ Stop** — so common actions are one tap away without clutter. Tap **☰ Menu**
-(or `/menu`) to open a clean, grouped **inline menu**: Project · New · Running ·
-Sessions · Agent · Model · Reasoning · Tasks · Status · Usage · Stop · Kill all.
-The bar can be hidden (🙈) and restored (⌨️ Show bar or `/menu`).
+A tiny **persistent bar** sits under the message box — **☰ Menu · 🆕 New session
+· 🧭 Running · ⏹ Stop** (while idle/busy the middle button may show Running
+instead of New) — so common actions are one tap away without clutter. Tap
+**☰ Menu** (or `/menu`) to open a clean, grouped **inline menu**: Project ·
+Running · Sessions · Agent · Model · Reasoning · Tasks · Status · Usage · Stop ·
+Kill all. Forum topics keep **New** on the topic inline menu (reply keyboards are
+unreliable there). The bar can be hidden (🙈) and restored (⌨️ Show bar or
+`/menu`).
 
 While a task is running, a **pinned status panel** appears at the top of the chat
 showing your current **task progress, activity, queue, project, session, context
@@ -403,9 +431,9 @@ Resuming an **idle** session loads it directly so you continue the exact thread.
 | Variable | Required | Default | Description |
 |---|---|---|---|
 | `TELEGRAM_BOT_TOKEN` | **yes** | — | Bot token from @BotFather. |
-| `ALLOWED_USERS` | recommended | *(all)* | Comma-separated Telegram user IDs. Empty = anyone (unsafe). |
+| `ALLOWED_USERS` | recommended | *(all)* | Comma-separated Telegram user IDs for private chats **and** groups. Empty = anyone (unsafe — never leave empty with `TOPIC_GROUP_ID`). Unauthorized group members are ignored silently. |
 | `GROK_CLI_PATH` | no | auto / `grok` | Path to the `grok` binary. |
-| `GROK_WORKSPACE` | no | cwd | Default working directory. |
+| `GROK_WORKSPACE` | no | cwd | Default working directory (also AI Chat / General in a forum group). |
 | `XAI_API_KEY` | no | — | xAI API key, only for headless hosts with no browser. Normally you sign in with `grok login` (or `/reauth`) — no key needed. Exported to the agent when set. |
 | `GROK_MODEL` | no | `grok-4.5` | Default model for new sessions. |
 | `GROK_TG_DIR` | no | `~/.grok/tg` | Folder holding this instance's `.env`, `logs/`, `data/`. Resolution: `--instance` → `GROK_TG_DIR` → a `.env` in the current folder → `~/.grok/tg`. So a `.env` created once is loaded from any startup path. |
@@ -423,6 +451,18 @@ Resuming an **idle** session loads it directly so you continue the exact thread.
 | `SHOW_PROGRESS` | no | `true` | Ask the agent to append a `{progress: N%}` marker to each message; the bot parses it, hides the marker, and renders a green 0–100% bar on the live message, in session cards, and in the status panel. |
 | `PROGRESS_FALLBACK` | no | `true` | When `SHOW_PROGRESS` is on but the agent emits **no** `{progress: N%}` marker (weaker/free models and long tool-heavy turns often skip it), render a **bot-computed** bar derived from real activity (completed tool calls, streamed output, elapsed time) so a live bar still advances — filling to 100% when the turn completes. The agent's own marker, when present, always takes precedence and stays monotonic. |
 | `NOTIFY_OTHER_SESSIONS` | no | `true` | Deliver a session's "Done" summary (with a short created/edited/deleted count) even when it's a background session, marked "From other session". `false` keeps background sessions silent. |
+| `SUGGESTIONS_ENABLED` | no | `true` | After Done, quietly ask for 1–3 scored follow-ups shown as buttons. |
+| `SUGGESTIONS_AUTO_APPROVE_PCT` | no | `95` | Auto-queue suggestions with need ≥ this % as one multi-step prompt (`0` = buttons only). |
+| `SELF_RECHECK` | no | `true` | After a successful user turn that modified files, optionally run one gated quality pass before Done. Alias: `SLEF_RECHECK`. |
+| `SELF_RECHECK_PROMPT` | no | — | Optional fixed recheck template when AI decides recheck is needed (`{{USER}}` / `{{DONE}}`). |
+| `QUIET_PROMPT_TIMEOUT_MS` | no | `90000` | Max wait for quiet meta prompts (recheck decision + suggestions). Timeout cancels the meta prompt so Done is not blocked. |
+| `TOPIC_GROUP_ID` | no | — | Forum supergroup id for project topics. Bot must be admin with Manage Topics. See **[docs/GROUP.md](./docs/GROUP.md)**. |
+| `TOPIC_AUTO_CREATE` | no | `true` | When forum is ready, create one topic per catalog project (paced + 429-retried). |
+| `TOPIC_AI_CHAT_NAME` | no | `AI Chat` | Display name for the workspace topic. |
+| `ALLOWED_TELEGRAM_BOTS` | no | — | Comma-separated sibling bot usernames the agent may call via bridge `bot_command` / `list_bots`. |
+| `TELEGRAM_BOT_COMMANDS` | no | — | Optional command catalogs for sibling bots (compact or JSON; see `.env.example`). |
+| `TELEGRAM_BOT_REPLY_TIMEOUT_MS` | no | `45000` | Hard timeout waiting for a sibling bot after `/cmd@bot`. |
+| `TELEGRAM_BOT_SETTLE_MS` | no | `2000` | Quiet settle after the last message/edit from that bot. |
 | `MCP_PROBE_TIMEOUT_MS` | no | `8000` | Per-server timeout for the `/mcp` live health-check. |
 | `MCP_PROBE_CONCURRENCY` | no | `6` | How many MCP health probes run at once. |
 | `GROK_AUTO_RESTART` | no | `true` | Auto-restart the agent if it exits. |
@@ -475,11 +515,12 @@ src/
 ├── grok/                 Grok bridge: headless client, JSONL types, models, session log
 ├── sessions/             Session discovery, history parser, live tail watcher
 ├── projects/             Project directory discovery
+├── forum/                Forum topic store, path bind, project icons
 ├── mcp/                  MCP config (list/toggle) + live health probe
 ├── render/               Markdown→MarkdownV2, diffs, tool formatting, chunking
 ├── stream/               Incremental edit-streaming
 ├── service/              Cross-platform daemon (windows/linux/macos + selector)
-└── bot/                  grammY bot, per-chat runtime, handlers
+└── bot/                  grammY bot, per-chat runtime, handlers, Telegram bridge
 ```
 
 ---
@@ -549,10 +590,13 @@ user. See [SECURITY.md](./SECURITY.md) for the full model.
 - [x] Device-code `/reauth` (no host browser) + real email labels from auth.json
 - [x] Rich per-kind tool-call detail (search / edit diffs / shell / MCP / …)
 - [x] README community sections — Contributors, Top Contributors, Stars, StarMapper
+- [x] Forum project topics + AI Chat workspace (`TOPIC_GROUP_ID`)
+- [x] Cross-topic Telegram bridge (`create_topic` / `set_path` / `send_prompt` / …)
+- [x] Prompt anchors, post-turn suggestions, gated self-recheck
 - [ ] **Token & cost meter** — per-session token counts and an estimated spend tally
 - [ ] **Text-to-speech replies** — optionally speak answers back as voice notes
 - [ ] **Scheduled-task chaining & conditions** — run task B after A, or only if a command/file check passes
-- [ ] **Team mode** — multiple authorized users with per-user sessions, roles, and an audit log
+- [ ] **Team mode** — roles and audit log beyond shared `ALLOWED_USERS` + forum topics
 - [ ] Localized bot UI (i18n)
 - [ ] Docker image with `grok` preinstalled
 - [ ] Webhook mode for serverless deployment
@@ -657,8 +701,9 @@ Grab the latest packaged build from the
 release ships a clean `grok-telegram-bot-<version>.zip` (no `node_modules` or
 secrets) plus GitHub's source archives. See [CHANGELOG.md](./CHANGELOG.md) for
 what changed in each version, **[docs/INSTALL.md](./docs/INSTALL.md)** for the
-full 1-click install guide, and **[docs/UPGRADE.md](./docs/UPGRADE.md)** for how
-to update an existing install (npm, zip, or source).
+full 1-click install guide, **[docs/UPGRADE.md](./docs/UPGRADE.md)** for how to
+update an existing install (npm, zip, or source), and
+**[docs/GROUP.md](./docs/GROUP.md)** for forum project topics.
 
 ---