clisbot 0.1.53-beta.5 → 0.1.53

package/README.md

@@ -14,7 +14,7 @@
   <a href="https://www.npmjs.com/package/clisbot"><img src="https://img.shields.io/npm/dm/clisbot?label=downloads&color=22c55e" alt="npm downloads per month" /></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-d4a017" alt="MIT license" /></a>
   <img src="https://img.shields.io/badge/CLI-Codex%20%7C%20Claude%20%7C%20Gemini-111827" alt="supported cli tools" />
-  <img src="https://img.shields.io/badge/Channels-Slack%20%7C%20Telegram-0a66c2" alt="supported channels" />
+  <img src="https://img.shields.io/badge/Channels-Slack%20%7C%20Telegram%20%7C%20Zalo-0a66c2" alt="supported channels" />
   <img src="https://img.shields.io/badge/Runtime-tmux%20backed-16a34a" alt="tmux backed runtime" />
   <img src="https://img.shields.io/badge/Workflow-AI--native-f59e0b" alt="AI-native workflow" />
 </p>
@@ -24,145 +24,81 @@
 </p>
 
 # clisbot - Turn your favorite coding CLI into an agentic personal assistant, workplace assistant, coding partner - on the go
-Want to use OpenClaw but are struggling because:
+Want to use OpenClaw / Hermes Agent but are struggling because:
 
 - API cost is too high, so you end up looking for LLM proxy workarounds
-- you have to switch between OpenClaw for daily work and Claude / Codex / Gemini for real coding
+- you have to switch between OpenClaw / Hermes Agent for daily work and Claude / Codex / Gemini for real coding
 - you want to code on the go and work on the go
 
 `clisbot` is the right solution for you.
 
-`clisbot` turns native frontier agent CLIs like Claude Code, Codex, and Gemini CLI into durable Slack and Telegram bots. Each agent runs inside its own tmux session, keeps a real workspace, and can behave like a coding bot, a daily-work assistant, or a team assistant with SOUL, IDENTITY, and MEMORY.
+`clisbot` turns native frontier agent CLIs like Claude Code, Codex, and Gemini CLI into durable chat-native bots across multiple channels. Current channels include Slack, Telegram, Zalo Bot, and Zalo Personal, with more to come. Each agent runs inside its own tmux session, keeps a real workspace, and can behave like a coding bot, a daily-work assistant, or a team assistant with SOUL, IDENTITY, and MEMORY.
 
-It is not just a tmux bridge with chat glued on top. `clisbot` treats Slack and Telegram as real channel surfaces with routing, durable conversation state, pairing, follow-up control, file sending and receiving, and the ability to keep frontier coding agents inside the tools and communication surfaces where teams already work.
+It is not just a tmux bridge with chat glued on top. `clisbot` treats chat platforms as real channel surfaces, including Slack, Telegram, Zalo Bot, and Zalo Personal today, with routing, durable conversation state, pairing, follow-up control, file sending and receiving, and the ability to keep frontier coding agents inside the tools and communication surfaces where teams already work.
 
 `clisbot` is also meant to grow into a reusable agent runtime layer that can support many CLI tools, many channels, and many workflow shapes on top of the same durable agent session.
 
-## Start Here By Goal
-
-### I Want A Personal Coding Bot In Telegram Or Slack
-
-- start with the [Quick Start](#quick-start)
-- best fit when you want Codex, Claude, or Gemini available from chat without
-  giving up a real workspace
-- current release value: a much more AI-native control path, where the bot can
-  increasingly set up `/queue`, loops, schedules, and other recurring work for
-  you from normal chat instead of forcing you to memorize command syntax first
-
-### I Want A Shared Team Bot
-
-- start with [Quick Start](#quick-start), then read [Surface Access Model](#surface-access-model)
-- best fit when you need one bot in a real Slack channel, Telegram group, or
-  Telegram topic with explicit route and sender control
-- current release value: safer shared-surface policy, tighter topic or thread
-  isolation, per-group sender control, and permission boundaries that let one
-  bot live in a team group without opening it to everyone there
-
-### I Need Operator Control And Debugging
-
-- start with [Common CLI commands](#common-cli-commands)
-- most useful surfaces: `clisbot status`, `clisbot logs`,
-  `clisbot watch --latest`, `clisbot inspect --latest`, and `clisbot queues`
-- current release value: more truthful `sessionId`, lighter runner inventory,
-  and less confusing restart behavior during updates
-
-### I Just Want To Know What Changed Recently
-
-- start with [Recent Release Highlights](#recent-release-highlights)
-- then read [v0.1.52 Release Notes](docs/releases/v0.1.52.md) or the
-  [v0.1.52 Release Guide](docs/updates/releases/v0.1.52-release-guide.md)
-
 ## Why I Built This
 
 I’m Long Luong (Long), Co-founder & CTO of Vexere, Vietnam’s #1 transportation booking platform, where we also build SaaS and inventory distribution infrastructure for transportation operators. As we scale a 300-person company with a 100-member Engineering, Product, and Design team, I’ve been searching for the most practical way to roll out AI-native workflows across the organization.
 
 The challenge is not whether AI is useful. It is how to make it work at enterprise scale without creating a fragmented, expensive, or ungovernable stack. In practice, that means solving several hard problems at once: cost control, workflow truthfulness, team accessibility, governance, and the ability to bring frontier AI into the real tools and communication surfaces where work already happens.
 
-`clisbot` is the approach I landed on. Instead of building yet another isolated AI layer, it turns the coding CLIs we already trust into durable, chat-native agents that can work across Slack, Telegram, and real team workflows.
-
-## Why clisbot
-
-- One frontier-agent stack for both daily work and real coding. You do not need one product for assistant work and another for actual engineering work.
-- Reuses native CLI subscriptions you already pay for, such as Claude Code, Codex, and Gemini CLI, instead of pushing you toward a separate API-cost-heavy stack.
-- Learns from and integrates the two biggest strengths that made OpenClaw popular: memory and native channel integration with deep, channel-specific conversation and presentation capabilities.
-- Not just a tmux bridge. Slack and Telegram are treated as real channel surfaces with routing, thread or topic continuity, pairing, follow-up control, and attachment-aware interaction instead of plain text passthrough so you can work from your laptop or on the go without giving up a real coding workspace.
-- Team-first by design, with `AGENTS`, `USER`, and `MEMORY` context bootstrapping shaped for shared team reality instead of only personal solo-assistant flows.
-- Shared-surface permission control is a first-class feature: a bot can be in a team group but still answer only the specific people you allow there, while sensitive control actions stay behind explicit auth roles and permissions.
-- Useful for coding, operations, teamwork, and general assistant work, with fast chat controls such as `!<command>`, `/bash <command>`, `/queue`, `/loop`, `/streaming`, and `/mention`.
-- New in the `v0.1.50` to `v0.1.52` stable line: the AI-native control experience is much better, the default runner startup window is now 60 seconds, and stale old startup-delay pins no longer silently keep upgraded installs on shorter timeouts.
-
-## Who This Fits Best
-
-- Anyone who wants a high-agency personal assistant with OpenClaw-style memory,
-  workspace context, and a skill-oriented operating model that can do far more
-  than a thin chat wrapper.
-- Solo builders who want a real coding assistant in Telegram or Slack, backed
-  by Codex, Claude, or Gemini, without rebuilding their workflow around a new
-  web product.
-- Team leads who want one shared bot with explicit group or topic safety,
-  durable context, and attachment-aware chat workflows.
+`clisbot` is the approach I landed on. Instead of building yet another isolated AI layer, it turns the coding CLIs we already trust into durable, chat-native agents that can work across Slack, Telegram, Zalo surfaces, and real team workflows.
 
-## Surface Access Model
+If `clisbot` helps your workflow, a GitHub star is a simple way to let me know
+it is useful and help more people discover it.
 
-The important current config mental model is:
-
-- `app`
-- `bots`
-- `agents`
-
-Inside each bot:
-
-- `directMessages` is the one-person surface map
-- `groups` is the multi-user surface map
-- stored keys use raw provider-local ids plus `*`
-
-Examples:
-
-- Slack shared surface: `groups["C1234567890"]`
-- Telegram group: `groups["-1001234567890"]`
-- Telegram topic: `groups["-1001234567890"].topics["42"]`
-- DM wildcard default: `directMessages["*"]`
-
-Operator CLI ids stay prefixed:
-
-- `dm:<id>`
-- `dm:*`
-- `group:<id>`
-- `group:*`
-- `topic:<chatId>:<topicId>`
-
-Current invariants:
+## Quick Start
 
-- Slack `channel:<id>` is compatibility input only, not canonical operator naming
-- stored config under one bot uses only raw ids plus `*` inside `directMessages` and `groups`
-- `group:*` is the default multi-user sender policy node for one bot and should be updated or disabled, not removed
-- `disabled` means silent for everyone on that surface, including owner/admin and pairing guidance
-- owner/admin do not bypass `groupPolicy`/`channelPolicy` admission; after a group is admitted and enabled, they bypass sender allowlists, while `blockUsers` still wins
-- the deny message intentionally uses one common human-facing term, `group`, for every multi-user surface
+### AI-Assisted Setup
 
-## CLI Compatibility Snapshot
+If you already use Codex, Claude Code, or Gemini CLI, open this repo in that
+CLI and paste this short prompt first:
 
-`clisbot` currently works well with Codex, Claude, and Gemini.
+```text
+Help me clarify and set up clisbot from this GitHub repo: https://github.com/longbkit/clisbot
+```
 
-| CLI      | Current Stability   | Short Take                                                                                                  |
-| ----------| ---------------------| -------------------------------------------------------------------------------------------------------------|
-| `codex`  | Best today          | Strongest default for routed coding work.                                                                   |
-| `claude` | Usable with caveats | Claude can surface its own plan-approval and auto-mode behavior even when launched with bypass-permissions. |
-| `gemini` | Fully compatible   | Gemini is supported as a first-class runner for routed Slack and Telegram workflows.                         |
+If you already know what you want, paste this more specific prompt instead and
+fill the placeholders:
 
-CLI-specific operator notes:
+```text
+Help me clarify and set up clisbot from this GitHub repo: https://github.com/longbkit/clisbot
 
-- [Codex CLI Guide](docs/user-guide/codex-cli.md)
-- [Claude CLI Guide](docs/user-guide/claude-cli.md)
-- [Gemini CLI Guide](docs/user-guide/gemini-cli.md)
+I want:
+- target channel: <Slack|Telegram|Zalo Bot|Zalo Personal>
+- coding CLI tool: <Codex|Claude Code|Gemini CLI>
+- usage shape: <personal assistant|team assistant>
+```
 
-## Quick Start
+For AI agents: use the guide below to help a user install, set up, and onboard
+with `clisbot` with as little friction as possible.
+
+1. Ask only the smallest number of clarify questions needed. In particular,
+   clarify:
+   - target channel: Slack, Telegram, Zalo Bot, or Zalo Personal
+   - coding CLI tool: Codex, Claude Code, or Gemini CLI
+   - usage shape: personal assistant or team assistant
+2. Prefer persisting credentials by default after the first successful test, so
+   later restarts can use plain `clisbot start` without retyping tokens.
+3. Read `README.md` and `docs/user-guide/README.md`, then guide the shortest
+   safe setup path. Run the right `clisbot` commands when the environment
+   allows it, and verify with status/logs.
+4. If a step must be done manually, such as creating a bot, setting up a Slack
+   app, or logging in to Zalo Personal, explain exactly what the user must do
+   and wait for them before continuing.
+5. If a technical limit prevents running a command, give the exact terminal
+   command for the user to run. If an unresolved bug blocks setup, help the user
+   report a GitHub issue or submit feedback at
+   https://docs.google.com/forms/d/e/1FAIpQLSd7L7mHOo0ea8YXFI4tGnyDIj94ESn4hbbDa5YTbcEKTVOKTA/viewform.
 
 Platform support:
 
 - Linux and macOS are the supported host environments today.
-- Native Windows is not supported yet because `clisbot` currently depends on `tmux` and Bash-based runtime flows.
-- If you use Windows, run `clisbot` inside WSL2.
+- If you use Windows, run `clisbot` inside WSL2 because native Windows is not supported yet; `clisbot` currently depends on `tmux` and Bash-based runtime flows.
+
+### Manual Setup
 
 Most people should start here:
 
@@ -185,43 +121,13 @@ Next steps:
 - `clisbot` also has a smart autopairing path to reduce first-run friction. If
   you send the bot a DM within the first 30 minutes, you can usually claim the
   owner role immediately and start using it without a separate pairing round.
-- New from the current `v0.1.50` to `v0.1.52` stable line: the AI-native operator experience is much stronger. You
-  can increasingly ask the bot through chat to explain how to use it, update
-  itself and summarize what's new, help onboard you, create or add a new bot or
-  agent, or set up loops and schedules for recurring work instead of relying
-  only on slash commands.
-- Existing configs from any version before `0.1.50` still update directly on first run when you install `v0.1.52`. clisbot writes a backup first under `~/.clisbot/backups/`, then rewrites the config to the current `0.1.50` schema shape.
-- Shared Slack channels, Slack groups, Telegram groups, and Telegram topics are a separate gate: normal users need an explicit route such as `group:<id>` or `topic:<chatId>:<topicId>` before the bot will talk there. Legacy Slack `channel:<id>` input still works for compatibility.
-- After a shared surface is admitted, per-surface sender control comes from the bot's default shared rule `groups["*"]` plus any route-local `allowUsers` or `blockUsers`.
-- With that permission model, a bot can be added to a team group but still be
-  allowed to answer only some people in that group.
-- If the effective shared policy is `disabled`, the bot stays silent there for everyone, including owner/admin.
-- If the effective shared policy is `allowlist` and a sender is not allowed, the bot denies before the runner:
-  - `You are not allowed to use this bot in this group. Ask a bot owner or admin to add you to \`allowUsers\` for this surface.`
-- To chat with the bot in a group:
-  - telegram: Add the bot to the group, then use `/start` there. It will guide
-    you toward the route you need to add. You can run that command directly or
-    copy it into a DM with the bot and ask it to do the setup for you if you
-    are already authorized.
-  - slack: similar flow, but Slack-native slash command handling is awkward.
-    Use a leading space such as ` /start`, or use the alias `\start`. The same
-    workaround applies to other slash commands such as ` /streaming on` or
-    `\mention`.
-  - group conversations require a mention by default to avoid abuse, but smart
-    follow-up stays open for a short window so you do not need to tag the bot
-    again on every reply. You can also ask the bot to change that mode for you.
-  - If you want stricter mention behavior, use `/mention` for this conversation only, `/mention channel` for the current channel or group default, or `/mention all` for the current bot default.
-  - For long running tasks such as coding, turn streaming on with `/streaming on`
-    and check it with `/streaming status`. In Slack, use a leading space such
-    as ` /streaming on` or the alias `\streaming on`.
-- If you want to add more owner or app admin, grant that principal explicitly with the platform prefix plus the channel-native user id, for example `clisbot auth add-user app --role owner --user telegram:1276408333` or `clisbot auth add-user app --role admin --user slack:U123ABC456`.
-- `clisbot auth --help` now covers role scopes, permission sets, and add/remove flows for users and permissions.
-- App-level auth and owner-claim semantics in [Authorization And Roles](docs/user-guide/auth-and-roles.md) describe both the current runtime reality and the remaining target-model gaps.
 
 Need the step-by-step setup docs instead of the shortest path?
 
 - Telegram: [Telegram Bot Setup](docs/user-guide/telegram-setup.md)
 - Slack: [Slack App Setup](docs/user-guide/slack-setup.md)
+- Zalo Bot: [Zalo Bot Setup](docs/user-guide/zalo-bot-setup.md)
+- Zalo Personal: [Zalo Personal](docs/user-guide/zalo-personal.md)
 - Release history: [CHANGELOG.md](CHANGELOG.md), [release notes](docs/releases/README.md), [update guide](docs/updates/update-guide.md), [release guides](docs/updates/README.md), and [migration index](docs/migrations/index.md)
 - Slack app manifest template: [app-manifest.json](templates/slack/default/app-manifest.json)
 - Slack app manifest guide: [app-manifest-guide.md](templates/slack/default/app-manifest-guide.md)
@@ -235,15 +141,529 @@ What happens next:
 - fresh bootstrap only enables the channels you name explicitly
 - after the persisted first run, later restarts can use plain `clisbot start`
 
+## Page Index
+
+- [Start By Need](#start-by-need)
+- [Supported Channels](#supported-channels)
+- [Who It Is For](#who-it-is-for)
+- [How clisbot Fits](#how-clisbot-fits)
+- [Use Case Map](#use-case-map)
+- [First Setup FAQ](#first-setup-faq)
+- [Routing And Access FAQ](#routing-and-access-faq)
+- [Chat-Native Operator Experience](#chat-native-operator-experience)
+- [Runtime And Workflow FAQ](#runtime-and-workflow-faq)
+- [Troubleshooting By Symptom](#troubleshooting-by-symptom)
+- [Troubleshooting Playbooks](#troubleshooting-playbooks)
+- [Command Cheat Sheet](#command-cheat-sheet)
+- [Related Docs](#related-docs)
+
+## Start By Need
+
+| Need | Best first path | Why it fits | Read next |
+| --- | --- | --- | --- |
+| Personal coding assistant in chat | Telegram DM + `codex` | Lowest setup friction, strong routed coding behavior, durable workspace. | [Telegram Bot Setup](docs/user-guide/telegram-setup.md), [Codex CLI Guide](docs/user-guide/codex-cli.md) |
+| Team assistant in a shared room | Slack channel or Telegram group/topic + `codex` | Explicit routes, mention defaults, and sender policy make shared use safer. | [Slack App Setup](docs/user-guide/slack-setup.md), [Routes](docs/user-guide/channels.md) |
+| Claude Code from chat | Any routed surface + `claude` | Keeps Claude-native commands and skills reachable from chat. | [Claude CLI Guide](docs/user-guide/claude-cli.md), [Native CLI Commands](docs/user-guide/native-cli-commands.md) |
+| OpenClaw-style assistant with local memory | Personal or team bot + bootstrapped workspace | `AGENTS.md`, `USER.md`, `MEMORY.md`, pairing, routes, and channel-native UX map well to OpenClaw habits. | [User Guide](docs/user-guide/README.md), [Authorization And Roles](docs/user-guide/auth-and-roles.md) |
+| Hermes-agent-style background workflow | Schedule review of repeated and struggled tasks to create and improve skills. | One chat surface can turn hard recurring work into reusable skills, review loops, and recurring briefs. | [Slash Commands](docs/user-guide/slash-commands.md), [Runtime Operations](docs/user-guide/runtime-operations.md) |
+| Operator rescue and inspection | `clisbot status`, `logs`, `watch`, `runner inspect` | Shows channel health, runtime pid, active runs, and live runner panes. | [Runtime Operations](docs/user-guide/runtime-operations.md), [CLI Commands](docs/user-guide/cli-commands.md) |
+| Zalo automation | Zalo Bot or Zalo Personal | Zalo Bot is official-DM oriented; Zalo Personal supports local personal-account DM and group workflows while staying silent until users or groups are allowlisted. | [Zalo Bot Setup](docs/user-guide/zalo-bot-setup.md), [Zalo Personal](docs/user-guide/zalo-personal.md) |
+
+## Supported Channels
+
+Current user-facing channel guides:
+
+- [Slack App Setup](docs/user-guide/slack-setup.md)
+- [Telegram Bot Setup](docs/user-guide/telegram-setup.md)
+- [Zalo Bot Setup](docs/user-guide/zalo-bot-setup.md)
+- [Zalo Personal](docs/user-guide/zalo-personal.md)
+
+| Channel | Best fit | Supported surfaces | Routing shape | Status |
+| --- | --- | --- | --- | --- |
+| Slack | Team channels, private groups, workplace assistant flows. | DM, public/private channel, thread continuity. | `dm:<userId>`, `group:<channelId>`, `group:*` | Stable primary channel |
+| Telegram | Personal bot, mobile coding, groups, topic-isolated team workflows. | DM, group, forum topic. | `dm:<userId>`, `group:<chatId>`, `topic:<chatId>:<topicId>` | Stable primary channel |
+| Zalo Bot | Official Zalo bot DM flows and Vietnam-market experiments. | DM-focused today. | `dm:<user-id>`, `dm:*` | Alpha; polling-first |
+| Zalo Personal | Local personal-account automation. | DM and group, silent by default until users or groups are allowlisted. | `dm:<user-id>`, `dm:*`, `group:<group-id>` | Supported local channel |
+
+Simple capability map:
+
+| Capability | Slack | Telegram | Zalo Bot | Zalo Personal |
+| --- | --- | --- | --- | --- |
+| Direct messages | Yes | Yes | Yes | Yes |
+| Shared rooms | Channels and groups | Groups | No current group model | Groups |
+| Child conversation isolation | Threads | Forum topics | No | No topic/thread model |
+| Pairing / first access flow | Yes | Yes | Yes | Opt-in; default silent |
+| Route allowlists | Yes | Yes | DM allowlists | DM and group allowlists |
+| Chat-native queue/loop use | Yes | Yes | Yes, DM-oriented | Yes, route-scoped |
+| Message send CLI | Yes | Yes | Yes, text and URL-backed photo path | Yes, text and file/URL media path |
+| Inbound attachments | Supported through routed attachments | Supported through routed attachments | Images/stickers to `.attachments/` | Images and grouped image handling |
+| Best default runner | `codex` | `codex` | `codex` | `codex` |
+
+Use the channel guide that matches the target surface. Slack and Telegram are
+the most stable public user experience today; Zalo Bot and Zalo Personal are
+the right fit when the target market or test surface specifically needs Zalo,
+with the safety notes in the channel guide close at hand.
+
+## Who It Is For
+
+| Audience | Common goal | Recommended shape | Main risk to manage |
+| --- | --- | --- | --- |
+| Solo builder | Code from phone or chat without losing a real repo workspace. | `--bot-type personal`, Telegram DM, `codex`. | Native CLI auth or missing host dependencies. |
+| Office worker | Use a frontier agent for business work, marketing, research, writing, planning, reporting, and follow-up without living in a terminal or separate AI app. | `--bot-type personal`, the channel you already use most, `codex` or your preferred CLI. | Giving the bot too broad a workspace before you have clear habits and permissions. |
+| Team member | Bring an assistant into the work channel where decisions, files, and follow-ups already happen. | `--bot-type team`, shared room route, mention required, queue/loop for follow-up. | Confusing a shared assistant with a private assistant; route and sender policy should be explicit. |
+| Business, marketing, or operations team | Turn recurring reports, campaign briefs, customer or market research, document updates, reviews, reminders, and cross-functional requests into chat-native workflows. | Slack, Telegram, Zalo Bot, or Zalo Personal depending on the team's real channel; queues and loops for repeated work. | Scheduling with the wrong timezone, sender identity, or target channel. |
+| Engineering lead | Put an assistant in a team channel without opening it to everyone. | `--bot-type team`, shared route allowlist, mention required. | Route admission and sender policy confusion. |
+| AI workflow operator | Run repeated reviews, status checks, and follow-up work. | Chat-native requests backed by `/queue`, `/loop`, `clisbot queues`, and `clisbot loops`. | Loops or queues created with the wrong sender, target, or timezone. |
+| Claude-heavy team | Keep existing Claude Code command and skill habits. | `claude` runner, native command pass-through, streaming on for long tasks. | Claude plan approval and auto-mode behavior may still appear. |
+| OpenClaw / Hermes Agent user | Keep channel-native assistant ergonomics, memory, background work, and skill evolution while using frontier coding CLIs. | Routed chat surfaces, memory files, workspace bootstrap, scheduled skill review loops. | Assuming every OpenClaw or Hermes behavior maps one-to-one. |
+| Platform builder | Evaluate clisbot as a local agent runtime layer. | Multiple agents, explicit routes, runtime inspection, queue/loop primitives. | Blurring channel, control, agents, and runner ownership. |
+
+## How clisbot Fits
+
+`clisbot` turns native CLI agents such as Codex, Claude Code, and Gemini CLI
+into durable Slack, Telegram, and Zalo-accessible bots. Each agent runs in a
+real workspace through a tmux-backed runner, while channels own chat-native
+presentation, routing, pairing, file handling, and follow-up behavior.
+
+The main problem it solves is not just "send terminal text to chat." It gives
+operators a safer way to expose expensive, subscription-backed coding agents to
+real communication surfaces without rebuilding every workflow around an API-only
+assistant product.
+
+Key fit:
+
+- Use Codex when you want the safest default for routed coding work.
+- Use Claude when Claude Code itself is the priority and you accept more
+  operator supervision on long tasks.
+- Use Gemini when Gemini auth is already clean and you specifically want Gemini.
+- Use clisbot as a lower-cost replacement for most OpenClaw-style assistant
+  workflows when the goal is memory, workspace continuity, pairing,
+  channel-native UX, and routed chat access to powerful agents.
+- Use clisbot for Hermes-agent-style background workflow when you want durable
+  queue and loop primitives plus skill creation and skill improvement inside a
+  real coding-agent workspace.
+- Use chat-native operation first: ask the bot to create loops, add routes,
+  update clisbot, summarize release changes, or inspect its own runtime. Slash
+  commands and CLI commands are still available as explicit control surfaces and
+  reliable fallbacks.
+
+## Use Case Map
+
+| Use case | Typical prompt | Useful controls | Notes |
+| --- | --- | --- | --- |
+| Quick coding task | "Fix the failing test and send me the diff." | `/streaming on`, `/watch every 30s`, `/stop` | Start with Codex unless another CLI is required. |
+| Code review loop | "After this implementation, queue a code review against architecture and fix the issues." | Bot-created queue, `/queue`, `clisbot queues list` | Queue keeps steps sequential instead of steering the current run. |
+| Team group assistant | "@bot summarize this incident thread" | `routes add`, `routes add-allow-user`, `/mention` | Keep mention required in shared groups by default. |
+| Recurring operations brief | "Create a weekday 09:00 loop that checks CI and summarizes risk." | Bot-created loop, `/loop status`, `/loop cancel <id>` | Verify timezone in the creation response. |
+| Native Claude skill | "`/code-review`" | Native command pass-through | In Slack, send a leading space if Slack intercepts `/...`. |
+| Personal memory assistant | "Remember this project rule and update the workspace docs." | Bootstrapped `AGENTS.md`, `USER.md`, `MEMORY.md` | Keep private memory out of shared contexts. |
+| Mobile coding companion | "Continue the repo task from my phone." | `/attach`, `/detach`, `/watch`, `/new` | The workspace stays on the machine; chat is the control surface. |
+| Bot self-update | "Update clisbot, follow the update guide, then summarize what changed." | Bot checks `clisbot update --help`, operator auth, `clisbot status` | The bot can perform the routine update path when it has permission. |
+| Zalo local automation | "Allow this Zalo user or group to use the work bot." | `dm:*` allowUsers or exact `group:<id>` routes | Keep Zalo Personal silent except for intentionally allowlisted users or groups. |
+
+## First Setup FAQ
+
+### Which CLI should I choose first?
+
+Choose `codex` for the safest general routed coding experience. It currently
+has the strongest default operator stability in clisbot.
+
+Choose `claude` when your team already depends on Claude Code, Claude-native
+commands, or Claude-specific skills. Turn streaming on for longer tasks so you
+can see if Claude is waiting at a plan approval step.
+
+Choose `gemini` when Gemini is already authenticated in the runtime environment
+and you specifically want Gemini. If Gemini opens OAuth or setup screens, fix
+Gemini auth directly first.
+
+Related pages: [Codex CLI Guide](docs/user-guide/codex-cli.md), [Claude CLI Guide](docs/user-guide/claude-cli.md),
+[Gemini CLI Guide](docs/user-guide/gemini-cli.md).
+
+### Should I start with Telegram or Slack?
+
+Use Telegram when you want the simplest personal bot path. Use Slack when the
+workflow is team-channel first. Telegram topics and Slack threads both work well
+as isolated conversation surfaces once routes are explicit.
+
+Related pages: [Telegram Bot Setup](docs/user-guide/telegram-setup.md), [Slack App Setup](docs/user-guide/slack-setup.md).
+
+### What is the difference between personal and team bot type?
+
+`--bot-type personal` creates a default assistant shaped for one human. It is a
+good default for Telegram DM or a private assistant.
+
+`--bot-type team` creates a shared assistant shape for a team, group, channel, or
+topic workflow. It is a good default for Slack channel use.
+
+### Why does the first run require both `--cli` and `--bot-type`?
+
+A fresh config starts with no agents. `--cli` chooses the runner family, and
+`--bot-type` chooses the workspace/bootstrap shape for the first `default`
+agent.
+
+Example:
+
+```bash
+clisbot start --cli codex --bot-type personal --telegram-bot-token <token> --persist
+```
+
+### Is clisbot an OpenClaw replacement?
+
+For most OpenClaw-style workflows, yes. clisbot is intended to be a better
+replacement when you want the same assistant shape: memory, workspace
+continuity, pairing, channel-native routing, and chat access from Slack,
+Telegram, or Zalo.
+
+The main difference is the execution model. OpenClaw-style systems usually point
+you toward API-backed agents. clisbot runs frontier coding CLIs such as Codex,
+Claude Code, and Gemini CLI as durable agents behind chat surfaces. That can be
+much cheaper for many users because it reuses the CLI subscriptions they already
+pay for instead of forcing every useful workflow through API-metered usage.
+
+It is also stronger for coding-native work. The same bot can act as a daily
+assistant, workplace assistant, and team assistant, but when the task becomes
+"edit the repo, run tests, improve docs, create a skill, or fix the workflow,"
+it is already sitting inside the native coding-agent environment where those
+tasks are strongest.
+
+### Is clisbot a Hermes agent?
+
+It can cover most Hermes-agent-style use cases, but it reaches them through
+durable coding agents instead of a separate agent product boundary.
+
+Hermes-style self-evolution maps naturally to clisbot because an agent can keep
+working in a real workspace, use `/queue` for sequential follow-up, use `/loop`
+for daily or weekly review, and update its own operating files, docs, tools, or
+skills after hard tasks. If a task exposes a repeated weakness, you can ask the
+agent to create a new skill or improve an existing one, then reuse that skill in
+future work. Daily and weekly loops can do the same thing as a deliberate
+maintenance rhythm.
+
+The practical positioning is: clisbot is both an assistant and a native coding
+agent surface. It can handle general office-worker workflows through chat,
+files, memory, and tools, while still being unusually strong when the work
+requires code, repo edits, tests, automation scripts, or skill evolution.
+
+## Routing And Access FAQ
+
+### Why does the bot answer in DM but not in a group?
+
+DMs and shared surfaces are gated separately. Fresh configs do not automatically
+admit Slack channels, Telegram groups, Telegram topics, or Zalo Personal groups.
+Add an explicit route:
+
+```bash
+clisbot routes add --channel telegram group:<chatId> --bot default
+clisbot routes add --channel telegram topic:<chatId>:<topicId> --bot default
+clisbot routes add --channel slack group:<channelId> --bot default
+```
+
+Use `/whoami` in the target surface to discover ids where supported.
+
+### What does `group:*` mean?
+
+`group:*` is the default multi-user sender policy node under one bot. It is not
+the same thing as admitting every group. Exact shared routes still decide which
+groups, topics, or channels are admitted when the bot's shared admission policy
+is `allowlist`.
+
+### Why does the deny message say "group" in Slack channels or Telegram topics?
+
+The deny text intentionally uses one common human-facing word for multi-user
+surfaces. Internally, provider-specific surfaces still map to canonical route
+concepts such as `group` and `topic`.
+
+### Why does the bot require a mention in groups?
+
+Shared surfaces default toward safer behavior. Mention-required routes reduce
+accidental bot activation in busy rooms. Use `/mention`, `/mention channel`, or
+`/mention all` to tighten mention behavior, or `routes set-require-mention` when
+you intentionally want a route to listen without mention.
+
+### How do I let only selected people use the bot in a shared surface?
+
+Add the route, keep or set its policy to `allowlist`, then add allowed users:
+
+```bash
+clisbot routes add --channel telegram group:<chatId> --bot default --policy allowlist
+clisbot routes add-allow-user --channel telegram group:<chatId> --bot default --user <userId>
+```
+
+Surface policy decides who may reach the bot. Auth roles decide what they may do
+after they get in.
+
+Related page: [Authorization And Roles](docs/user-guide/auth-and-roles.md).
+
+## Chat-Native Operator Experience
+
+### Do I need to memorize slash commands and CLI commands?
+
+No. The preferred product experience is chat-native: ask the bot what you want,
+and let it inspect the relevant help, run the right `clisbot` command, and
+report the result.
+
+Good prompts:
+
+```text
+Create a loop every weekday at 09:00 that checks CI and summarizes risk here.
+Queue a code review after the current implementation finishes, then run tests.
+Add this Telegram topic to the default bot if I am allowed to manage routes.
+Update clisbot, follow the update guide, restart safely, and summarize what changed.
+```
+
+Slash commands such as `/loop`, `/queue`, `/watch`, and `/status` still matter.
+They are the precise chat control surface for users who already know the command
+they want. The CLI remains the explicit operator surface and fallback when you
+need exact, scriptable control.
+
+### How does bot-native configuration stay safe?
+
+clisbot is designed so the bot can help configure itself without treating every
+chat message as permission to mutate protected state.
+
+The important guardrails are:
+
+- surface routes decide where the bot may answer at all
+- auth roles and permissions decide whether a sender may manage routes, queues,
+  loops, runtime operations, or protected resources
+- the agent prompt tells the bot to use `clisbot` CLI help for configuration,
+  update, loop, queue, and route requests instead of inventing commands
+- sensitive actions should be preceded by a read-only permission check such as
+  `clisbot auth get-permissions --sender <principal> --agent <agentId> --json`
+- runtime monitoring, `status`, `logs`, `watch`, `/attach`, `/stop`, and
+  `stop --hard` give operators recovery paths if a native CLI or runner gets
+  stuck
+
+That is the intended balance: you can operate clisbot by chatting with it, while
+configuration changes still pass through explicit command surfaces, auth checks,
+durable state, and observable recovery mechanisms.
+
+## Runtime And Workflow FAQ
+
+### What should I use when a run is taking a long time?
+
+Use `/attach` to resume live updates in the current thread. Use
+`/watch every 30s` for periodic updates. Use `/detach` when you want the run to
+continue quietly and still post the final result.
+
+Use `/stop` only when you want to interrupt the current run.
+
+### What is the difference between queue and steer?
+
+`/queue <message>` stores a prompt behind the current run and executes it later
+in order. Use it for review-after-code, test-after-fix, or deliberate
+multi-step work.
+
+`/steer <message>` injects a prompt into the active run now. Use it when the
+current run is going in the wrong direction and must be corrected immediately.
+
+### When should I create a loop?
+
+Use loops for repeated or scheduled work. The easiest path is to ask the bot to
+create the loop in plain language:
+
+```text
+Create a loop every weekday at 09:00 that summarizes open operational risks here.
+Run this review prompt 3 times, one after another, until the issues are fixed.
+Check CI every 2 hours and summarize only actionable failures.
+```
+
+The bot should inspect the live loop help when needed, create the loop through
+the clisbot control surface, and report the resolved timezone and cancel
+command. Direct `/loop ...` commands still work when you want exact syntax.
+
+Loops are durable and session-scoped. Check loop state by asking the bot, with
+`/loop status`, or with `clisbot loops status`. Cancel stale loops before
+creating replacements.
+
+### Why did a queued or looped prompt not run immediately?
+
+Managed loops are skip-if-busy, and queues wait for the current logical run to
+settle. This avoids corrupting the active conversation or piling unrelated
+prompts into one run.
+
+### How do native CLI commands work?
+
+clisbot reserves a small set of control commands such as `/status`, `/stop`,
+`/queue`, and `/loop`. Other slash commands are forwarded unchanged to the
+underlying CLI. That is why Claude-native commands like `/code-review` and
+Codex-native habits such as `/review` or `$code-review` can still work.
+
+Related page: [Native CLI Commands](docs/user-guide/native-cli-commands.md).
+
+## Troubleshooting By Symptom
+
+| Symptom | First check | Likely cause | Fix |
+| --- | --- | --- | --- |
+| `clisbot start` says no agents are configured | `clisbot start --help` | Fresh config has no agent yet. | Start with both `--cli` and `--bot-type`. |
+| Token refs show `missing` | `clisbot status` | Env var is not visible to the runtime. | Pass token again, persist it, or restart from a shell with the env exported. |
+| Channel stays `starting` | `clisbot logs` | Credential, network, auth, or provider startup failure. | Fix the provider error shown in logs, then restart. |
+| Bot answers in DM but not group | `/whoami` in group/topic | Missing shared route or mention requirement. | Add `group:<id>` or `topic:<chatId>:<topicId>` route. |
+| Message accepted but no answer arrives | `clisbot watch --latest --lines 100` | Runner is blocked, unauthenticated, or waiting at a prompt. | Fix the native CLI state in the workspace, then restart or `/new`. |
+| Native CLI runner does not answer | `codex`, `claude`, or `gemini` directly in terminal | The underlying coding CLI is not installed, authenticated, trusted, or able to run on this machine. | Fix the native CLI first; clisbot only works after the CLI can answer normally. |
+| Channel or runtime feels stuck | `clisbot status` and `clisbot logs` | Channel worker, detached runtime, or tmux runner state is stale. | Try `clisbot restart`; if that is not enough, run `clisbot stop --hard` then `clisbot start`. |
+| Claude appears stuck | `/streaming on` and `/watch every 30s` | Claude plan approval or auto-mode behavior. | Send `/nudge` if it is waiting for default confirmation. |
+| Gemini startup blocks | `clisbot logs` | Gemini OAuth or setup screen. | Authenticate Gemini directly or provide a headless auth path. |
+| Codex reports missing env var | `clisbot watch --latest` | Detached runtime did not inherit your shell env. | Restart clisbot from a shell with the env, or configure the service env. |
+| Slack slash command does not reach clisbot | Slack client behavior | Slack intercepts leading `/...`. | Send a leading space, for example ` /status`, or use `\status`. |
+| Old behavior survives restart | `clisbot runner list` | Stale tmux runner or old environment. | Use `clisbot stop --hard`, then start again. |
+| Update or restart seems stuck | `clisbot status` | Worker already exited or monitor is in transition. | Check status first; then run `clisbot start` if runtime is down. |
+
+## Troubleshooting Playbooks
+
+### Check The Native CLI First
+
+When clisbot accepts a message but the agent does not answer, first separate
+clisbot from the underlying coding CLI.
+
+1. Open a terminal on the same machine.
+2. Go to the workspace you expect clisbot to use, usually
+   `~/.clisbot/workspaces/default`.
+3. Start the configured CLI directly:
+
+```bash
+codex
+claude
+gemini
+```
+
+4. Say `hi` and confirm the CLI can answer.
+5. If the CLI cannot start or reply, fix its install, login, trust prompt,
+   model access, or local dependency issue first. clisbot cannot make a broken
+   native CLI work; it can only run and route a CLI that already works on the
+   machine.
+
+### Reset A Stuck Channel Or Runtime
+
+If the native CLI works in terminal but the chat channel is still stuck, reset
+the clisbot runtime boundary.
+
+1. Try the normal restart first:
+
+```bash
+clisbot restart
+```
+
+2. If stale tmux sessions or old channel state still survive, hard-stop all
+   clisbot tmux sessions and start fresh:
+
+```bash
+clisbot stop --hard
+clisbot start
+```
+
+3. After the restart, run `clisbot status` and send one small test message from
+   the target channel.
+
+### Bot Does Not Start
+
+1. Run `clisbot status`.
+2. Run `clisbot logs`.
+3. Confirm token refs are present and the channel is enabled.
+4. If this is the first run, include both `--cli` and `--bot-type`.
+5. If a normal restart is not enough, run `clisbot stop --hard`, then start
+   again from a shell with the correct environment.
+
+### Bot Does Not Reply In A Routed Surface
+
+1. Send `/whoami` in the surface.
+2. Confirm the exact route exists with `clisbot routes list --channel <channel>`.
+3. Confirm sender policy does not block the user.
+4. Confirm the message mentions the bot when `requireMention` is true.
+5. Run `clisbot watch --latest --lines 100` after one test message to inspect
+   the runner pane.
+
+### Runner Looks Stuck
+
+1. Run `clisbot runner list`.
+2. Run `clisbot runner inspect --latest`.
+3. Use `clisbot watch --latest --lines 100` to see the live pane.
+4. Open the workspace directly, usually `~/.clisbot/workspaces/default`.
+5. Start the native CLI there and clear auth, trust, or dependency prompts.
+6. Use `/nudge`, `/stop`, or `/new` depending on whether the run is waiting,
+   wrong, or needs a fresh conversation.
+
+### Access Control Is Confusing
+
+1. Separate the two questions:
+   - route policy: may this sender reach this surface?
+   - auth role: what may this sender do after admission?
+2. Use `clisbot routes get --channel <channel> <route-id> --bot <bot>`.
+3. Use:
+
+```bash
+clisbot auth get-permissions --sender <principal> --agent <agentId> --json
+```
+
+4. Remember that `disabled` wins over owner/admin, and `blockUsers` still wins.
+
+### Queue Or Loop Behavior Is Surprising
+
+1. Check the current session with `/status`.
+2. List pending queue items with `/queue list` or `clisbot queues list`.
+3. Check loops with `/loop status` or `clisbot loops status`.
+4. Confirm the loop timezone in the creation response.
+5. Cancel stale loops before creating replacement schedules.
+
+## Command Cheat Sheet
+
+| Job | Command |
+| --- | --- |
+| Start first Telegram personal bot | `clisbot start --cli codex --bot-type personal --telegram-bot-token <token> --persist` |
+| Start first Slack team bot | `clisbot start --cli codex --bot-type team --slack-app-token <xapp> --slack-bot-token <xoxb> --persist` |
+| Check runtime health | `clisbot status` |
+| Read recent logs | `clisbot logs` |
+| Inspect live runner output | `clisbot watch --latest --lines 100` |
+| Add Telegram group route | `clisbot routes add --channel telegram group:<chatId> --bot default` |
+| Add Telegram topic route | `clisbot routes add --channel telegram topic:<chatId>:<topicId> --bot default` |
+| Add Slack channel route | `clisbot routes add --channel slack group:<channelId> --bot default` |
+| Approve DM pairing | `clisbot pairing approve <channel> <code>` |
+| Hard reset runtime sessions | `clisbot stop --hard` |
+| Show update instructions | `clisbot update --help` |
+
+## Related Docs
+
+- [User Guide](docs/user-guide/README.md)
+- [CLI Commands](docs/user-guide/cli-commands.md)
+- [Runtime Operations](docs/user-guide/runtime-operations.md)
+- [Routes](docs/user-guide/channels.md)
+- [Surface Access Model](docs/user-guide/surface-access-model.md)
+- [Bots And Credentials](docs/user-guide/bots-and-credentials.md)
+- [Authorization And Roles](docs/user-guide/auth-and-roles.md)
+- [Slash Commands](docs/user-guide/slash-commands.md)
+- [Agent Progress Replies](docs/user-guide/agent-progress-replies.md)
+- [Telegram Bot Setup](docs/user-guide/telegram-setup.md)
+- [Slack App Setup](docs/user-guide/slack-setup.md)
+- [Zalo Bot Setup](docs/user-guide/zalo-bot-setup.md)
+- [Zalo Personal](docs/user-guide/zalo-personal.md)
+
+
+## CLI Compatibility Snapshot
+
+`clisbot` currently works well with Codex, Claude, and Gemini.
+
+| CLI      | Current Stability   | Short Take                                                                                                  |
+| ----------| ---------------------| -------------------------------------------------------------------------------------------------------------|
+| `codex`  | Best today          | Strongest default for routed coding work.                                                                   |
+| `claude` | Usable with caveats | Claude can surface its own plan-approval and auto-mode behavior even when launched with bypass-permissions. |
+| `gemini` | Fully compatible   | Gemini is supported as a first-class runner for routed chat-native workflows.                               |
+
+CLI-specific operator notes:
+
+- [Codex CLI Guide](docs/user-guide/codex-cli.md)
+- [Claude CLI Guide](docs/user-guide/claude-cli.md)
+- [Gemini CLI Guide](docs/user-guide/gemini-cli.md)
+
 ## Recent Release Highlights
 
+- `v0.1.53`: refreshes the main README and localized user guides, adds Zalo Bot QR onboarding and Zalo Personal media guidance, fixes queue/loop/message-tool edge cases, tightens Slack/Telegram/Zalo channel behavior, and adds admin-only sensitive channel permissions for contact, group, and channel-native actions.
 - `v0.1.52`: clarifies shared-route setup so `routes add ...` clearly means “use the agent currently assigned to that bot by default,” and prunes stale short `startupDelayMs` overrides so upgraded installs can actually inherit the newer 60-second startup default.
 - `v0.1.51`: raises the default runner startup window to 60 seconds across the
   standard CLI families and the shared runner fallback, so slower fresh launches
   are less likely to fail before the first prompt can be submitted.
 - `v0.1.50`: a much more AI-native operator experience, where you can
   increasingly talk to the bot to manage itself; plus safer personal and team
-  bots in real Slack and Telegram groups, automatic direct updates from older
+  bots in real shared chat surfaces, automatic direct updates from older
   installs, durable queue control, clearer session continuity truth, more
   reliable scheduled loops, stronger trust/restart behavior, and stricter
   streaming/session isolation.
@@ -272,80 +692,17 @@ Read the full notes here:
 
 - [CHANGELOG.md](CHANGELOG.md)
 - [Release Notes Index](docs/releases/README.md)
+- [v0.1.53 Release Notes](docs/releases/v0.1.53.md)
 - [v0.1.52 Release Notes](docs/releases/v0.1.52.md)
 - [v0.1.51 Release Notes](docs/releases/v0.1.51.md)
 - [v0.1.50 Release Notes](docs/releases/v0.1.50.md)
 - [v0.1.43 Release Notes](docs/releases/v0.1.43.md)
 - [v0.1.39 Release Notes](docs/releases/v0.1.39.md)
 
-If you prefer Slack first:
-
-```bash
-clisbot start \
-  --cli codex \
-  --bot-type team \
-  --slack-app-token SLACK_APP_TOKEN \
-  --slack-bot-token SLACK_BOT_TOKEN
-```
-
-Short alias:
-
-```bash
-clis start --cli codex --bot-type personal --telegram-bot-token <your-telegram-bot-token>
-```
-
-Local repo path:
-
-```bash
-bun install
-bun run start --cli codex --bot-type personal --telegram-bot-token <your-telegram-bot-token> --persist
-```
-
-Repo-local `bun run start|stop|restart|status|logs|init|pairing` is pinned by `.env` to `CLISBOT_HOME=~/.clisbot-dev`, so local testing does not accidentally reuse your main `~/.clisbot` runtime.
-
-Update note for existing installs:
-
-- Older installs before `v0.1.50` now update directly on first run with a
-  backup written first, so most people can update and restart without a manual
-  migration pass.
-- `v0.1.52` keeps that direct-upgrade path and does not introduce a new config
-  schema bump; it also cleans up stale short startup-delay overrides that would
-  otherwise keep some upgraded installs on older timeout behavior.
-- After you are on the `v0.1.50` schema line, future upgrades should feel much
-  more AI-native:
-  in many cases you can simply ask the bot to update `clisbot` to the latest
-  version, and it can follow the update guide, perform the upgrade flow, then
-  brief you on what changed.
-- If you still want an agent to inspect your current config before updating,
-  ask Codex or Claude in this repo to review it first.
-- The manual package upgrade path is now simpler:
-
-```bash
-npm install -g clisbot && clisbot restart
-clisbot --version
-```
-
-First conversation path:
-
-- send a DM to the bot in Slack or Telegram
-- if that principal is already app `owner` or app `admin`, pairing is bypassed and the bot should answer normally
-- otherwise, `clisbot` defaults DMs to pairing mode and replies with a pairing code plus approval command
-
-Approve it with:
-
-```bash
-clisbot pairing approve slack <CODE>
-clisbot pairing approve telegram <CODE>
-```
-
-Fresh config starts with no configured agents, so first-run `clisbot start` requires both `--cli` and `--bot-type` before it creates the first `default` agent.
-Fresh config also starts with no preconfigured Slack channels or Telegram groups or topics. Add those routes manually in `~/.clisbot/clisbot.json`.
-`clisbot start` requires explicit channel token input before it bootstraps anything. You can pass raw values, env names such as `MY_TELEGRAM_BOT_TOKEN`, or placeholders such as `'${MY_TELEGRAM_BOT_TOKEN}'`.
-If you want a separate dev instance beside your main bot, see the [Development Guide](docs/development/README.md).
 
 ## Showcase
 
-The goal is a real chat-native agent surface, not a terminal transcript mirror: threads, topics, follow-up behavior, and file-aware workflows should feel native to Slack and Telegram.
+The goal is a real chat-native agent surface, not a terminal transcript mirror: threads, topics, follow-up behavior, and file-aware workflows should feel native to each supported channel surface.
 
 Slack
 
@@ -367,173 +724,6 @@ Strong vendor investment in security and safety does not make frontier agentic C
 
 `clisbot` would not exist without the ideas, momentum, and practical inspiration created by OpenClaw. Many configuration, routing, and workspace concepts here were learned from studying OpenClaw, then adapted to `clisbot`'s own direction. Respect and thanks to the OpenClaw project and community.
 
-## Setup Guide
-
-The easiest setup flow is still:
-
-1. Install `clisbot`.
-2. Run the quick start command above.
-3. DM the bot; approve pairing unless that principal is already app `owner` or app `admin`.
-4. Only move into advanced config after the first successful run.
-
-If you want the repo-guided setup path:
-
-1. Clone this repo.
-2. Open Claude Code, Codex, or Gemini CLI in this repo.
-3. Ask it to help you set up `clisbot`.
-
-The docs in this repo are kept current, including the [User Guide](docs/user-guide/README.md), so the agent should have enough context to walk you through setup, configuration, and troubleshooting directly inside the repo.
-If anything goes wrong, the fastest rescue loop is usually `clisbot logs`,
-`clisbot status`, `clisbot restart`, or if needed `clisbot stop --hard`
-followed by `clisbot start`.
-Also open the coding CLI directly inside the bot workspace, usually
-`~/.clisbot/workspaces/default`, and make sure that CLI already works there.
-That is one of the strongest end-to-end checks for bot health.
-
-If you prefer to configure everything yourself:
-
-1. Read the official config template in [config/clisbot.json.template](config/clisbot.json.template).
-2. If you need the archived released snapshot for migration review, compare it with [config/clisbot.v0.1.43.json.template](config/clisbot.v0.1.43.json.template).
-3. Copy the official template to `~/.clisbot/clisbot.json` and adjust bots, routes, agents, workspaces, and policies for your environment.
-4. Add agents through the CLI so tool defaults, startup options, and bootstrap templates stay consistent.
-5. Optionally move stable channel secrets into env vars or canonical credential files after your first successful run.
-
-Channel route setup is manual by design:
-
-- fresh config does not auto-add Slack channels
-- fresh config does not auto-add Telegram groups or topics
-- add only the exact channel, group, topic, or DM routing you want to expose
-- default bot credential setup lives in [docs/user-guide/bots-and-credentials.md](docs/user-guide/bots-and-credentials.md)
-
-Advanced agent management:
-
-- most users should stay on `clisbot start --cli ... --bot-type ...` and let first-run create the default agent
-- if you need more than one agent, custom bot defaults, or manual route setup flows, use the `clisbot agents ...`, `clisbot bots ...`, and `clisbot routes ...` commands described in [docs/user-guide/README.md](docs/user-guide/README.md)
-- README intentionally keeps that low-level surface out of the main onboarding path because the public first-run model is `--bot-type personal|team`, not internal template-mode naming
-- fresh bot config still points at the `default` agent; if your first useful agent uses another id, update the fallback with `clisbot bots set-agent ...` or override it on a route with `clisbot routes set-agent ...`
-
-Env-backed setup is still supported when you want config to reference an env name instead of persisting a credential file:
-
-```bash
-clisbot start \
-  --cli codex \
-  --bot-type personal \
-  --slack-app-token CUSTOM_SLACK_APP_TOKEN \
-  --slack-bot-token CUSTOM_SLACK_BOT_TOKEN
-```
-
-- these flags are written into `~/.clisbot/clisbot.json` as `${ENV_NAME}` placeholders
-- you can pass either `CUSTOM_SLACK_APP_TOKEN` or `'${CUSTOM_SLACK_APP_TOKEN}'`
-- use this path when you want config to point at env variable names you chose yourself
-- keep env export details in [docs/user-guide/bots-and-credentials.md](docs/user-guide/bots-and-credentials.md) instead of front-loading them into quick start
-
-## Troubleshooting
-
-If the quick start does not work, check these in order:
-
-- If setup feels unclear, open Claude Code, Codex, or Gemini CLI in this repo and ask it to help using the local docs.
-- If anything looks wrong, start with `clisbot logs`, `clisbot status`,
-  `clisbot restart`, or if needed `clisbot stop --hard` followed by
-  `clisbot start`.
-- If config behavior is confusing, inspect [config/clisbot.json.template](config/clisbot.json.template) first, then compare it with [docs/user-guide/README.md](docs/user-guide/README.md).
-- If `clisbot start` says no agents are configured, prefer `clisbot start --cli codex --bot-type personal --telegram-bot-token <your-telegram-bot-token>`.
-- If `clisbot start` prints token refs as `missing`, either pass the token explicitly on the command line or switch to env-backed setup described in [docs/user-guide/bots-and-credentials.md](docs/user-guide/bots-and-credentials.md).
-- If `clisbot status` shows `bootstrap=...:missing` or `bootstrap=...:not-bootstrapped`, follow the advanced agent bootstrap steps in [docs/user-guide/README.md](docs/user-guide/README.md).
-- Trust is usually handled automatically by the bot, but if trust or startup
-  behavior still looks wrong, go to the workspace and launch the underlying CLI
-  there directly, for example `cd ~/.clisbot/workspaces/default` and start
-  `codex`, `claude`, or `gemini` yourself. If the CLI cannot start cleanly in
-  that workspace, the bot will not be healthy either.
-- If Gemini startup says it is waiting for manual authorization, authenticate Gemini directly first or provide a headless auth path such as `GEMINI_API_KEY` or Vertex AI credentials; `clisbot` now treats that screen as a startup blocker instead of a healthy ready session.
-- If Codex warns that `bubblewrap` is missing on Linux, install `bubblewrap` in the runtime environment.
-- If the bot does not answer, check `clisbot status` first. Healthy channels should show `connection=active`; if a channel stays `starting`, inspect `clisbot logs`.
-- If a routed message was accepted but no reply arrives, send one test message
-  and immediately run `clisbot watch --latest --lines 100` in a terminal. This
-  shows the live tmux runner pane and usually reveals missing CLI auth, trust
-  prompts, stuck startup, or model/provider errors.
-- If Codex works in your normal terminal but the routed runner shows `Missing environment variable: CODEX_CLIPROXYAPI_KEY`, remember that `clisbot` runs Codex from a detached background process and tmux session. Start or restart `clisbot` from a shell where `echo $CODEX_CLIPROXYAPI_KEY` prints a value, or export the key in the environment used by your service manager. Existing tmux runner sessions keep their old environment, so recycle them after fixing env.
-- If runtime startup still fails, run `clisbot logs` and inspect the recent log tail that `clisbot` now prints automatically on startup failure.
-- If `clisbot restart` warns that stop timed out during an update, run `clisbot status` once. Current releases should continue cleanly when status already shows the worker exited; only treat it as a real bug if restart leaves the runtime down.
-- If a normal restart is not enough, use `clisbot stop --hard` to stop the runtime and kill all tmux runner sessions on the configured clisbot socket, then start again from a shell with the correct environment.
-- If you need the full command list, run `clisbot --help`.
-- If you need step-by-step operator docs, start with [docs/user-guide/README.md](docs/user-guide/README.md).
-- If Slack thread behavior feels too eager, use `/followup pause` or `/followup mention-only`.
-- If Slack slash commands conflict with Slack-native command handling, add a leading space, for example ` /bash ls -la`.
-
-## Common CLI commands
-
-Most users only need a small set of commands at first:
-
-- `clisbot start`: start the bot runtime and create the default first-run setup when needed.
-- `clisbot restart`: restart the runtime cleanly; use this first when the bot stops responding.
-- `clisbot stop`: stop the runtime cleanly before updates, config changes, or maintenance.
-- `clisbot stop --hard`: stop the runtime and kill all tmux runner sessions on the configured clisbot socket; use this when stale runner panes, old environment variables, or stuck sessions survive a normal restart.
-- `clisbot status`: check whether the runtime, channels, and active sessions look healthy.
-- `clisbot logs`: inspect recent runtime logs when startup, routing, or replies look wrong.
-- `clisbot runner list`: list the live tmux-backed runner sessions and see what is active.
-- `clisbot inspect --latest`: capture the current pane state of the newest
-  admitted session once.
-- `clisbot watch --latest --lines 100`: jump straight into the newest admitted
-  live session with enough context to debug a just-submitted message.
-- `clisbot watch --index 2`: follow the second most recent admitted session
-  without needing to copy a tmux session name first.
-- `clisbot queues list`: inspect pending durable queued prompts across the app.
-- `clisbot queues create --channel telegram --target group:-1001234567890 --topic-id 4335 --sender telegram:1276408333 <prompt>`: create one durable same-session queued prompt, capped by `control.queue.maxPendingItemsPerSession` (default `20`).
-
-Full operator command reference:
-
-- [CLI Commands Guide](docs/user-guide/cli-commands.md)
-
-If you are running from the repo instead of the global package:
-
-- `bun run dev`
-- `bun run start`
-- `bun run restart`
-- `bun run stop`
-- `bun run typecheck`
-- `bun run test`
-- `bun run check`
-
-## In Chat
-
-`clisbot` supports a small set of chat-native commands for thread control and workflow acceleration inside Slack and Telegram.
-
-Native coding-CLI command compatibility:
-
-- `clisbot` only intercepts its own reserved chat commands
-- any other native Claude, Codex, or Gemini command text is forwarded to the underlying CLI unchanged
-- operator guide: [Native CLI Commands](docs/user-guide/native-cli-commands.md)
-
-Slack note:
-
-- To stop Slack from interpreting a slash command as a native Slack slash command, prefix it with a space.
-- Example: ` /bash ls -la`
-- Bash shorthand also works: `!ls -la`
-
-Common commands:
-
-- `/start`: show onboarding or route-status help for the current conversation.
-- `/help`: show the available clisbot conversation commands.
-- `/stop`: interrupt the current running turn.
-- `/streaming on`, `/streaming off`, `/streaming status`: turn live progress on when you want to follow long coding work, then turn it back off when you only want final answers; in Slack, use ` /streaming on` or `\streaming on` when Slack grabs the raw slash command.
-- `/followup status`, `/followup auto`, `/followup mention-only`, `/followup pause`, `/followup resume`: control whether the bot keeps naturally following the thread, stays quiet, or requires an explicit mention again; fast shorthands include `/mention`, `/pause`, and `/resume`.
-- `/queue <message>`: queue the next prompt behind the current run so the bot can finish one thing, then keep going automatically without you babysitting every step.
-- `/loop <schedule or count> <message>`: turn one instruction into repeated work, from recurring automation to brute-force progress like `/loop 3 tiếp đi em` when you want the AI to keep pushing instead of stopping early.
-
-Why `/queue` and `/loop` matter:
-
-- `/queue` is a very simple workflow primitive: stack the next prompts now, let the bot run them one by one later.
-- `/loop` is the force multiplier: use it for recurring review/reporting, or just to keep the AI moving through multi-step coding work with less laziness and fewer early stops.
-
-Examples:
-
-- `/queue tiếp đi em`
-- `/queue code review theo architecture, guideline và fix, test`
-- `/loop 3 tiếp đi em`
-
-Detailed slash-command guide:
-
-- [Slash Commands](docs/user-guide/slash-commands.md)
 
 ## Docs
 
@@ -550,32 +740,17 @@ Detailed slash-command guide:
 
 ## Roadmap
 
-- Add more native CLIs, starting with a stronger Claude, Codex, and Gemini launch trio.
-- Add more channels, starting from Slack and Telegram, then moving toward Zalo and other expansion surfaces.
-- Add better workflow building blocks such as heartbeat, cron-style jobs, and stronger loop automation.
-- Explore structured output, ACP, and native SDK integrations where they improve truthfulness or operator control.
-- Explore more stable native messaging paths beyond tmux-pane capture over time.
+Current shipped foundation:
 
-## Current Focus
+- Native CLI runners: Codex, Claude Code, and Gemini CLI.
+- Channels: Telegram, Slack, Zalo Bot, and Zalo Personal.
+- Workflow primitives: durable queues and loops are stable enough for real chat-native operations work.
 
-`clisbot` is growing toward a broader agent runtime layer:
+Next focus:
 
-- more CLI tool support beyond Claude Code, Codex, and Gemini CLI
-- more communication channels beyond Slack and Telegram
-- simple workflow building blocks such as cron jobs, heartbeat jobs, and loops
-- durable agent sessions, workspaces, follow-up policy, commands, attachments, and operator controls that stay reusable across all those surfaces
-- stability and security stay at the top of the project focus; if you find an
-  issue in either area, please report it
-
-tmux is still the current stability boundary. One agent maps to one durable runner session in one workspace, and every CLI, channel, or workflow layer should route onto that durable runtime instead of recreating the agent from scratch.
-
-## Completed
-
-- [x] Multiple Codex, Claude, and Gemini sessions with streaming on/off support.
-- [x] Stale tmux session cleanup and session resume.
-- [x] OpenClaw-compatible configuration system.
-- [x] Slack channel support with streaming and attachments, smart follow mode
-- [x] Telegram channel support with streaming and attachments
+- Standardize auto-skill creation and improvement, similar to the Hermes agent pattern: repeated or struggled tasks should become reusable skills over daily and weekly review loops.
+- Add the next channel wave: Discord and WhatsApp Personal unofficial.
+- Keep improving runtime safety, recovery, and channel-native operator experience around the durable tmux runner boundary.
 
 ## AI-Native Workflow
 
@@ -587,6 +762,19 @@ This repo also serves as a small example of an AI-native engineering workflow:
 - end-to-end validation expectations to close the feedback loop for AI agents
 - workflow docs for shortest-review-first artifacts, repeated review loops, and task-readiness shaping in [docs/workflow/README.md](docs/workflow/README.md)
 
+## Bug Report
+
+The preferred way to report bugs is to create an issue in this GitHub repo.
+You can also report through this
+[Google Form](https://docs.google.com/forms/d/e/1FAIpQLSd7L7mHOo0ea8YXFI4tGnyDIj94ESn4hbbDa5YTbcEKTVOKTA/viewform).
+Please include:
+
+- your clisbot version
+- channel and runner used
+- what you expected
+- what happened instead
+- relevant `clisbot status` or `clisbot logs` output with secrets removed
+
 ## Contributing
 
 Merge requests are welcome.