herdrchat 1.3.2 → 1.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 # herdrchat
 
-Every terminal hc runs, in the chat app you already use: Feishu or Telegram.
+The chat client for hc ([herdr](https://herdr.dev)): see and answer every hc terminal from Feishu or Telegram.
 
 [English](README.md) · [简体中文](README.zh.md)
 
@@ -12,13 +12,15 @@ Every terminal hc runs, in the chat app you already use: Feishu or Telegram.
 
 </div>
 
+**herdr-app is hc's desktop and phone client; herdrchat is hc's chat client.**
+
 [herdr](https://herdr.dev) runs your coding agents (Claude Code, codex, pi, …) in
-terminals that stay alive: **hc** (herdr-core) keeps them running, **herdr-app** shows
-them in spaces and tabs. herdr-app has phone and desktop apps, but your phone has to
+terminals that stay alive: **hc** (herdr-core) keeps them running, and herdr-app shows
+them in spaces and tabs. But to use herdr-app away from your desk, your phone has to
 reach the machine that runs hc, so you first need a VPN or a private network, and working
 with an agent on a small phone screen is clumsy.
 
-herdrchat puts them in a chat app instead. It connects out to Feishu or Telegram by
+herdrchat shows the same terminals in a chat app you already have on your phone. It connects out to Feishu or Telegram by
 itself, so there is nothing to set up on your network: no public IP, no VPN. Each
 herdr-app tab gets its own Feishu group, or a topic in your private chat with the
 Telegram bot. You read what the agent says while it works, tap buttons to answer its
@@ -31,7 +33,10 @@ until herdrchat learns to read their conversations too.
 
 ## You need
 
-- **hc** running on this machine, with at least one session ([herdr.dev](https://herdr.dev)).
+- **herdr**: herdrchat is built on it and does nothing without it. Install it from
+  [herdr.dev](https://herdr.dev) first (or let your coding agent do it with you:
+  `/herdrchat setup` offers to); its **hc** must run on this machine, with at least one
+  session.
 - **Node.js 20** or newer, on **macOS or Linux**.
 - **Feishu**: a Feishu team (not Lark) where you may create a custom app and publish it.
   **Telegram**: a Telegram account. Use one app, or both at once.
@@ -56,17 +61,21 @@ reach the agent.
 **With your agent:** ask it `/herdrchat setup`. It asks which chat app, then walks you
 through everything, clicking in the Feishu console for you when it can.
 
-**By hand:**
+**In the terminal** (the same steps, asked one by one; the agent can also click through
+the Feishu console for you, with the [Ego Lite](https://lite.ego.app/) browser, which the
+terminal cannot; without Ego it tells you what to click):
 
 ```bash
-herdrchat init --chat telegram   # or --chat feishu; it prints where the settings file is
-# fill in that file (each line says where its value comes from), then:
-herdrchat start                  # starts it and waits until it is connected
-herdrchat install                # once it works: start at login, come back after a crash
+herdrchat setup
 ```
 
-The steps for each app (making the Feishu app, or the Telegram bot) are in the
-[guide](docs/guide.md#set-up-telegram).
+It asks which chat app, takes the bot's token (or the Feishu app's keys) and checks them
+at once, picks your hc sessions (`default` unless you say otherwise), starts the bot, and
+shows a 6-digit code: send it to the bot and it knows you are its owner. Last, it offers
+to keep it running as a service. No file to edit, no id to copy.
+
+Making the Telegram bot or the Feishu app, and doing it all by editing the settings file
+instead: the [guide](docs/guide.md#set-up-telegram).
 
 ## Use
 
@@ -84,7 +93,7 @@ start a terminal, `/kill` to end one.
 | `/herdrchat feishu <task>` | Does a task in the Feishu developer console (with the [Ego Lite](https://lite.ego.app/) browser, or step by step). |
 | `/herdrchat telegram <task>` | The Telegram bot, from @BotFather to the first topic. |
 
-On the command line: `herdrchat init`, `start`, `stop`, `status`, `logs`, `install`,
+On the command line: `herdrchat setup`, `pair`, `init`, `start`, `stop`, `status`, `logs`, `install`,
 `uninstall`, `version`; `herdrchat` alone lists them. Add `--profile <name>` to run a
 second chat app beside the first.
 

package/README.zh.md

@@ -2,7 +2,7 @@
 
 # herdrchat
 
-hc 跑的每个终端，都能在你常用的聊天软件里看到和回复：飞书或 Telegram。
+hc（[herdr](https://herdr.dev)）的聊天客户端：在飞书或 Telegram 里查看和回复 hc 的每一个终端。
 
 [English](README.md) · [简体中文](README.zh.md)
 
@@ -12,11 +12,13 @@ hc 跑的每个终端，都能在你常用的聊天软件里看到和回复：
 
 </div>
 
+**herdr-app 是 hc 的电脑和手机客户端；herdrchat 是 hc 的聊天客户端。**
+
 [herdr](https://herdr.dev) 让你的编程 agent（Claude Code、codex、pi……）跑在不会断的终端里：
-**hc**（herdr-core）让它们一直跑着，**herdr-app** 按空间和标签页把它们展示出来。herdr-app 有手机端和电脑端，
-但手机得能连到跑 hc 的机器，所以要先折腾 VPN 或内网；而且在手机的小屏幕上和 agent 交互，体验并不好。
+**hc**（herdr-core）让它们一直跑着，herdr-app 按空间和标签页把它们展示出来。
+但想在外面用 herdr-app，手机得能连到跑 hc 的机器，所以要先折腾 VPN 或内网；而且在手机的小屏幕上和 agent 交互，体验并不好。
 
-herdrchat 把它们搬进聊天软件。它自己主动连到飞书或 Telegram，网络上什么都不用配：不要公网 IP，也不要 VPN。
+herdrchat 把同样这些终端，放进你手机上本来就有的聊天软件里。它自己主动连到飞书或 Telegram，网络上什么都不用配：不要公网 IP，也不要 VPN。
 herdr-app 的每个标签页，在飞书里是一个群，在 Telegram 里是和 bot 私聊中的一个话题：
 agent 干活时说的话实时可见，它问你的问题点按钮就能回答，图片双向都能传，所有终端汇总在一张总览里。
 新开的群或话题会先补上之前的对话；只有 agent 需要你、或者做完的时候手机才会响
@@ -27,7 +29,8 @@ agent 干活时说的话实时可见，它问你的问题点按钮就能回答
 
 ## 需要什么
 
-- 这台机器上在跑 **hc**，至少有一个 session（[herdr.dev](https://herdr.dev)）。
+- **herdr**：herdrchat 是基于它做的，没有它什么都做不了。请先从 [herdr.dev](https://herdr.dev) 安装
+  （也可以让编程 agent 帮你装：`/herdrchat setup` 会主动问你）；它的 **hc** 要在这台机器上跑着，至少有一个 session。
 - **Node.js 20** 或更新版本，系统是 **macOS 或 Linux**。
 - **飞书**：一个能创建并发布企业自建应用的飞书团队（暂不支持 Lark 国际版）。
   **Telegram**：一个 Telegram 账号。可以只用一个，也可以两个同时用。
@@ -48,18 +51,19 @@ skill 会教你的编程 agent（Claude Code、Codex……）替你配置和照
 ## 配置
 
 **让 agent 帮你：** 对它说 `/herdrchat setup`。它会先问你用哪个聊天软件，然后一步步带你配好，
-能自动点的飞书后台操作它会替你点。
+飞书后台的操作，装了 [Ego Lite](https://lite.ego.app/) 浏览器它会替你点；没装的话，它会问你要不要装，不装就一步步告诉你点哪里。
 
-**自己动手：**
+**在终端里**（步骤和 agent 一样，一个个问你；区别是 agent 还能替你在飞书后台点，终端做不到）：
 
 ```bash
-herdrchat init --chat telegram   # 或者 --chat feishu；它会告诉你配置文件在哪
-# 填好那个文件（每一行上面都写了值从哪来），然后：
-herdrchat start                  # 启动，并等到真的连上
-herdrchat install                # 跑通以后：装成系统服务，开机自动启动，崩溃自动重启
+herdrchat setup
 ```
 
-每个聊天软件的具体步骤（建飞书应用，或者建 Telegram bot）在[详细说明](docs/guide.md#set-up-telegram)里（英文）。
+它会问你用哪个聊天软件，让你粘贴 bot 的 token（或飞书应用的 App ID 和 Secret）并当场检查，
+帮你选好要同步的 hc session（不改就是 `default`），然后启动 bot，并给你一个 6 位数字：
+把它发给 bot，bot 就认出你是主人。最后问你要不要装成系统服务。不用改文件，也不用复制任何 id。
+
+怎么建 Telegram bot 或飞书应用，以及想自己改配置文件的做法，见[详细说明](docs/guide.md#set-up-telegram)（英文）。
 
 ## 使用
 
@@ -76,7 +80,7 @@ herdrchat install                # 跑通以后：装成系统服务，开机自
 | `/herdrchat feishu <任务>` | 替你在飞书开发者后台完成操作（用 [Ego Lite](https://lite.ego.app/) 浏览器，或者一步步带你点）。 |
 | `/herdrchat telegram <任务>` | Telegram bot：从 @BotFather 一直到第一个话题。 |
 
-命令行：`herdrchat init`、`start`、`stop`、`status`、`logs`、`install`、`uninstall`、`version`；
+命令行：`herdrchat setup`、`pair`、`init`、`start`、`stop`、`status`、`logs`、`install`、`uninstall`、`version`；
 只输入 `herdrchat` 会列出全部。加上 `--profile <名字>`，可以再开一个聊天软件。
 
 ## 更新

package/bin/cli.mjs

@@ -2,6 +2,7 @@
 // herdrchat's command line: set up, start, stop and look at one profile.
 //
 //   herdrchat <command> [--profile <name>]
+//     setup      a few questions, and it is set up, started, paired with you and kept running
 //     init       make the profile's config.env from the example when it is missing
 //     install    run it as a service of the system (launchd, systemd): it starts at
 //                login and comes back after a crash; start, stop, status go through it
@@ -21,8 +22,13 @@ import { fileURLToPath } from 'node:url';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const GUIDE = 'https://github.com/zhangxiangliang/herdrchat/blob/main/docs/guide.md';
-const USAGE = `herdrchat <command> [--profile <name>]
+const HERDR = 'herdrchat is built on herdr: it mirrors the terminals that hc (herdr-core) runs.\nIt needs hc on this machine: install herdr first, from https://herdr.dev\n(or ask your coding agent `/herdrchat setup`: it can install herdr with you).';
+const USAGE = `herdrchat: the chat client for hc (herdr), in Feishu or Telegram. Needs hc (https://herdr.dev).
 
+herdrchat <command> [--profile <name>]
+
+  setup      set it up by answering a few questions (the easy way in)
+  pair       make you the bot's owner: it shows a code to send to the bot
   init       make the profile's config.env (--chat feishu|telegram picks the app)
   start      start (or restart) it: the service, or else its own hc terminal
   stop       stop it
@@ -33,7 +39,7 @@ const USAGE = `herdrchat <command> [--profile <name>]
   run        run in the foreground (what start keeps running)
   version    which herdrchat this is
 
-First time: herdrchat init, fill in the file it names, then herdrchat start.
+First time: herdrchat setup. (Or by hand: herdrchat init, fill in the file, herdrchat start.)
 A second chat app: add --profile <name> to every command.
 Environment: HERDRCHAT_PROFILE (same as --profile), HERDRCHAT_HOME (one folder for a
 profile's settings and state).
@@ -82,7 +88,8 @@ if (helpAsked || !command) {
 if (process.env.HERDRCHAT_PROFILE && !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(process.env.HERDRCHAT_PROFILE)) fail(`HERDRCHAT_PROFILE "${process.env.HERDRCHAT_PROFILE}": use letters, digits, - and _ only.`);
 
 // after the profile is set: lib/core/config.mjs reads it when it loads
-const { CONFIG_FILE, STATE_DIR, chatOf, loadConfig, makeDirs, placesOf } = await import('../lib/core/config.mjs');
+const { CONFIG_FILE, STATE_DIR, chatOf, loadConfig, makeDirs, placesOf, readState, setConfigValue, writeState } = await import('../lib/core/config.mjs');
+const { startPairing, PAIR_MINUTES } = await import('../lib/core/pairing.mjs');
 const { chatModule, chatNames } = await import('../lib/chats/index.mjs');
 const { coreUp, hc, sessionsHere } = await import('../lib/core/hc.mjs');
 const { serviceOf } = await import('../lib/core/service.mjs');
@@ -104,7 +111,10 @@ function readyConfig() {
   // a session not on this machine would be made by hc as the bot asks for it: a typo
   const here = sessionsHere();
   const unknown = cfg.sessions.filter((s) => !here.includes(s));
-  if (unknown.length) fail(`HERDR_SESSIONS in ${CONFIG_FILE} names ${unknown.join(', ')}, which ${unknown.length > 1 ? 'are' : 'is'} not an hc session on this machine.\nThe sessions here: ${here.join(', ') || 'none (start hc first)'}.`, 1);
+  if (unknown.length) {
+    const what = cfg.sessionsSet ? `HERDR_SESSIONS in ${CONFIG_FILE} names ${unknown.join(', ')}, which ${unknown.length > 1 ? 'are' : 'is'} not an hc session on this machine` : `HERDR_SESSIONS is empty, so herdrchat follows hc's default session, which is not on this machine`;
+    fail(`${what}.\nThe sessions here: ${here.join(', ') || 'none: install and start herdr first (https://herdr.dev)'}.${here.length ? ` Put the ones to mirror in HERDR_SESSIONS in ${CONFIG_FILE}.` : ''}`, 1);
+  }
   return cfg;
 }
 // a day's log file: the local date, as the log names its files
@@ -155,7 +165,7 @@ async function waitConnected(since) {
 // Nothing else, so no agent's variables come along.
 function botEnv() {
   const hcPath = findHc();
-  if (!hcPath) throw new Error('hc is not on PATH: install herdr-core first (https://herdr.dev)');
+  if (!hcPath) throw new Error(`hc is not on PATH. ${HERDR}`);
   const env = { HERDRCHAT_HC: hcPath, HERDRCHAT_PROFILE: places.profile };
   for (const k of ['PATH', 'HERDRCHAT_HOME', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME']) if (process.env[k]) env[k] = process.env[k];
   return env;
@@ -178,10 +188,240 @@ async function terminalState(session) {
   }
 }
 
+// ---------- setup: questions instead of a file to fill ----------
+
+async function prompter() {
+  const readline = await import('node:readline/promises');
+  let rl = null;
+  const open = () => { rl ||= readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true }); return rl; };
+  const shut = () => { rl?.close(); rl = null; };
+  const ask = async (q, fallback = '') => (await open().question(fallback ? `${q} [${fallback}] ` : `${q} `)).trim() || fallback;
+  // A token or a secret is typed with nothing shown, not even dots: the terminal is put in
+  // raw mode and each key is read here, so neither the terminal nor readline echoes it.
+  const askSecret = (q) => new Promise((resolve) => {
+    shut();
+    process.stdout.write(`${q} `);
+    const stdin = process.stdin;
+    stdin.setRawMode(true);
+    stdin.resume();
+    let value = '';
+    const onData = (buf) => {
+      for (const ch of buf.toString('utf8')) {
+        if (ch === '\u0003') { // Ctrl+C
+          stdin.setRawMode(false);
+          process.stdout.write('\n');
+          process.exit(130);
+        }
+        if (ch === '\r' || ch === '\n' || ch === '\u0004') {
+          stdin.setRawMode(false);
+          stdin.pause();
+          stdin.off('data', onData);
+          process.stdout.write('\n');
+          resolve(value.trim());
+          return;
+        }
+        if (ch === '\u007f' || ch === '\b') value = value.slice(0, -1);
+        else if (ch >= ' ') value += ch;
+      }
+    };
+    stdin.on('data', onData);
+  });
+  return { ask, askSecret, close: shut };
+}
+
+const ok = (text) => console.log(`✔ ${text}`);
+const bad = (text) => console.log(`✘ ${text}`);
+const tell = (text) => console.log(`  ${text}`);
+
+async function telegramMe(token) {
+  try {
+    const res = await fetch(`https://api.telegram.org/bot${token}/getMe`, { signal: AbortSignal.timeout(15000) });
+    const body = await res.json();
+    return body.ok ? body.result : { error: body.description || `HTTP ${res.status}` };
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+async function feishuCheck(appId, appSecret) {
+  try {
+    const res = await fetch('https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ app_id: appId, app_secret: appSecret }), signal: AbortSignal.timeout(15000) });
+    const body = await res.json();
+    return body.code === 0 ? { ok: true } : { error: body.msg || `code ${body.code}` };
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
 const commands = {
+  async setup() {
+    if (!process.stdin.isTTY) fail(`herdrchat setup asks questions, so run it in a terminal. Without one: herdrchat init${again}, fill in the file, herdrchat start${again}.`);
+    console.log(`herdrchat setup${again}: a few questions, then it runs.\n`);
+    // 1. herdr
+    const hcPath = findHc();
+    if (!hcPath) {
+      bad(`hc is not on PATH. ${HERDR}`);
+      process.exitCode = 1;
+      return;
+    }
+    const { execFileSync } = await import('node:child_process');
+    ok(`herdr is here (${execFileSync(hcPath, ['--version'], { encoding: 'utf8' }).trim()})`);
+    const p = await prompter();
+    try {
+      // 2. the chat app
+      makeDirs();
+      const had = fs.existsSync(CONFIG_FILE) ? loadConfig() : null;
+      let chatName = chatFlag || had?.chat;
+      if (!chatName || (!had && !chatFlag)) {
+        const pick = await p.ask('Which chat app? 1) Feishu  2) Telegram', had?.chat === 'telegram' ? '2' : '1');
+        chatName = pick === '2' || /^t/i.test(pick) ? 'telegram' : 'feishu';
+      }
+      if (!had) {
+        const example = fs.readFileSync(path.join(ROOT, 'config.env.example'), 'utf8').replace(/^HERDRCHAT_CHAT=.*$/m, `HERDRCHAT_CHAT=${chatName}`);
+        fs.writeFileSync(CONFIG_FILE, example, { mode: 0o600 });
+      } else {
+        setConfigValue(CONFIG_FILE, 'HERDRCHAT_CHAT', chatName);
+      }
+      ok(`${chatName}, settings in ${CONFIG_FILE}`);
+      const env = loadConfig().env;
+      // 3. its keys, checked now
+      if (chatName === 'telegram') {
+        let token = env.TELEGRAM_BOT_TOKEN || '';
+        if (!token) tell('Make a bot first: in Telegram, message @BotFather, send /newbot, pick a name; it gives you a token.');
+        for (;;) {
+          if (!token) token = await p.askSecret('Paste the token (it is not shown):');
+          const me = await telegramMe(token);
+          if (me.error) {
+            bad(`Telegram says: ${me.error}. Check the token and paste it again.`);
+            token = '';
+            continue;
+          }
+          setConfigValue(CONFIG_FILE, 'TELEGRAM_BOT_TOKEN', token);
+          ok(`the token works: @${me.username}`);
+          if (!me.has_topics_enabled) {
+            bad('topic mode is off, and herdrchat makes one topic per terminal.');
+            tell('In the @BotFather chat tap Open (its mini app), pick your bot, turn on Threaded Mode.');
+            await p.ask('Press Enter when it is on.');
+            continue;
+          }
+          ok('topic mode is on');
+          break;
+        }
+      } else {
+        let appId = env.FEISHU_APP_ID || '';
+        let appSecret = env.FEISHU_APP_SECRET || '';
+        if (!appId || !appSecret) {
+          tell('Make the Feishu app first, in https://open.feishu.cn/app: a custom app (企业自建应用) with the bot ability');
+          tell('and the scopes in the guide, "Set up: Feishu": ' + GUIDE + '#set-up-feishu');
+          tell('(your coding agent can click through it for you: /herdrchat feishu create the app)');
+        }
+        for (;;) {
+          if (!appId) appId = await p.ask('App ID (cli_…, on the app\'s 凭证与基础信息 page):');
+          if (!appSecret) appSecret = await p.askSecret('App Secret (it is not shown):');
+          const check = await feishuCheck(appId, appSecret);
+          if (check.error) {
+            bad(`Feishu says: ${check.error}. Check the App ID and Secret and give them again.`);
+            appId = '';
+            appSecret = '';
+            continue;
+          }
+          setConfigValue(CONFIG_FILE, 'FEISHU_APP_ID', appId);
+          setConfigValue(CONFIG_FILE, 'FEISHU_APP_SECRET', appSecret);
+          ok('the App ID and Secret work');
+          break;
+        }
+      }
+      // 4. which sessions
+      const here = sessionsHere();
+      if (!here.length) {
+        bad('herdr is installed but no hc session runs on this machine, so there is nothing to mirror yet.');
+        tell('Open herdr-app, or start hc as herdr\'s docs say (https://herdr.dev), then run herdrchat setup' + again + ' again: what is done so far is kept.');
+        process.exitCode = 1;
+        return;
+      }
+      const named = loadConfig().sessionsSet ? loadConfig().sessions.join(',') : '';
+      const fallback = named || (here.includes('default') ? 'default' : here[0] || 'default');
+      tell(`hc sessions on this machine: ${here.join(', ') || 'none yet'}. "default" with herdr-app reaches all it shows.`);
+      for (;;) {
+        const pick = (await p.ask('Which sessions to mirror (comma-separated)?', fallback)).split(',').map((x) => x.trim()).filter(Boolean);
+        const unknown = pick.filter((x) => !here.includes(x));
+        if (unknown.length) {
+          bad(`not on this machine: ${unknown.join(', ')}`);
+          continue;
+        }
+        setConfigValue(CONFIG_FILE, 'HERDR_SESSIONS', pick.join(',') === 'default' ? '' : pick.join(','));
+        ok(`following ${pick.join(', ')}`);
+        break;
+      }
+      // 5. start
+      console.log('');
+      await commands.start();
+      if (process.exitCode) return;
+      if (chatName === 'feishu') {
+        tell('Now, with the bot running, in the Feishu developer console: 事件与回调 -> long connection (长连接),');
+        tell('add the event im.message.receive_v1 and the callback card.action.trigger, then publish a version.');
+        await p.ask('Press Enter when the version is published.');
+      }
+      // 6. pair: the owner is whoever sends the code (the same step the agent runs)
+      await commands.pair();
+      if (process.exitCode) return;
+      // 7. keep it running
+      const svc = service();
+      if (svc && !svc.installed()) {
+        const yes = await p.ask('Keep it running as a service (starts at login, comes back after a crash)? [Y/n]', 'Y');
+        if (/^y/i.test(yes)) await commands.install();
+      }
+      console.log(`\nDone. herdrchat status${again} shows how it is; herdrchat logs${again} what it did.`);
+      if (chatName === 'feishu') console.log('Send /auth to the bot once to let it mute its groups, so your phone rings only when it should.');
+    } finally {
+      p.close();
+    }
+  },
+
+  // The owner, without copying an id: a 6-digit code sent to the bot. It needs no terminal,
+  // so `herdrchat setup` and the agent's `/herdrchat setup` both use it. Sending the code
+  // also proves the whole path works: the bot runs, the chat app delivers, events are on.
+  async pair() {
+    const cfg = loadConfig();
+    const ownerKey = cfg.chat === 'telegram' ? 'TELEGRAM_OWNER_ID' : 'FEISHU_OWNER_OPEN_ID';
+    if (cfg.env[ownerKey]) {
+      ok(`the owner is set already (${ownerKey} in ${CONFIG_FILE}); to change it, empty that line and pair again`);
+      return;
+    }
+    const svc = service();
+    const running = svc?.installed() ? svc.state().running : (await terminalState(cfg.sessions[0])) === 'live';
+    if (!running) fail(`The bot is not running, and it is the bot that reads the code. Run herdrchat start${again} first.`);
+    let where = 'your chat with the bot';
+    if (cfg.chat === 'telegram') {
+      const me = await telegramMe(cfg.env.TELEGRAM_BOT_TOKEN || '');
+      if (me.username) where = `your chat with @${me.username} (https://t.me/${me.username}), tap Start if Telegram shows it,`;
+    } else {
+      where = 'your chat with the bot (in Feishu, search the app\'s name, open it, and message it)';
+    }
+    const code = startPairing({ read: readState, write: writeState });
+    console.log(`\nOpen ${where} and send it this code:\n\n      ${code}\n`);
+    tell(`It works for ${PAIR_MINUTES} minutes. Waiting…`);
+    const since = new Date().toISOString();
+    const until = Date.now() + PAIR_MINUTES * 60 * 1000;
+    while (Date.now() < until && !loadConfig().env[ownerKey]) await new Promise((r) => setTimeout(r, 2000));
+    if (!loadConfig().env[ownerKey]) {
+      bad(`no code came in ${PAIR_MINUTES} minutes. Run herdrchat pair${again} for a new one.`);
+      if (cfg.chat === 'feishu') tell('When the bot never answered at all: in the developer console, check the event im.message.receive_v1 is added on the long connection, and that a version with it is published.');
+      else tell('When the bot never answered at all: herdrchat logs' + again + ' says why.');
+      process.exitCode = 1;
+      return;
+    }
+    ok('paired: you are the owner. It starts again as yours…');
+    const back = await waitConnected(since);
+    if (!back.ok) return failedToConnect('It paired', back);
+    ok(`connected; your terminals' ${cfg.chat === 'telegram' ? 'topics' : 'groups'} appear in a moment`);
+  },
+
   init() {
     const chatName = chatFlag || 'feishu';
     if (!chatNames().includes(chatName)) fail(`--chat ${chatName}: the chat apps are ${chatNames().join(', ')}`);
+    // the settings can be made first, but nothing works without herdr: said before anything
+    if (!findHc()) console.log(`⚠️  hc is not on PATH. ${HERDR}\n`);
     makeDirs();
     if (fs.existsSync(CONFIG_FILE)) {
       console.log(`${CONFIG_FILE} is there already; open it and edit it, then run \`herdrchat start${again}\`.`);
@@ -190,7 +430,7 @@ const commands = {
     const example = fs.readFileSync(path.join(ROOT, 'config.env.example'), 'utf8').replace(/^HERDRCHAT_CHAT=.*$/m, `HERDRCHAT_CHAT=${chatName}`);
     fs.writeFileSync(CONFIG_FILE, example, { mode: 0o600 });
     const keys = (chatModule(chatName).requires || []).join(', ');
-    console.log(`Made ${CONFIG_FILE} (only you can read it) for ${chatName}.\nOpen it and fill in ${keys} and HERDR_SESSIONS (the hc sessions to mirror), then run \`herdrchat start${again}\`.\nThe guide walks through it: ${GUIDE}`);
+    console.log(`Made ${CONFIG_FILE} (only you can read it) for ${chatName}.\nOpen it and fill in ${keys} (HERDR_SESSIONS is hc's default session unless you name others), then run \`herdrchat start${again}\`.\nThe guide walks through it: ${GUIDE}`);
   },
 
   // The service file is written again each time (a moved node or hc is picked up), and
@@ -265,11 +505,11 @@ const commands = {
       if (!here.includes(session)) sessionWords.push(`${session} (no such session here; this machine has: ${here.join(', ') || 'none'})`);
       else sessionWords.push(`${session} (${(await coreUp(session)) ? 'core up' : 'core not running'})`);
     }
-    console.log(`sessions  ${sessionWords.join(', ') || 'none yet: set HERDR_SESSIONS (`ls ~/.local/state/herdr-core` lists them)'}`);
+    console.log(`sessions  ${sessionWords.join(', ')}${cfg.sessionsSet ? '' : ' (hc\'s default session: HERDR_SESSIONS is empty)'}`);
     // how it runs: the service, an hc terminal, or not at all
     const svc = hcThere ? service() : null;
     if (!hcThere) {
-      console.log('running   unknown: hc is not on PATH (install herdr-core: https://herdr.dev)');
+      console.log('running   unknown: hc is not on PATH; herdrchat is built on herdr: install it from https://herdr.dev');
     } else {
       const inTerminal = cfg.sessions.length ? (await terminalState(cfg.sessions[0])) === 'live' : false;
       if (svc?.installed()) {

package/bin/herdrchat.mjs

@@ -5,7 +5,8 @@
 //
 // Usage: node bin/herdrchat.mjs (`herdrchat start` keeps it running)
 import path from 'node:path';
-import { STATE_DIR, chatOf, loadConfig, makeDirs, readState, writeState } from '../lib/core/config.mjs';
+import { STATE_DIR, chatOf, loadConfig, makeDirs, readState, setConfigValue, writeState } from '../lib/core/config.mjs';
+import { tryPairing } from '../lib/core/pairing.mjs';
 import { createEngine } from '../lib/core/engine.mjs';
 import { followEvents } from '../lib/core/events.mjs';
 import { cores, getTerminal, hc, keys, machines, nameTab, put, run, screenTail, send } from '../lib/core/hc.mjs';
@@ -34,6 +35,17 @@ const chat = createChat(cfg.chat, {
   stateDir: STATE_DIR,
   lane: (k, label, fn) => engine.laneOf(k, label, fn),
   scopeOf: (k) => engine.scopeOfKey(k),
+  // the pairing code from `herdrchat setup`: its sender becomes the owner, written to
+  // config.env; the bot then starts again (its service or terminal brings it back) as theirs
+  claimOwner: (text, key, id) => {
+    const result = tryPairing(store, text);
+    if (result === 'ok') {
+      setConfigValue(cfg.configFile, key, id);
+      log(`paired: ${key} set; starting again as the owner's`);
+      setTimeout(() => process.exit(0), 2000);
+    }
+    return result;
+  },
 });
 
 // A bot that is down is a phone that hears nothing, so down time is said in the direct

package/config.env.example

@@ -7,7 +7,8 @@
 # (`herdrchat init --profile telegram --chat telegram`).
 HERDRCHAT_CHAT=feishu
 
-# The hc sessions to mirror, comma-separated (machines they reach come along).
+# The hc sessions to mirror, comma-separated (machines they reach come along). Empty is
+# hc's own session, `default`: with herdr-app it reaches every session herdr-app shows.
 # `ls ~/.local/state/herdr-core` lists the sessions on this machine.
 HERDR_SESSIONS=
 

package/docs/guide.md

@@ -2,8 +2,8 @@
 
 How herdrchat works and every setting, for when the README is not enough.
 
-herdrchat is a chat front-end for hc: every herdr-app tab, followed and answered in a chat
-app, Feishu or Telegram. Both sit on the same core (hc events, a reader per agent,
+herdrchat is hc's chat client, as herdr-app is its desktop and phone client: every
+herdr-app tab, followed and answered in a chat app, Feishu or Telegram. Both sit on the same core (hc events, a reader per agent,
 dialogs, the overview), each behind one contract (`docs/architecture.md`); Slack and
 Discord may follow the same way. A profile is one chat app (`HERDRCHAT_CHAT`); to use
 both, run a profile each.
@@ -85,7 +85,7 @@ In the profile's `config.env` (`herdrchat status` prints where it is):
 | Key | For | Default | What it does |
 |---|---|---|---|
 | `HERDRCHAT_CHAT` | both | `feishu` | the chat app this profile mirrors into: `feishu` or `telegram` |
-| `HERDR_SESSIONS` | both | (required) | the hc sessions to mirror, comma-separated; machines they reach come along |
+| `HERDR_SESSIONS` | both | `default` | the hc sessions to mirror, comma-separated; machines they reach come along. `default` is hc's own session, which with herdr-app reaches every session it shows |
 | `HERDR_MUTED_SPACES` | both | `all` | spaces whose rooms are quiet: only "needs you" and "done" ring; empty for none |
 | `HERDR_SILENT_SPACES` | both | (none) | spaces where nothing rings, not even "needs you" |
 | `HERDR_HISTORY` | both | `file,folded` | what a new room gets of the conversation before it: `file`, `folded`, both, or empty |
@@ -228,6 +228,11 @@ delivered (the terminal has ended) says so plainly.
   dialog it waits on, as is), `/esc`, `/history` (the conversation so far, as a file and
   a folded post). Dialog cards have buttons.
 
+`herdrchat setup` does the steps below by asking: it checks the token or the Feishu keys
+at once, picks the sessions, starts the bot and pairs you as its owner with a 6-digit
+code you send to the bot, then offers the service. The steps say what happens, and how
+to do it by hand. When the owner is missing later, `herdrchat pair` shows a new code.
+
 ## Set up: Telegram
 
 1. In Telegram, message **@BotFather**: `/newbot`, give it a name and a username ending
@@ -235,10 +240,10 @@ delivered (the terminal has ended) says so plainly.
 2. Turn on topics for the bot: in the BotFather chat tap **Open** (its mini app), pick the
    bot, turn on **Threaded Mode**. Without it the bot cannot make topics.
 3. `herdrchat init --chat telegram` (with `--profile <name>` too if you also run Feishu)
-   prints where its `config.env` is. Fill in `TELEGRAM_BOT_TOKEN` and `HERDR_SESSIONS`
-   (`ls ~/.local/state/herdr-core` lists your hc sessions).
-4. `herdrchat start`, then message the bot anything. It answers with the line to add,
-   `TELEGRAM_OWNER_ID=<your id>`; add it and run `herdrchat start` again. One topic per
+   prints where its `config.env` is. Fill in `TELEGRAM_BOT_TOKEN`. `HERDR_SESSIONS`
+   can stay empty for hc's default session (`ls ~/.local/state/herdr-core` lists yours).
+4. `herdrchat start`, then `herdrchat pair`: it shows a 6-digit code. Open the bot (tap
+   Start) and send it the code; the bot makes you its owner and starts again. One topic per
    tab appears in your private chat with the bot (Telegram takes about one message a
    second, so many tabs take a moment).
 5. Once it works: `herdrchat install` (see "Running as a service").
@@ -249,8 +254,9 @@ If Telegram is your only app, use the default profile with `--chat telegram`. Us
 ## Set up: Feishu
 
 Feishu only: Lark (the international version) is not supported yet. Steps 1, 2, 5 and 6
-are in the Feishu developer console (`https://open.feishu.cn/app`); the herdrchat skill
-(`/herdrchat setup`) can do them with you.
+are in the Feishu developer console (`https://open.feishu.cn/app`). The herdrchat skill
+(`/herdrchat setup`) clicks them for you with the [Ego Lite](https://lite.ego.app/)
+browser, or tells you what to click without it; or follow the steps here yourself.
 
 1. Create a custom app (企业自建应用) and add the bot ability (机器人).
 2. Permissions: import the scopes listed in `skills/herdrchat/references/feishu.md`,
@@ -258,8 +264,8 @@ are in the Feishu developer console (`https://open.feishu.cn/app`); the herdrcha
    reading the messages sent to it, making and renaming groups, reactions, images both
    ways, and group tags.
 3. `herdrchat init` prints where its `config.env` is. Fill in the app's App ID and App
-   Secret (the app's 凭证与基础信息 page) and `HERDR_SESSIONS` (`ls
-   ~/.local/state/herdr-core` lists your hc sessions).
+   Secret (the app's 凭证与基础信息 page). `HERDR_SESSIONS` can stay empty for hc's
+   default session (`ls ~/.local/state/herdr-core` lists yours).
 4. `herdrchat start`. The bot must be running for the next step: the console checks for
    a live connection.
 5. Events and callbacks (事件与回调): for events, choose the long connection mode (长连接)
@@ -267,9 +273,9 @@ are in the Feishu developer console (`https://open.feishu.cn/app`); the herdrcha
    mode too and add `card.action.trigger` (the dialog buttons).
 6. Publish a version. If the page does not say 本次发布免审核, your team's admin must
    approve it first.
-7. Open `https://applink.feishu.cn/client/bot/open?appId=<app id>` and send anything.
-   The bot answers with the line to add, `FEISHU_OWNER_OPEN_ID=<your open_id>`; add it
-   and run `herdrchat start` again. One group per tab appears.
+7. `herdrchat pair`: it shows a 6-digit code. In Feishu, search the app's name, open the
+   bot and send it the code; the bot makes you its owner and starts again. One group per
+   tab appears. When the code gets no answer, step 5 or 6 is not done.
 8. Optional: send `/auth` to the bot so it can mute its groups for you ("Optional: let
    the bot act as you"), and add the bot menu (`skills/herdrchat/references/feishu.md`,
    "The bot menu").

package/lib/chats/contract.mjs

@@ -12,7 +12,10 @@
 // working | closed | needs | done | good | bad.
 //
 // ctx: {cfg, store: {read, write}, log, logWarn, logError, stateDir,
-//       lane(k, label, fn): run fn in the room's lane, scopeOf(k): its session or machine}
+//       lane(k, label, fn): run fn in the room's lane, scopeOf(k): its session or machine,
+//       claimOwner(text, key, id) -> 'ok' | 'wrong' | 'none': with no owner yet, a message
+//       that may be the pairing code `herdrchat setup` shows; on 'ok' the id is written
+//       to config.env as `key` and the bot starts again as that owner's}
 
 export const CHAT_MEMBERS = {
   name: 'string: the app, as in HERDRCHAT_CHAT',
@@ -21,7 +24,7 @@ export const CHAT_MEMBERS = {
   roomWord: 'string: what the user calls a room in this app (group, topic), for what the bot says',
   liveBytes: 'number: how much text one editable card holds',
   split: '(markdown) -> string[]: one message\'s worth each',
-  start: '({onMessage, onAction, onReady}): connect; onMessage({room|null, where, message, text, images}) for the owner\'s messages (room null: the direct chat), onAction({value, message, answer}) -> {toast: {type, text}, card?: {kind: done|dialog, ...}} for button clicks',
+  start: '({onMessage, onAction, onReady}): connect; onMessage({room|null, where, message, text, images}) for the owner\'s messages (room null: the direct chat), onAction({value, message, answer, ticks?}) -> {toast: {type, text}, card?: {kind: done|dialog, ...}} for button clicks; ticks: {<option n>: true|false}, a multi-select\'s boxes as ticked on the card itself (a form, sent with Next), when the app has them',
   command: '(cmd, args, where) -> boolean: one of its own direct-chat commands, handled',
   openRoom: '({name, intro}) -> room',
   renameRoom: '(room, name)',

package/lib/chats/feishu/client.mjs

@@ -102,14 +102,24 @@ function button(text, value, type = 'default') {
   return { tag: 'button', type, width: 'fill', text: { tag: 'plain_text', content: short }, behaviors: [{ type: 'callback', value }] };
 }
 
+// A multi-select's boxes are checkers in a form: with no behaviors a checker is ticked on
+// the phone only, so ticking makes no call and shows no loading; Next submits the form,
+// and each box comes back in form_value under its name, box_<n> (ticksOf reads them).
+export const BOX = 'box_';
 export function menuCard({ title, markdown, menu, value }) {
   const elements = [{ tag: 'markdown', content: markdown }];
+  const boxes = [];
   for (const o of menu.options) {
     if (o === menu.free) continue;
-    const box = o.checked === null ? '' : o.checked ? '☑ ' : '☐ ';
-    elements.push(button(`${o.n}. ${box}${o.label}`, { ...value, pick: o.n, label: o.label }, o.n === 1 && !menu.multi ? 'primary' : 'default'));
+    if (menu.multi && o.checked !== null) {
+      boxes.push({ tag: 'checker', name: `${BOX}${o.n}`, checked: o.checked, text: { tag: 'plain_text', content: `${o.n}. ${o.label}` } });
+      continue;
+    }
+    elements.push(button(`${o.n}. ${o.label}`, { ...value, pick: o.n, label: o.label }, o.n === 1 && !menu.multi ? 'primary' : 'default'));
+  }
+  if (menu.multi) {
+    elements.push({ tag: 'form', name: 'boxes', elements: [...boxes, { ...button('Next ⇥', { ...value, pick: 'tab' }, 'primary'), name: 'next', form_action_type: 'submit' }] });
   }
-  if (menu.multi) elements.push(button('Next ⇥', { ...value, pick: 'tab' }, 'primary'));
   if (menu.free) {
     elements.push({
       tag: 'form',
@@ -306,3 +316,12 @@ export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}, on
   });
   return ws;
 }
+
+// The boxes as ticked, from a submitted form: {<n>: true|false}, or null when form_value
+// has none of them (then nothing can be known, and nothing should be pressed). A checker's
+// value is read as true when it is true or "true".
+export function ticksOf(formValue) {
+  const entries = Object.entries(formValue || {}).filter(([name]) => name.startsWith(BOX));
+  if (!entries.length) return null;
+  return Object.fromEntries(entries.map(([name, v]) => [Number(name.slice(BOX.length)), v === true || v === 'true']));
+}

package/lib/chats/feishu/index.mjs

@@ -3,7 +3,7 @@
 // avatars, and, after /auth, acting as you (muted groups, your labels, pins, @ mentions).
 // The core (lib/core/engine.mjs) calls only what is returned here; see "The chat side"
 // there for what each call means.
-import { createClient, bindTag, chunk, createChat, createTag, doneCard, downloadImage, foldedCard, menuCard, messageParts, recallMessage, renameChat, replyMention, sendCard, sendFile, sendMarkdown, setChatAvatar, startEvents, tagName, textCard, unbindTag, updateCard, uploadImage } from './client.mjs';
+import { ticksOf, createClient, bindTag, chunk, createChat, createTag, doneCard, downloadImage, foldedCard, menuCard, messageParts, recallMessage, renameChat, replyMention, sendCard, sendFile, sendMarkdown, setChatAvatar, startEvents, tagName, textCard, unbindTag, updateCard, uploadImage } from './client.mjs';
 import { COLORS, avatarPng, letterOf } from './avatar.mjs';
 import { overviewCard, overviewText } from './overview.mjs';
 import { createUserAuth } from './userauth.mjs';
@@ -28,7 +28,7 @@ const spaceOfName = (name) => (name || '').split(' / ')[0];
 // room's terminal belongs to (its tag and label).
 export const requires = ['FEISHU_APP_ID', 'FEISHU_APP_SECRET'];
 
-export function create({ cfg, store, log, logWarn, logError, stateDir, lane, scopeOf }) {
+export function create({ cfg, store, log, logWarn, logError, stateDir, lane, scopeOf, claimOwner = () => 'none' }) {
   const client = createClient(cfg);
   const userAuth = createUserAuth(cfg, stateDir);
   const { read, write } = store;
@@ -440,8 +440,13 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
       const msg = data.message;
       const openId = data.sender?.sender_id?.open_id;
       if (!cfg.ownerOpenId) {
-        log(`owner not set; message from open_id ${openId}`);
-        if (msg.chat_type === 'p2p') await reply(msg.chat_id, `Hello! To make you this bot's owner (the only person it listens to), add this line to ${cfg.configFile || 'config.env'}:\n\n\`FEISHU_OWNER_OPEN_ID=${openId}\`\n\nthen run ${startAgain(cfg)}. Your terminals' groups appear then.`);
+        if (msg.chat_type !== 'p2p') return;
+        const said = messageParts(msg.message_type, msg.content)?.text || '';
+        const paired = said.trim().startsWith('/') ? 'none' : claimOwner(said, 'FEISHU_OWNER_OPEN_ID', openId);
+        log(`owner not set; message from open_id ${openId} (pairing: ${paired})`);
+        if (paired === 'ok') await reply(msg.chat_id, '✅ Paired: you are this bot\'s owner now. It starts again, and your terminals\' groups appear in a moment.\n\nThen: type in a terminal\'s group to talk to it; here, /ls shows them all, /new starts one, /auth lets the bot mute its groups.');
+        else if (paired === 'wrong') await reply(msg.chat_id, 'That is not the code. Send the 6 digits `herdrchat setup` shows.');
+        else await reply(msg.chat_id, `Hello! This bot has no owner yet. Run \`herdrchat setup${cfg.profile && cfg.profile !== 'default' ? ` --profile ${cfg.profile}` : ''}\` and send me the code it shows; or add this line to ${cfg.configFile || 'config.env'} yourself and run ${startAgain(cfg)}:\n\n\`FEISHU_OWNER_OPEN_ID=${openId}\``);
         return;
       }
       if (openId !== cfg.ownerOpenId) {
@@ -461,7 +466,17 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
     // callback response: a toast and, when the card changes, its new form.
     const handleAction = async (data) => {
       if (data.operator?.open_id !== cfg.ownerOpenId) return { toast: { type: 'error', content: 'Only the owner can answer.' } };
-      const out = await onAction({ value: data.action?.value || {}, message: data.context?.open_message_id, answer: String(data.action?.form_value?.answer || '') });
+      const value = data.action?.value || {};
+      const form = data.action?.form_value;
+      let ticks = null;
+      if (value.pick === 'tab' && form) {
+        ticks = ticksOf(form);
+        // what each box sent, by type only (never what it says): to see the shape Feishu uses
+        log(`card form: ${Object.entries(form).map(([n, v]) => `${n}=${typeof v}:${typeof v === 'boolean' ? v : String(v).length}`).join(' ') || 'empty'}`);
+        // no box came back: the ticks are unknown, and a wrong answer is worse than none
+        if (!ticks) return { toast: { type: 'error', content: 'No ticked box came through, so nothing was sent. Tick at least one, or answer it in herdr-app.' } };
+      }
+      const out = await onAction({ value, message: data.context?.open_message_id, answer: String(form?.answer || ''), ticks });
       const res = { toast: { type: out.toast.type, content: out.toast.text } };
       if (out.card?.kind === 'done') res.card = { type: 'raw', data: doneCard(out.card.dialog.doneTitle, out.card.dialog.markdown, out.card.done) };
       if (out.card?.kind === 'dialog') res.card = { type: 'raw', data: menuCard({ title: out.card.dialog.title, markdown: out.card.dialog.markdown, menu: out.card.dialog.menu, value: out.card.value }) };

package/lib/chats/telegram/index.mjs

@@ -53,7 +53,7 @@ const inSpaces = (set, space) => set.all || set.spaces.includes(space);
 const spaceOfName = (name) => (name || '').split(' / ')[0];
 const cut = (text, max) => (text.length > max ? `${text.slice(0, max - 1)}…` : text);
 
-export function create({ cfg, store, log, logWarn, logError }) {
+export function create({ cfg, store, log, logWarn, logError, claimOwner = () => 'none' }) {
   const env = cfg.env || {};
   const owner = String(env.TELEGRAM_OWNER_ID || '').trim();
   const tg = createClient(env.TELEGRAM_BOT_TOKEN, { log: logWarn });
@@ -331,8 +331,13 @@ export function create({ cfg, store, log, logWarn, logError }) {
     const from = String(m.from?.id || '');
     const where = `${m.chat.id}:${m.is_topic_message ? m.message_thread_id : ''}`;
     if (!owner) {
-      log(`owner not set; message from user id ${from}`);
-      if (m.chat.type === 'private') await reply(where, `Hello! To make you this bot's owner (the only person it listens to), add this line to ${cfg.configFile || 'config.env'}:\n\n\`TELEGRAM_OWNER_ID=${from}\`\n\nthen run ${startAgain(cfg)}. Your terminals' topics appear then.`);
+      if (m.chat.type !== 'private') return;
+      // Telegram sends /start when someone first opens the bot: a command is never a guess
+      const paired = String(m.text || '').startsWith('/') ? 'none' : claimOwner(m.text, 'TELEGRAM_OWNER_ID', from);
+      log(`owner not set; message from user id ${from} (pairing: ${paired})`);
+      if (paired === 'ok') await reply(where, '✅ Paired: you are this bot\'s owner now. It starts again, and your terminals\' topics appear in a moment.\n\nThen: type in a terminal\'s topic to talk to it; here, /ls shows them all, /new starts one.');
+      else if (paired === 'wrong') await reply(where, 'That is not the code. Send the 6 digits `herdrchat setup` shows.');
+      else await reply(where, `Hello! This bot has no owner yet. Run \`herdrchat setup${cfg.profile && cfg.profile !== 'default' ? ` --profile ${cfg.profile}` : ''}\` and send me the code it shows; or add this line to ${cfg.configFile || 'config.env'} yourself and run ${startAgain(cfg)}:\n\n\`TELEGRAM_OWNER_ID=${from}\``);
       return;
     }
     if (from !== owner || String(m.chat.id) !== owner) {

package/lib/core/config.mjs

@@ -11,7 +11,8 @@
 //   FEISHU_OWNER_OPEN_ID             your open_id for that app; the only person it listens to
 //   TELEGRAM_BOT_TOKEN               herdrchat's Telegram bot (topic mode on, in @BotFather)
 //   TELEGRAM_OWNER_ID                your Telegram user id; the only person it listens to
-//   HERDR_SESSIONS                   hc sessions to mirror, comma-separated
+//   HERDR_SESSIONS                   hc sessions to mirror, comma-separated; empty: `default`,
+//                                    hc's own (with herdr-app it reaches every session it shows)
 //   HERDR_MUTED_SPACES               spaces whose rooms are quiet, so only "needs you" and
 //                                    "done" ring (Feishu: groups muted, once /auth is done,
 //                                    and an @; Telegram: silent posts and a reply that
@@ -76,6 +77,20 @@ function parseEnv(file) {
   return env;
 }
 
+// Sets one key in a config.env, keeping every other line (and its comments) as it was:
+// the key's line is replaced, or the key is added at the end. The file stays private.
+export function setConfigValue(file, key, value) {
+  const lines = fs.existsSync(file) ? fs.readFileSync(file, 'utf8').split('\n') : [];
+  const at = lines.findIndex((l) => new RegExp(`^\\s*${key}\\s*=`).test(l));
+  if (at >= 0) lines[at] = `${key}=${value}`;
+  else {
+    if (lines.length && lines[lines.length - 1] === '') lines.pop();
+    lines.push(`${key}=${value}`, '');
+  }
+  fs.writeFileSync(file, lines.join('\n'), { mode: 0o600 });
+  fs.chmodSync(file, 0o600);
+}
+
 // A list of spaces: `all`, empty or `none` for none, or the spaces listed. `fallback` is
 // what an unset variable means.
 export function spacesOf(value, fallback) {
@@ -105,19 +120,23 @@ export function onOff(value, fallback) {
 
 // `requires`: config keys the chat app cannot start without (its module's `requires`).
 // `env` is everything config.env and the environment hold, for the app's own keys.
-// `sessions: false`: an empty HERDR_SESSIONS is not an error (status shows what is set).
+// An empty HERDR_SESSIONS means hc's own session, `default` (`sessionsSet` says whether
+// it was named). `sessions: false` is kept for callers that only read what is set.
+export const DEFAULT_SESSION = 'default';
 export function loadConfig({ requires = [], sessions: needSessions = true } = {}) {
   const env = { ...parseEnv(CONFIG_FILE), ...process.env };
-  const sessions = (env.HERDR_SESSIONS || '').split(',').map((s) => s.trim()).filter(Boolean);
+  const named = (env.HERDR_SESSIONS || '').split(',').map((s) => s.trim()).filter(Boolean);
+  const sessions = named.length ? named : [DEFAULT_SESSION];
   const missing = requires.filter((k) => !env[k]);
   if (missing.length) throw new Error(`${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} empty in ${CONFIG_FILE}: fill ${missing.length > 1 ? 'them' : 'it'} in (the comment above each says where it comes from), then start again.`);
-  if (needSessions && !sessions.length) throw new Error(`HERDR_SESSIONS is empty in ${CONFIG_FILE}: put the hc sessions to mirror there, comma-separated (\`ls ~/.local/state/herdr-core\` lists the sessions on this machine), then start again.`);
+  void needSessions; // an empty list is `default` now: never an error here
   return {
     profile: places.profile,
     configFile: CONFIG_FILE,
     chat: env.HERDRCHAT_CHAT || 'feishu',
     env,
     sessions,
+    sessionsSet: named.length > 0,
     appId: env.FEISHU_APP_ID || '',
     appSecret: env.FEISHU_APP_SECRET || '',
     ownerOpenId: env.FEISHU_OWNER_OPEN_ID || '',

package/lib/core/engine.mjs

@@ -567,7 +567,8 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     const markdown = menu ? escapeMarkdown(menu.text) : `\`\`\`\n${tidyScreen(screenText, DIALOG_LINES)}\n\`\`\``;
     return { menu, title, markdown, doneTitle: DONE_TITLE };
   }
-  const dialogValue = (session, address, dialog) => ({ s: session, a: address, k: dialog.menu.key });
+  // c: the terminal's width when the card was made, to tell a resize from a new dialog
+  const dialogValue = (session, address, dialog, cols) => ({ s: session, a: address, k: dialog.menu.key, ...(cols ? { c: cols } : {}) });
 
   // One dialog gets one card. A dialog is named by its menu key (or, with no menu, by its
   // status words); the name is claimed before anything is sent, so the turn event, a
@@ -620,6 +621,16 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       return;
     }
     if (!claimDialog(k, dialog, record.status) && !again) return;
+    try {
+      await sendBlocked(session, address, record, k, dialog);
+    } catch (err) {
+      // not posted: let the next event (or a held message) post it, never "posted already"
+      if (postedDialog.get(k) === dialogName(dialog, record.status)) postedDialog.delete(k);
+      throw err;
+    }
+    log(`<- ${session}/${address}: blocked${dialog.menu ? ` (${dialog.menu.options.length} options)` : ''}`);
+  }
+  async function sendBlocked(session, address, record, k, dialog) {
     await closeCard(k, 'It moved on; see the next card.');
     if (!dialog.menu) {
       const sent = await postTo(session, record, `**${dialog.title}**\n\n${dialog.markdown}\n\nReply \`/answer <text>\` to answer it, or \`/esc\` to cancel it.`);
@@ -627,7 +638,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       if (room) await chat.pin(k, room, sent);
       await chat.ring(k, sent, '⚠️ needs you');
     } else {
-      const message = await deliver(session, record, (room) => chat.postDialog(room, dialog, dialogValue(session, address, dialog)));
+      const message = await deliver(session, record, (room) => chat.postDialog(room, dialog, dialogValue(session, address, dialog, record.cols)));
       if (message) {
         remember(message, dialog);
         openCard.set(k, { message, dialog });
@@ -637,9 +648,10 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
         // answered while the card was on its way: nothing will close it later, so now
         const live = views.get(session)?.terminals.get(address);
         if (live?.status?.state !== 'blocked' || postedDialog.get(k) !== dialogName(dialog, record.status)) await closeCard(k, '✔ Answered.');
+      } else {
+        throw new Error('the room for its card is gone');
       }
     }
-    log(`<- ${session}/${address}: blocked${dialog.menu ? ` (${dialog.menu.options.length} options)` : ''}`);
   }
 
   // The keys that pick an option: its digit, or, in a question with previews (which takes
@@ -664,7 +676,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
   // unless it still shows the dialog the card was made from (same key) with the same
   // option. After the key, the card turns into the dialog's next step (the next question,
   // the review, a toggled box) or says what was picked.
-  async function onAction({ value: v = {}, message, answer = '' }) {
+  async function onAction({ value: v = {}, message, answer = '', ticks = null }) {
     const started = Date.now();
     const shown = dialogCards.get(message) || { title: NEEDS_TITLE, markdown: '', doneTitle: DONE_TITLE };
     // A box in a multi-select is ticked on the card only, at once; Next sends them all.
@@ -680,25 +692,37 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       log(`-> ${v.s}/${v.a}: click on ${message} not pressed: the terminal has ended`);
       return answered(shown, 'The terminal has ended.');
     }
-    const status = (await hc.getTerminal(v.s, v.a)).status;
+    const term = await hc.getTerminal(v.s, v.a);
+    const status = term.status;
     const menu = status?.state === 'blocked' ? menuOf(await hc.screenTail(v.s, v.a, SCREEN_LINES)) : null;
+    const k = key(v.s, v.a);
     if (!menu || menu.key !== v.k) {
-      log(`-> ${v.s}/${v.a}: click on ${message} not pressed: ${menu ? `the dialog changed (card ${v.k}, screen ${menu.key})` : `nothing waits (status ${status?.state || 'none'})`}`);
-      if (menu) later(v.s, v.a, 'dialog', () => postBlocked(v.s, v.a, { ...record, status }));
-      return answered(shown, menu ? 'It now asks something else; see the new card.' : 'It no longer waits on this.');
+      log(`-> ${v.s}/${v.a}: click on ${message} not pressed: ${menu ? `the dialog changed (card ${v.k}, screen ${menu.key}; width then ${v.c || '?'}, now ${term.cols || '?'})` : `nothing waits (status ${status?.state || 'none'})`}`);
+      if (!menu) return answered(shown, 'It no longer waits on this.');
+      // The card in your hand becomes what the screen asks now, to tap again. Never "see the
+      // new card": a new card can be held back as already posted, and then nothing is left
+      // to answer while your messages wait on the dialog.
+      const now = dialogOf(status, await hc.screenTail(v.s, v.a, SCREEN_LINES));
+      if (!now.menu) return answered(shown, 'It no longer waits on this.');
+      if (openCard.get(k) && openCard.get(k).message !== message) await closeCard(k, 'It moved on; see the next card.');
+      postedDialog.set(k, dialogName(now, status));
+      remember(message, now);
+      openCard.set(k, { message, dialog: now });
+      return { ...toast('warning', 'It changed before your tap, so nothing was pressed. The card shows it now: tap again.'), card: { kind: 'dialog', dialog: now, value: dialogValue(v.s, v.a, now, term.cols) } };
     }
-    const k = key(v.s, v.a);
     if (openCard.get(k)?.message === message) openCard.delete(k);
     let picked;
     if (v.pick === 'tab' && shown.menu?.multi) {
-      // the boxes the card shows, made so on the screen: each one that differs is pressed
-      const changed = shown.menu.options.filter((o) => o.checked !== null && o.checked !== menu.options.find((m) => m.n === o.n)?.checked);
+      // the boxes as ticked on the card (sent with Next by a form, or kept per tap), made
+      // so on the screen: each one that differs is pressed
+      const wanted = ticks ? { ...shown.menu, options: shown.menu.options.map((o) => (o.checked === null ? o : { ...o, checked: Boolean(ticks[o.n]) })) } : shown.menu;
+      const changed = wanted.options.filter((o) => o.checked !== null && o.checked !== menu.options.find((m) => m.n === o.n)?.checked);
       for (const o of changed) {
         await hc.keys(v.s, v.a, [String(o.n)]);
         await sleep(BOX_GAP_MS);
       }
       await hc.keys(v.s, v.a, ['tab']);
-      const ticked = shown.menu.options.filter((o) => o.checked).map((o) => o.label);
+      const ticked = wanted.options.filter((o) => o.checked).map((o) => o.label);
       picked = ticked.length ? ticked.join(', ') : 'nothing ticked';
     } else if (v.pick === 'esc' || v.pick === 'tab') {
       await hc.keys(v.s, v.a, [v.pick]);
@@ -738,9 +762,16 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       if (next.menu && (next.menu.key === v.k || claimDialog(k, next, nextStatus))) {
         remember(message, next);
         openCard.set(k, { message, dialog: next });
-        return { ...toast('info', `✔ ${picked}`), card: { kind: 'dialog', dialog: next, value: dialogValue(v.s, v.a, next) } };
+        return { ...toast('info', `✔ ${picked}`), card: { kind: 'dialog', dialog: next, value: dialogValue(v.s, v.a, next, term.cols) } };
+      }
+      // its card is out already, unless that card was closed: then this one shows it
+      if (next.menu && openCard.has(k)) return answered(shown, `✔ ${picked}`);
+      if (next.menu) {
+        postedDialog.set(k, dialogName(next, nextStatus));
+        remember(message, next);
+        openCard.set(k, { message, dialog: next });
+        return { ...toast('info', `✔ ${picked}`), card: { kind: 'dialog', dialog: next, value: dialogValue(v.s, v.a, next, term.cols) } };
       }
-      if (next.menu) return answered(shown, `✔ ${picked}`); // its card is out already
       // still waiting, on something with no menu: hc sends no new turn for it, so post it
       later(v.s, v.a, 'dialog', () => postBlocked(v.s, v.a, { ...record, status: nextStatus }));
     }
@@ -939,9 +970,16 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
         log(`-> ${session}/${address}: answered ${text.slice(0, 80)}`);
         await markWorking(key(session, address), message);
       } else {
-        hold(key(session, address), { where, message, session, address, text });
+        const k = key(session, address);
+        hold(k, { where, message, session, address, text });
         log(`-> ${session}/${address}: held until its dialog is answered: ${text.slice(0, 80)}`);
-        await chat.reply(where, 'It asks something first (the card above). Your message goes in once that is answered.');
+        // "the card above" must be there: with a menu and no open card, post it now
+        const status = (await hc.getTerminal(session, address).catch(() => record))?.status;
+        if (menu && !openCard.has(k)) {
+          logWarn(`${session}/${address}: waits on a dialog with no open card; posting it again`);
+          await postBlocked(session, address, { ...record, status }, { again: true }).catch((err) => logError(`dialog card for ${session}/${address} not posted (${err.message})`));
+        }
+        await chat.reply(where, openCard.has(k) || !menu ? 'It asks something first (the card above). Your message goes in once that is answered.' : 'It asks something first, in herdr-app (its card could not be posted here). Your message goes in once that is answered.');
       }
       return;
     }

package/lib/core/menu.mjs

@@ -39,8 +39,10 @@ function topOf(lines, first) {
 
 const MARKS = /[☐☑☒✔✓✗✘■□●○◉◯]/gu;
 
+// Joined with spaces, not line breaks: the same dialog wraps at other places when the
+// terminal is resized (herdr-app opened on a phone), and it is still the same dialog.
 function keyOf(lines, top, last) {
-  const body = lines.slice(top, last + 1).map((l) => l.replace(/❯/g, '').replace(/^(\s*\d{1,2}\.\s+)\[.\]/, '$1').replace(MARKS, '').replace(/\s+/g, ' ').trim()).join('\n');
+  const body = lines.slice(top, last + 1).map((l) => l.replace(/❯/g, '').replace(/^(\s*\d{1,2}\.\s+)\[.\]/, '$1').replace(MARKS, '')).join(' ').replace(/\s+/g, ' ').trim();
   return crypto.createHash('sha1').update(body).digest('hex').slice(0, 12);
 }
 

package/lib/core/pairing.mjs

@@ -0,0 +1,35 @@
+// Pairing: how the bot learns who its owner is without anyone copying an id. `herdrchat
+// setup` shows a short code and keeps it in state.json; the first person who sends that
+// code to the bot becomes its owner. The code lasts PAIR_MINUTES and allows PAIR_TRIES
+// wrong guesses, so nobody can guess their way in.
+import crypto from 'node:crypto';
+
+export const PAIR_MINUTES = 15;
+export const PAIR_TRIES = 5;
+
+// store: {read, write} of state.json
+export function startPairing(store, now = Date.now()) {
+  const code = String(crypto.randomInt(0, 1000000)).padStart(6, '0');
+  const state = store.read();
+  state.pairing = { code, until: now + PAIR_MINUTES * 60 * 1000, tries: 0 };
+  store.write(state);
+  return code;
+}
+
+// 'ok' (the code, used up), 'wrong' (a guess counted), or 'none' (no pairing running)
+export function tryPairing(store, text, now = Date.now()) {
+  const state = store.read();
+  const p = state.pairing;
+  if (!p || now > p.until) return 'none';
+  if (String(text || '').trim() === p.code) {
+    delete state.pairing;
+    store.write(state);
+    return 'ok';
+  }
+  p.tries = (p.tries || 0) + 1;
+  if (p.tries >= PAIR_TRIES) delete state.pairing;
+  store.write(state);
+  return 'wrong';
+}
+
+export const pairingRunning = (store, now = Date.now()) => Boolean(store.read().pairing && now <= store.read().pairing.until);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "herdrchat",
-  "version": "1.3.2",
-  "description": "Chat front-ends for hc: every terminal hc runs, in the chat app you use",
+  "version": "1.4.0",
+  "description": "The chat client for hc (herdr): see and answer every hc terminal from Feishu or Telegram",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zhangxiangliang/herdrchat.git"
@@ -39,5 +39,17 @@
     "@semantic-release/git": "^11.0.1",
     "semantic-release": "^25.0.9",
     "yaml": "^2.9.1"
-  }
+  },
+  "keywords": [
+    "herdr",
+    "hc",
+    "herdr-core",
+    "feishu",
+    "lark",
+    "telegram",
+    "chatops",
+    "claude-code",
+    "agents",
+    "terminal"
+  ]
 }

package/skills/herdrchat/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: herdrchat
 description: >-
-  Set up, run and look after herdrchat, which mirrors every herdr-app (hc) tab into
+  Set up, run and look after herdrchat, the chat client for hc (herdr), which mirrors every herdr-app tab into
   Feishu (a group per tab) or Telegram (a topic per tab): first setup of either app,
   start, stop, status, logs, running it as a service, settings, fixing problems, the
   Feishu developer console and @BotFather. Use for anything about herdrchat or its
@@ -29,7 +29,7 @@ from the package (`config.env.example`, `docs/guide.md`) are in the installed pa
 
 | Command | Do |
 |---|---|
-| `/herdrchat setup` | First ask which chat app (Feishu, Telegram, or both: the second one on its own profile). Telegram: `/herdrchat telegram setup`. Feishu, in this order: create the app, the bot ability and the scopes (`references/feishu.md`); `herdrchat init` and fill `config.env` with the user (App ID, App Secret, `HERDR_SESSIONS`: `ls ~/.local/state/herdr-core` lists the sessions); `herdrchat start` (the console's long-connection check needs it running); events and callbacks; publish a version; the user messages the bot and adds the `FEISHU_OWNER_OPEN_ID` line it answers with; `herdrchat start` again; offer `/herdrchat auth` and `herdrchat install`. |
+| `/herdrchat setup` | First check herdr is there (`command -v hc`): herdrchat is built on herdr and does nothing without it. When it is missing, offer to install it and, on a yes, follow `references/herdr.md` (from herdr's own instructions, read now, each command shown and agreed first). Then ask which chat app (Feishu, Telegram, or both: the second one on its own profile). Telegram: `/herdrchat telegram setup`. Feishu, in this order (with ego-browser the agent clicks the console; without it, offer to install Ego Lite or walk the user through it, `references/feishu.md` "Before anything"): create the app, the bot ability and the scopes; `herdrchat init` and fill `config.env` with the user (App ID, App Secret; `HERDR_SESSIONS` empty means hc's default session, `ls ~/.local/state/herdr-core` lists the sessions); `herdrchat start` (the console's long-connection check needs it running); events and callbacks; publish a version; `herdrchat pair` (in the background: it prints a 6-digit code and waits; the user sends the code to the bot, which writes `FEISHU_OWNER_OPEN_ID` itself and starts again; it also proves the events work); offer `/herdrchat auth` and `herdrchat install`. Never run `herdrchat setup` yourself: it asks questions in a terminal, and this shell has none. It is the same steps for a user without an agent; yours add the Feishu console through ego-browser. When there is no hc session yet, say so and stop until herdr runs one. |
 | `/herdrchat status` | `herdrchat status`; explain each line; on errors, `/herdrchat fix`. |
 | `/herdrchat start`, `/herdrchat stop` | Read `config.env` (its `HERDR_SESSIONS`) in one step, then `herdrchat start` / `stop` in the next; never both at once. With a service installed they go through it. |
 | `/herdrchat install`, `/herdrchat uninstall` | Run it as a service of the system (launchd on macOS, systemd on Linux): it starts at login and comes back after a crash, whatever happens to the hc cores. Recommended once it works. Read the config first; after a node upgrade, install again (`herdrchat status` says so). |
@@ -55,6 +55,8 @@ With no subcommand, run `herdrchat status` and suggest the next step from it.
 
 - `references/feishu.md`: the bot's app in the Feishu developer console, with Ego or as a
   guided walk-through; the scopes this bot uses.
+- `references/herdr.md`: what herdrchat is built on, and installing herdr with the user
+  when hc is missing.
 - `references/telegram.md`: the Telegram bot, from @BotFather to the first topic; what
   it does differently from Feishu.
 - `references/ops.md`: running and checking the bot, its logs and state, the usual

package/skills/herdrchat/references/feishu.md

@@ -6,13 +6,20 @@ that with ego-browser, in the user's own logged-in browser.
 
 ## Before anything
 
-1. **ego-browser.** Run `command -v ego-browser`. When it is there, run
+1. **ego-browser, or the guide.** Only Feishu needs this (Telegram's bot is made in a
+   chat, with no browser). Run `command -v ego-browser`. When it is there, run
    `ego-browser skill` and follow its usage guide. When it is missing, do not fall back
    to another browser; ask the user which they want:
-   - install Ego Lite (https://lite.ego.app/), sign in to Feishu in it, and ask again,
-     so the agent does the clicking; or
-   - a guided walk-through instead (see "Guide mode" below): the user clicks, the agent
-     says what to click.
+   - **Install Ego Lite**, so the agent does the clicking. Use Ego's own instructions,
+     read now at https://lite.ego.app/ (not from memory): say what it installs, and
+     install only on a yes. Then check `command -v ego-browser` again (a new folder may
+     need a new shell), and have the user sign in to Feishu in Ego as an admin of the
+     tenant. If any of it fails or the user stops, take the guide below; do not retry
+     other ways.
+   - **The guide** ("Guide mode" below): the user clicks, the agent says what to click.
+   Either way is the same procedures. When Ego stops working in the middle (signed out,
+   a page that does not match), say so and go on in guide mode from that step: what is
+   done stays done.
 2. **Which profile.** Ask which Ego profile is signed in to Feishu as an admin of the
    tenant that owns the app (`await profiles()` lists them); never guess. Create one task
    space for the whole job with that `profileId`, and close it at the end with
@@ -20,7 +27,9 @@ that with ego-browser, in the user's own logged-in browser.
 3. **Which app.** The app id is `FEISHU_APP_ID` in the profile's `config.env`
    (`~/.config/herdrchat/<profile>/config.env`, or in `HERDRCHAT_HOME`). Read only that
    key; never print, screenshot or paste `FEISHU_APP_SECRET`, and never write a real app
-   id, open_id, chat id or tenant name into a file of this repo.
+   id, open_id, chat id or tenant name into a file of this repo. With Ego too, the agent
+   does not read or reveal the secret on the credentials page: the user copies it into
+   `config.env` themselves (the agent says the file and the line).
 4. **Ask first** before anything outward-facing: publishing a version, applying scopes,
    deleting or deactivating an app. One yes covers one action.
 

package/skills/herdrchat/references/herdr.md

@@ -0,0 +1,33 @@
+# herdr: what herdrchat is built on, and putting it in place
+
+herdrchat mirrors the terminals that **hc** (herdr-core) runs; **herdr-app** is herdr's
+desktop and phone app that shows them in spaces and tabs. Without hc on the machine
+herdrchat does nothing. Check: `command -v hc && hc --version`.
+
+When hc is missing, help the user install it. Do it from herdr's own instructions, read
+now, never from memory or a script kept here: install steps change, and a fixed script
+breaks on another system or version.
+
+## Installing it, with the user
+
+1. **Say what and why.** "herdrchat is built on herdr: it mirrors the terminals that hc
+   runs. hc is not on this machine. Shall I install herdr for you?" Wait for a yes.
+2. **Read the official way, now.** Open https://herdr.dev and follow its install or
+   download instructions for this system (macOS or Linux; say so if it is neither). Use
+   only what herdr's own site or its official releases give. If the page does not say
+   how, stop and tell the user where you looked.
+3. **Show before running.** Give the user the exact command or download, where it comes
+   from, where it installs, and what it changes (a folder, the PATH, a login item).
+   When the instructions pipe a script into a shell, download the script first and read
+   it, then say what it does. Run it only after the user says yes to that command.
+4. **Check it worked.** `hc --version` answers. If hc is not found, the new folder may
+   not be on PATH yet in this shell: say which folder, and how the instructions add it.
+5. **A first session.** `hc ls` (or the instructions' own first step) starts the default
+   session; `ls ~/.local/state/herdr-core` then lists it. herdrchat's `HERDR_SESSIONS`
+   names the sessions to mirror. herdr-app is optional for herdrchat but is how terminals
+   get their space and tab names; offer it when the user wants the desktop app too.
+6. **On a failure, stop.** Show the error as it is and what was tried. Do not try other
+   install ways the user did not agree to, and never run anything with sudo without
+   asking for that command.
+
+Then go back to `/herdrchat setup`.

package/skills/herdrchat/references/ops.md

@@ -79,7 +79,7 @@ your token after `/auth`: never print it.
 
 | You see | Likely cause | Do |
 |---|---|---|
-| nothing posts | bot down, or the owner not set (`FEISHU_OWNER_OPEN_ID`, `TELEGRAM_OWNER_ID`) | `herdrchat status`; the log says "owner not set" |
+| nothing posts | bot down, or the owner not set (`FEISHU_OWNER_OPEN_ID`, `TELEGRAM_OWNER_ID`) | `herdrchat status`; the log says "owner not set": `herdrchat pair` |
 | Telegram: no topic appears | topic mode off | log: "topic mode is off"; BotFather's mini app, the bot, Threaded Mode, then start again |
 | Telegram: `telegram poll: ... 409` | another copy polls the same token | stop it (another machine?), then start once |
 | a button gives error 200340 | the card callback is not set up | `references/feishu.md`: events and card callbacks |

package/skills/herdrchat/references/telegram.md

@@ -19,18 +19,20 @@ Do these in order; the user does the Telegram steps, you check each one.
 2. **The config.** `herdrchat init --chat telegram P` makes the profile's `config.env`
    (private) and prints where it is. Ask the user to paste the token after
    `TELEGRAM_BOT_TOKEN=` themselves (`open -e <file>` opens it), no quotes, no spaces, and
-   fill `HERDR_SESSIONS` with them (`ls ~/.local/state/herdr-core` lists the sessions).
+   leave `HERDR_SESSIONS` empty for hc's default session, or name others
+   (`ls ~/.local/state/herdr-core` lists the sessions).
 3. **Topic mode, checked before the first start.** It is not in BotFather's `/mybots` →
    Bot Settings list; it is in BotFather's mini app (the **Open** button at the bottom
    left of the BotFather chat): pick the bot, turn on Threaded Mode. Check it without
    printing the token: a short `node -e` reads the token from the config, calls
    `https://api.telegram.org/bot<token>/getMe` and prints only `username` and
    `has_topics_enabled`, which must be `true`.
-4. **First start, to learn the owner.** `herdrchat start P`; the user messages the bot
-   anything; it answers with the line to add, `TELEGRAM_OWNER_ID=<digits>`, and where the
-   file is. The user adds it. Until then the bot makes no topic.
-5. **Start again.** Read the config (secrets hidden) in one step, then
-   `herdrchat start P` in the next. One topic per tab appears; Telegram takes about one
+4. **Start, then pair the owner.** Read the config (secrets hidden) in one step, then
+   `herdrchat start P` in the next. Then run `herdrchat pair P` in the background: it
+   prints a 6-digit code and waits. Tell the user the code; they open the bot (tap
+   Start), send it, and the bot writes `TELEGRAM_OWNER_ID` itself and starts again as
+   theirs. Until then the bot makes no topic. No id to copy.
+5. **The topics.** One topic per tab appears; Telegram takes about one
    message a second in a chat, so twenty tabs take twenty seconds. A new topic gets the
    conversation before it (`HERDR_HISTORY`); `/history` in a topic posts it again.
 6. **Make it a service.** Once it works: `herdrchat install P`. It then starts at login
@@ -68,7 +70,7 @@ without muting each topic by hand.
 | Seen | Cause | Do |
 |---|---|---|
 | log: `topic mode is off for @<bot>` | step 3 not done | turn it on in BotFather's mini app, check `has_topics_enabled`, start again |
-| the bot answers "To make you this bot's owner…" | `TELEGRAM_OWNER_ID` empty | step 4 |
+| the bot answers "This bot has no owner yet" | `TELEGRAM_OWNER_ID` empty | step 4: `herdrchat pair P` |
 | `herdrchat start` says it did not reach its chat app | wrong token, or no network | check with getMe (step 3) |
 | log: `telegram poll: ... 409` | another copy polls the same token | `herdrchat stop P`, find the other one (another machine?), start once |
 | log: `too fast, waiting N s` | Telegram's flood limit; the bot waits as told | nothing; it catches up |