charness 3.1.0 → 3.2.0

package/README.md

@@ -1,13 +1,36 @@
 <h1 align="center">Charness</h1>
 
-<p align="center"><em>formerly TelegramCode</em></p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/charness"><img src="https://img.shields.io/npm/v/charness?logo=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/charness"><img src="https://img.shields.io/node/v/charness?logo=node.js" alt="Node.js version"></a>
+  <a href="https://github.com/olosegres/charness/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/charness" alt="license"></a>
+</p>
+
+<h2 align="center">Run multiple Claude Code / OpenCode agents and connect them to your Telegram or Jira.</h2>
 
-<h2 align="center">Telegram bot/group as a terminal for OpenCode, Claude Code — every thread like a terminal tab + scheduling, voice control</h2>
+- **In Telegram** you control your agents through a bot or a group, so it becomes a terminal for OpenCode and Claude Code — every thread is like a terminal tab, plus scheduling and voice control.
+- **In Jira** it starts an agent when you assign a ticket to a special user: the agent reads the description, comments and attachments and does the work according to the ticket's status — like a real employee.
+
+<p align="center">It runs fine on your laptop. But it is called a <b>c</b>loud <b>harness</b> for a reason — put it on a server and your agents keep working while the laptop sleeps.</p>
 
 <p align="center">
   <img src="docs/images/hero-v2.png" alt="Charness — all your agents in Telegram; chat, code, ship; powerful slash commands" width="900" />
 </p>
 
+## What it does
+
+### Common (any surface)
+
+These hold whichever surface you drive it from — the same core serves all of them:
+
+- **Agent backends** — OpenCode (native server API over HTTP+SSE) and Claude Code (three backends — json-stream, per-turn and tmux)
+- **Sleeping agents** — a Claude json-stream topic's process is stopped when idle (or after every turn in per-turn mode) and the next message resumes the same conversation by itself, prompt cache still warm
+- **Several Claude accounts** — keep more than one Claude subscription signed in side by side and choose per topic which one a session runs on (`/accounts`); every account's usage windows are shown next to it. See [Several accounts](#several-accounts-accounts)
+- **Waits out usage limits** — when the agent hits a usage / session limit the bot reads the reset time out of the error (honouring the timezone the provider quotes), waits, then tells the agent to continue by itself and pins the "work resumed" message so a muted topic still notifies you; `/limits` turns waiting off per topic or skips a single resume. With a **fallback chain** (`/limits`: other Claude accounts, OpenCode providers and models, in your order of preference) the limit notice offers «🔁 Switch to …» buttons to move the topic to the next entry with room and continue at once — or the bot does it by itself when you turn switching on; across backends the new agent gets a context bridge with the previous one's last turns
+- **Restart-safe** — agents run as external processes (tmux, `opencode serve`) that the bot re-adopts after a restart instead of killing them; a prompt sent while a session boots is buffered and replayed. See [Restart behaviour](#restart-behaviour)
+
+### Telegram
+
 Charness turns Telegram into a terminal for running agentic CLIs. Open as
 many tabs as you need — even two on the same project for parallel work — and
 drive the agents from your phone or tablet, voice messages included.
@@ -16,13 +39,9 @@ Think **OpenClaw for vibe coding**, driven entirely from Telegram: no complex
 setup, no extra dashboards — direct access to your own **OpenCode** /
 **Claude Code** running on your machine or server.
 
-### Features
-
 - **Simple setup & management** — install the CLI, put your bot token in one `.env`, bind a topic to a folder, and run; everything after is managed from Telegram — no dashboards
 - **Multi-thread / topic** — one topic per directory with your agent; two topics can share one folder for parallel work — run almost unlimited agents in parallel
 - **Two chat surfaces** — forum-group topics and the owner's bot DM, both served at once by default, with tabs on either
-- **Agent backends** — OpenCode (native server API over HTTP+SSE) and Claude Code (three backends — json-stream, per-turn and tmux)
-- **Sleeping agents** — a Claude json-stream topic's process is stopped when idle (or after every turn in per-turn mode) and the next message resumes the same conversation by itself, prompt cache still warm
 - **Raw terminal** — `/terminal` binds a topic to a real `$SHELL` in the project folder
 - **Notifications** — when the agent asks a question, the bot pins that message so even a muted topic notifies you: the pin pierces mute, giving exactly one notification per question (unpinned once you answer)
 - **Scheduled & self-driving runs** — `/schedule` arms cron / one-shot / N-times jobs per topic, and the agent can schedule *itself* via injected MCP tools: nightly reviews, recurring reports, a "finish this tomorrow at 9" hand-off. Each job fires as a fresh session with your prompt; restart-safe, with one catch-up for a run missed while the bot was down
@@ -34,9 +53,8 @@ setup, no extra dashboards — direct access to your own **OpenCode** /
 - **Time-aware prompts** — `/timestamps on` prepends each forwarded prompt's send time (local-offset ISO), so a days-long session knows what "yesterday" or "2 days ago" means; agent-facing only, per topic
 - **Reply context** — reply to a message in a topic and the quoted text is folded into the prompt the agent receives, so it sees what you point at without re-pasting; works for text, voice and files (a photo, a document, an album…), both agents; a reply TO a photo, file or voice note names it, with the path of the bot's saved copy when it has one
 - **Your timezone** — `/timezone Europe/Moscow` once, and schedules fire at your wall-clock time while the agent is told what time it actually is; no server-clock guessing
-- **Waits out usage limits** — when the agent hits a usage / session limit the bot reads the reset time out of the error (honouring the timezone the provider quotes), waits, then tells the agent to continue by itself and pins the "work resumed" message so a muted topic still notifies you; `/limits` turns waiting off per topic or skips a single resume. With a **fallback chain** (`/limits`: other Claude accounts, OpenCode providers and models, in your order of preference) the limit notice offers «🔁 Switch to …» buttons to move the topic to the next entry with room and continue at once — or the bot does it by itself when you turn switching on; across backends the new agent gets a context bridge with the previous one's last turns
 
-## Two surfaces: group topics, bot DM, or both
+#### Two surfaces: group topics, bot DM, or both
 
 The bot serves two Telegram surfaces:
 
@@ -50,289 +68,22 @@ The bot serves two Telegram surfaces:
   the reply grows in place in one message instead of arriving as a flood of
   separate messages.
 
-## Where to run the bot server
-
-The bot runs anywhere the agent CLIs run:
-
-- **Your own working machine** — the simplest start: launch `telegramcode`
-  from your projects parent folder and your laptop/desktop becomes the
-  backend. The catch: agents are only reachable while the machine is on and
-  awake.
-- **A remote server (cloud VPS/VDS or bare metal)** — the more convenient
-  setup: organize your working environment there once (git + your repos,
-  Claude Code / OpenCode, `telegramcode`) and you get an always-on dev box you
-  drive from any device through Telegram — phone, tablet, voice. When picking
-  one, a bare-metal server without virtualization beats a virtualized VPS/VDS:
-  its NVMe drives are usually much faster, which matters once you also build
-  and run a dev server there, not just the agents. Classic terminal access to
-  the very same Claude sessions stays available over SSH — run plain `claude`
-  in the project folder: it reads the same `~/.claude/projects/<cwd-slug>/`
-  session store the bot uses, so a session started in a Telegram thread can
-  be picked up in the terminal and vice versa.
-
-## Quick Start
-
-Five steps: install the CLI, create a bot, (optionally) set up a group, launch
-from your projects folder, bind a topic to an agent.
+## Quick start
 
-> **[manual]** tags a step you must do by hand in the Telegram app — an agent
-> running on the host can't do it for you. Everything unmarked is a host-side
-> command (or file edit) that can be automated.
+1. `npm install -g charness` (needs Node ≥ 22.12).
+2. Put your bot token (from [@BotFather](https://t.me/BotFather)) into `~/.config/charness/.env` as
+   `TELEGRAM_BOT_TOKEN=…`.
+3. Run `charness` from the folder that holds your projects: `cd ~/projects && charness`.
+4. In your Telegram group (or the bot's DM): `/bind <subfolder>` in a topic, then `/claude` or `/opencode` and
+   talk to the agent — text or voice.
 
-### 1. Install the CLI
+Full setup — Telegram, Jira, environment, updating: [SETUP.md](SETUP.md)
 
-```bash
-npm install -g charness      # needs Node ≥ 22.12
-```
-
-This registers the `telegramcode` command (it keeps the project's former name;
-`charness` works too). Coming from the old `telegramcode` npm package (2.x)?
-Run `npm uninstall -g telegramcode` first: both install the same commands. The
-config, `DATA_DIR` and sessions carry over as they are.
-
-Prefer the whole bot in a container, isolated from the host? Use
-[Run with Docker](#run-with-docker) instead — the bot and group steps are the
-same. To hack on the bot itself, see [Run from source](#run-from-source).
-
-### 2. Create the bot
-
-**[manual]** In Telegram, with @BotFather:
-
-1. Message [@BotFather](https://t.me/BotFather), send `/newbot`, follow prompts.
-2. Save the token (`123456789:ABCdef...`).
-3. **Disable privacy mode** — same chat: `/setprivacy` → pick this bot →
-   `Disable`. Without this the bot only sees `/commands`, not free-form text.
-
-<p><img src="docs/images/01-botfather.png" width="360" alt="@BotFather: /newbot to get the token, then /setprivacy → this bot → Disable" /></p>
-
-Put the token where the bot reads it — the global config `.env`:
-
-```bash
-mkdir -p ~/.config/telegramcode
-$EDITOR ~/.config/telegramcode/.env
-```
+## Reference
 
-```dotenv
-# ~/.config/telegramcode/.env — the one place your keys live
-TELEGRAM_BOT_TOKEN=123456789:ABCdef...
-# GROQ_API_KEY=...     # optional: free voice transcription
-# OWNER_USER_ID=...    # set to drive the bot from its DM (step 3)
-```
-
-All keys the bot needs live in this one file — the bot token and the optional
-`GROQ_API_KEY` for voice sit side by side, no separate stores. (Agent
-provider auth is the exception, and lives inside the agents themselves:
-`claude login` for Claude, `/connect` or OpenCode's own config for OpenCode —
-see [Environment Variables](#environment-variables).) The wrapper loads env
-from two locations, in order — a global base and an optional per-project
-override:
-
-1. `~/.config/telegramcode/.env` — base, set once, used everywhere.
-2. `$PWD/.env` — per-project tweaks (last write wins).
-
-The full annotated template is `.env.example` (shipped with the package and in
-the repo).
-
-### 3. Set up a group (optional) or DM
-
-The bot serves a **forum supergroup**, the **owner's private chat (DM)**, or
-both at once (`CHAT_MODE`, default `both`). The group is the nicest UX — a
-visible topic list, per-topic names/icons, quick agent switching — but it is
-**optional**: with `OWNER_USER_ID` set you can run entirely from the bot's DM.
-
-**To use a group (recommended)** — **[manual]**, all in the Telegram client:
-
-1. In a Telegram client: `New Group` → name it → add the bot.
-2. Open group settings → enable **Topics** (Forum mode).
-3. Promote the bot to admin with these rights:
-   - `Manage Topics` (required — bind/create threads)
-   - `Delete Messages` (for `/clear_messages`)
-   - `Pin Messages` (per-thread status banner + question alerts; `/doctor`
-     warns if missing, but the bot still runs without it)
-4. **Remove the bot from the group and add it again.** Telegram caches the
-   privacy-mode flag on join; without re-adding, the bot keeps private-mode and
-   ignores free-form messages (see
-   [Troubleshooting → Bot doesn't see text](#bot-doesnt-see-text)).
-
-<p>
-  <img src="docs/images/02-enable-topics.png" width="360" alt="Group settings → Topics toggle enabled (Forum mode)" />
-  <img src="docs/images/03-promote-admin.png" width="360" alt="Bot admin rights: Manage Topics, Delete Messages, Pin Messages ticked" />
-</p>
-
-The group **id is automatic** — leave `ALLOWED_GROUP_ID` empty and the bot
-auto-pairs with the first forum supergroup an admin talks to it from (the
-`-100…` id is saved to `state.json`; re-point later with `/pair`). To pin a
-specific id by hand, set `ALLOWED_GROUP_ID` to the numeric value (a group
-**name** is not accepted) — that also disables auto-pairing. **Access control:**
-whoever is a creator/administrator of that group may drive the bot — there is no
-separate allow-list.
-
-**To use the DM instead (or as well):** **[manual]** send `/start` to
-[@userinfobot](https://t.me/userinfobot) for your numeric user id, then add it
-(host-side) to the same `.env`:
+### Commands (Telegram)
 
-```dotenv
-OWNER_USER_ID=987654321
-```
-
-With the default `CHAT_MODE=both`, an unset `OWNER_USER_ID` just leaves the DM
-surface inert (group-only); set it and the DM lights up alongside the group. Use
-`CHAT_MODE=dm` to skip the group entirely.
-
-### 4. Launch from your projects folder
-
-```bash
-cd ~/projects && telegramcode
-```
-
-That `$PWD` — the parent folder holding your repositories — is the folder the
-bot works in; each topic binds to a subfolder under it. There's nothing else to
-configure for it. A single-instance lockfile (`$DATA_DIR/instance.lock`) stops a
-second bot starting under the same user; stale locks (after `kill -9`) are
-reclaimed automatically.
-
-### 5. Bind a topic and talk to an agent
-
-This step is **[manual]** — it all happens inside the Telegram app.
-
-**In the group:**
-
-1. Open the group; in the General topic send `/ls` — the bot lists subfolders
-   under the work root.
-2. Create a topic (the `+` button).
-3. In the new topic: `/bind <subdir>` (auto-bound if the topic name matches a
-   subdir).
-4. `/claude` or `/opencode` → talk to the agent (text or voice).
-
-<p><img src="docs/images/04-bind-and-run.png" width="360" alt="A topic bound with /bind, /claude started, and the agent replying" /></p>
-
-**In the DM:** the same commands, one thread per agent — `/ls`,
-`/bind <subdir>`, then `/claude` or `/opencode`.
-
-Then: `/quit` ends the session; bare `/bind` inspects/reconfigures the binding;
-`/clear_messages` deletes the topic's bot messages.
-
-> **Continue the same session from a terminal.** No wrapper needed: run
-> `claude --dangerously-skip-permissions` in the project folder. It is the same
-> binary and the same `~/.claude/projects/<cwd-slug>/` session store the bot
-> uses, so a thread started in Telegram can be picked up with `claude --resume`
-> and vice versa.
-
-### Run with Docker
-
-The whole bot runs in one container: the bot itself, tmux, every agent it starts (Claude Code in any backend,
-`/terminal`, OpenCode and its server) and the bot's MCP server. Everything works as on a host; the host only
-lends the container the folders it mounts, so the bot and its agents see nothing else of the machine.
-
-```
-host                                        container telegramcode-<instance>
-your instance env file (tokens)   ── ro ──▶  the bot (hot mode) + a restart loop
-DATA_DIR, WORK_ROOT               ──────▶    tmux, the agents, OpenCode, the bot MCP
-a clone of this repository        ──────▶    /opt/telegramcode
-the agents' home folder           ──────▶    /home/telegramcode: their Claude / OpenCode
-                                              login, sessions and CLI installs
-```
-
-1. **Image and checkout.** Clone the repository for the container (a full clone of its own, not a worktree and
-   not the checkout a host instance runs from) and build the image from it:
-
-   ```bash
-   git clone https://github.com/olosegres/charness /srv/telegramcode/checkout
-   cd /srv/telegramcode/checkout && docker build -t telegramcode -f docker/Dockerfile .
-   ```
-
-   The image holds only system tools (tmux, git, ffmpeg, ripgrep, …) and the yarn the checkout's `package.json`
-   names (build from the checkout's root, which is how the build reads it; rebuild after a yarn bump so no
-   container has to download it). On first start the container installs the checkout's dependencies for the
-   image and builds it; the bot installs Claude Code and OpenCode into the agents' home.
-2. **Instance env file**, as for a host install (`TELEGRAM_BOT_TOKEN`, `DATA_DIR`, `WORK_ROOT`, …). It stays on
-   the host and is mounted read-only. Every host path it names (`DATA_DIR`, `WORK_ROOT`, `TMUX_TMPDIR`, …) is
-   mounted at the SAME path, so `state.json`, sessions and file paths stay valid inside and an instance can move
-   between host and container unchanged.
-3. **Run** (or use `examples/docker-compose.yml`):
-
-   ```bash
-   docker run -d --name telegramcode-main --hostname telegramcode-main \
-     --restart unless-stopped --stop-timeout 60 \
-     -v /srv/telegramcode/checkout:/opt/telegramcode \
-     -v /srv/telegramcode/home:/home/telegramcode \
-     -v /srv/telegramcode/data:/srv/telegramcode/data \
-     -v /srv/projects:/srv/projects \
-     -v /srv/telegramcode/instance.env:/srv/telegramcode/instance.env:ro \
-     -e ENV_FILE=/srv/telegramcode/instance.env \
-     telegramcode
-   ```
-
-   No port is published: Telegram is long polling, and the bot's MCP server and the OpenCode server listen on the
-   container's own loopback. Keep the `--hostname` fixed and unique per instance: the instance lock tells its own
-   restarted container from another machine by it.
-4. **Log the agents in once**, with the account the agents should use (a separate one is best):
-   `docker exec -it telegramcode-main claude`, then `/login` (or `/login` in a topic). OpenCode: `/connect` in a
-   topic, or `docker exec -it telegramcode-main opencode auth login`. Never copy your own `~/.claude` login in:
-   a second holder of its refresh token can log the first one out. For git, put a `.gitconfig` and an SSH key of
-   their own into the agents' home.
-
-Running it:
-
-- **Restart the bot only** (agents keep running and are adopted): `docker exec telegramcode-main
-  telegramcode-restart-bot`. A crashed bot is restarted by the container after 20 s.
-- **Update the bot**: `docker exec telegramcode-main /opt/telegramcode/scripts/self-update.sh` (by hand or from
-  a timer on the host); hot mode picks the change up. A change to `src/cli.ts`, `src/cli/hot.ts` or `nodemon.json`
-  needs the bot restart above. **Update Claude Code / OpenCode**: they update themselves in the agents' home, or
-  `docker exec telegramcode-main npm install -g @anthropic-ai/claude-code` / `… opencode-ai`.
-- **A container restart is a reboot**: every agent process ends; each conversation resumes with its next message.
-- **Rootless Docker** (recommended): the container's root is your user, so everything written on the mounts is
-  yours. **Rootful Docker**: add `--user "$(id -u):$(id -g)"` and give that user the agents' home.
-- **Moving a host instance in**: stop it first (the lock refuses a lock written on another host), mount its
-  folders at their paths, and copy its conversations' folders from `~/.claude/projects/` into the agents' home
-  `.claude/projects/` — without them each conversation starts a fresh session on its next message.
-- **What the agents can read**: everything mounted, the instance env file with its tokens, `DATA_DIR` and the
-  checkout included. The container keeps the rest of the host out of reach; running the agents as a second user
-  inside the container would close that gap later.
-
-### Run from source
-
-To hack on the bot itself:
-
-```bash
-git clone https://github.com/olosegres/charness && cd charness
-yarn install && yarn build
-npm install -g .            # registers the `telegramcode` (and `charness`) command
-```
-
-Shortcut: `yarn install-link` runs `yarn install && yarn build && npm link` in
-one shot — `npm link` symlinks the global `telegramcode` to this folder, so
-later rebuilds (`yarn build`) are picked up without re-installing. Config and
-launch are identical to steps 2–5 above.
-
-## Required files structure
-
-Launch `telegramcode` from the parent folder that holds your project repos —
-that `$PWD` is the work root, and every topic binds to a subfolder under it:
-
-```
-$PWD=/home/user/src                     ← run the bot here ($PWD = work root)
-├── projectA/         ← Topic "projectA"        (claude)
-├── projectB/         ← Topic "projB-frontend"  (claude)
-│                     ← Topic "projB-backend"   (opencode)   ← one folder, two topics
-│                     ← Topic "projB-refactor"  (claude)
-└── projectC/         ← Topic "projectC"         (opencode)
-
-Telegram forum supergroup
-├── Bot is admin with can_manage_topics + can_delete_messages + can_pin_messages
-└── Routes each topic by (chatId, threadId) → remembered in state.json
-```
-
-**What the bot remembers (`state.json`).** So a restart is seamless, the bot
-saves which topic is bound to which folder, each topic's live agent session (to
-re-attach it after a reboot), your per-topic preferences (agent, model,
-reasoning effort, language, display verbosity), scheduled prompts, and the
-paired group id. This file lives in `DATA_DIR` (default `~/.telegramCode`) and
-is written safely, so a crash can't corrupt it.
-
-## Commands
-
-### In any topic
+#### In any topic
 
 Most commands work in any topic; a binding (`/bind`) is required only to
 actually start an agent or terminal in the folder.
@@ -340,12 +91,12 @@ actually start an agent or terminal in the folder.
 | Command | Description |
 |---|---|
 | `/claude`, `/opencode`, `/oc` | Start agent in this topic's bound folder |
-| `/terminal` | Open a raw `$SHELL` in the bound folder — see [Raw terminal](#raw-terminal-terminal) |
+| `/terminal` | Open a raw `$SHELL` in the bound folder — see [Raw terminal](#raw-terminal-terminal-telegram) |
 | `/claude_mode` | Switch this topic's Claude backend (json-stream ⇄ per-turn ⇄ tmux-scrape); bare shows a picker — see [Claude Code backends](#claude-code-backends-claude_mode) |
 | `/model` | Switch model through a two-level picker: providers, then that provider's models (10 per page). On OpenCode the first row is 🕘 Recently used — a flat list of the models picked before, across providers (bot-wide, most recent first, up to 10), one tap to switch; it appears once something has been picked. Each provider row has a 🙈 to hide it from the picker (bot-wide, persisted; 👁 brings it back) — `/model <provider/model>` still reaches a hidden provider. If OpenCode is waiting on an old provider's retry, the next prompt interrupts that wait and starts with the selected model instead of sitting queued behind it |
 | `/accounts` | Every account the bot works with, on one screen. **Claude accounts** (when you keep several subscriptions signed in): each profile with its email, plan (personal Pro/Max or corporate Team/Enterprise), how many topics use it and its usage windows, ✓ on the active one; tap a profile to switch this topic (a running session is restarted under it, same conversation — at the end of its turn if it is working); in **General** the pick becomes the default for all topics. Per profile: 🔑 signs it in again, 🗑 removes it (after a confirmation; for `default`, which IS `~/.claude`, «remove» signs it out — see below). The usage lines give each window's percentage USED and when it resets as a time from now (`5h 5% 🔄 in 4h · week 20% 🔄 in 5d 8h · Fable 4% 🔄 in 5d 8h`; «🔄 in 2h», «🔄 in 2d 1h», «🔄 in 30m»; Fable only on a plan that has its own weekly window); when the 5h window's reset is unknown the weekly one is shown in its place, and with no reset at all only the percentage. The hint paragraph under the account list says the percentages are used. «➕ Claude account» asks for a name and runs the sign-in. **OpenCode providers**: the connected ones are listed with a «🔌 Disconnect <provider>» button and a 🔑 (connect again) each (the disconnect asks, then removes the stored credentials; a provider OpenCode enables from an environment variable, e.g. `OPENROUTER_API_KEY`, stays active — the reply says so and points at hiding it in `/model`); «➕ OpenCode provider» asks for the provider id and continues with the connect flow (OAuth methods when available, otherwise an API key whose message is deleted from Telegram). What happens when an account hits a usage limit is set in `/limits`. Text forms: `/accounts add <name>`, `/accounts use <name>`, `/accounts login <name>`, `/accounts remove <name>`, `/accounts autoswitch on\|off`. `/account`, `/connect [provider [key]]` and `/disconnect [provider]` still work as hidden aliases (the menu lists only `/accounts`). See [Several accounts](#several-accounts-accounts) |
 | `/effort` | Set reasoning effort (per-thread) via inline buttons. Claude: native `/effort` levels (`low…ultracode`). OpenCode: the current model's variants, applied per-prompt. No env configuration |
-| `/verbosity` | Output-verbosity macro (`minimal\|short\|full`): sets the thinking, tool-results and sub-agent display prefs at once; `/thinking`, `/tool_results`, `/subagent` point-override afterwards. Mixed prefs show as "custom" in the picker. The picker's second row (or `/verbosity stream\|stream_answers\|answers`) sets what the topic SHOWS — "Stream only" (default), "Stream + answers" (the stream plus the agent's pinned answers) or "Answers only" (the pinned answers, no stream; an agent that keeps writing after its final answer is reminded once to send what matters); a switch applies from the next message, and `/status` names the view |
+| `/verbosity` | Output-verbosity macro (`minimal\|short\|full`): sets the thinking, tool-results and sub-agent display prefs at once; `/thinking`, `/tool_results`, `/subagent` point-override afterwards. Mixed prefs show as "custom" in the picker. The picker's second row (or `/verbosity stream\|stream_answers\|answers`) sets what the topic SHOWS — "Stream only" (default), "Stream + answers" (the stream plus the agent's pinned answers) or "Answers only" (the pinned answers, no stream; an agent that keeps writing after its final answer is reminded once to send what matters); the answers are written like for a manager or QA — brief and to the point; a switch applies from the next message, and `/status` names the view |
 | `/thinking` | Chain-of-thought display: `full` keeps the reasoning, `short` collapses to "💭 thought for Ns", `minimal` keeps only the live working cue |
 | `/tool_results` | Completed tool-call output: `full` whole body, `short` capped (15 lines / 1200 chars), `minimal` transient 🔧 status only |
 | `/subagent` | Sub-agent transcript: status-only with a ticking elapsed counter (`minimal`/`short`), or streamed "🤖 ⤷" chunks (`full`) |
@@ -358,8 +109,8 @@ actually start an agent or terminal in the folder.
 | `/c`, `/y`, `/n` | Ctrl+C / "y" / "n" |
 | `/enter`, `/up`, `/down`, `/tab` | tmux key passthrough |
 | `/esc`, `/escape` | Send a raw Escape — interrupt the current turn / dismiss a selector |
-| `/schedule` | Schedule a prompt in free text — the agent parses the time and owns the job; see [Scheduler](#scheduler-schedule) |
-| `/reminders` | Reminders set with buttons only — the bot posts and pins them itself, with no agent involved; works in any topic, bound or not. See [Reminders](#reminders-reminders) |
+| `/schedule` | Schedule a prompt in free text — the agent parses the time and owns the job; see [Scheduler](#scheduler-schedule-telegram) |
+| `/reminders` | Reminders set with buttons only — the bot posts and pins them itself, with no agent involved; works in any topic, bound or not. See [Reminders](#reminders-reminders-telegram) |
 | `/clear_messages` | Delete bot messages in this topic (up to 48h, Telegram limit) |
 | `/clear` | Forwarded to the agent (Claude wipes context; OpenCode plain text) — not a bot command anymore. Also purges the topic's file-intake dir |
 | `/compact` | Compact the agent's context — a real, confirmed compaction on OpenCode and on the default (stream) Claude backend; the tmux Claude backend has the literal command forwarded (its TUI compacts); terminal: not supported |
@@ -369,7 +120,7 @@ actually start an agent or terminal in the folder.
 | `/bind` | Bare: current binding + folder picker, with «leave current dir» (the old `/unbind`) and «create new folder» buttons |
 | `/mcp` | List MCP servers active for this thread |
 
-### Info / ops (work anywhere)
+#### Info / ops (work anywhere)
 
 | Command | Description |
 |---|---|
@@ -387,13 +138,13 @@ actually start an agent or terminal in the folder.
 | `/timezone` | Set the timezone every clock the bot touches speaks in — schedules, agent time context, time renders. `/timezone Europe/Moscow`, `/timezone +04:00`, `/timezone auto` (host zone); bare opens a region → zone picker. Instance-wide, not per chat |
 | `/pair` | Bind this forum supergroup to the bot (re-point auto-pairing) — works from any topic of the target group; a numeric `ALLOWED_GROUP_ID` env locks pairing |
 
-### General-only
+#### General-only
 
 | Command | Description |
 |---|---|
 | `/quit-all`, `/quitall` | End every active agent in every bound topic (also releases their session ids) |
 
-### Natural language
+#### Natural language
 
 In a bound topic you can also type:
 - `claude fix the bug` / `opencode add tests`
@@ -407,7 +158,7 @@ then 15 s) — no need to re-record the voice note.
 `/terminal` is never started from a natural-language phrase — only the
 explicit command opens a shell.
 
-## Claude Code backends (`/claude_mode`)
+### Claude Code backends (`/claude_mode`)
 
 "Claude Code" in a topic is one user-facing choice with three interchangeable
 backends:
@@ -496,7 +247,7 @@ so one account's usage limit does not stop every topic.
   percentage is USED. A reset is shown as a time from
   now (`🔄 in 2d 1h`; the two largest units, minutes only under an hour); an
   unknown 5h reset shows the weekly one, and with no reset at all only the
-  percentage is shown. `telegramcode claude-profiles` prints
+  percentage is shown. `charness claude-profiles` prints
   the same relative form; its `--json` and the MCP tool keep ISO instants. The bot reads the figures with
   each profile's own login every 10 minutes, when `/accounts` or `/limits` opens and when an
   agent asks; a json-stream session's own rate-limit events keep them current
@@ -528,9 +279,9 @@ so one account's usage limit does not stop every topic.
   any other model → the shared weekly window and the session window). It then
   starts the child with `CLAUDE_CONFIG_DIR=<configDir>` (`null` = the default
   profile: set nothing). The same answer from a shell, for a worker without
-  MCP: `telegramcode claude-profiles [--best] [--model <name>] [--json]` —
+  MCP: `charness claude-profiles [--best] [--model <name>] [--json]` —
   `--best` prints just the directory (an empty line for the default), so
-  `CLAUDE_CONFIG_DIR="$(telegramcode claude-profiles --best --model fable)"`
+  `CLAUDE_CONFIG_DIR="$(charness claude-profiles --best --model fable)"`
   works as is; it reads the bot's cache off `DATA_DIR/state.json`.
 
 ### Usage limits and the fallback models (`/limits`)
@@ -592,7 +343,7 @@ instance-wide, ordered list of **fallback models** (where to go), top = preferre
   — the switch notice names the reset time; switch back by hand (`/accounts`,
   `/model`, `/claude`, `/opencode`).
 
-## Scheduler (`/schedule`)
+### Scheduler (`/schedule`) (Telegram)
 
 A topic can have scheduled prompts: at fire time the bot posts the prompt
 into the topic, pins the announcement (pins accumulate as run history),
@@ -612,7 +363,7 @@ with the thread's last-used backend.
   them (an expired one-shot is dropped). Reminders keep running — see
   below. Run history: `DATA_DIR/scheduler-runs.jsonl`.
 
-## Reminders (`/reminders`)
+### Reminders (`/reminders`) (Telegram)
 
 A reminder is the bot's own notification, not a job for an agent: at the due
 time the bot posts your text into the topic and pins it — and the pin is what
@@ -647,7 +398,7 @@ a single catch-up.
 Reminders are yours, not the agent's: the scheduling tools an agent can call
 do not see them, so it can neither list nor delete them.
 
-## Raw terminal (`/terminal`)
+### Raw terminal (`/terminal`) (Telegram)
 
 `/terminal` binds the topic to a real interactive `$SHELL` (in tmux) in the
 bound folder — a third backend alongside the agents, mutually exclusive
@@ -659,7 +410,7 @@ re-adopted. Known v1 limitation: full-screen TUIs (vim, htop, less) render
 messy; normal commands, builds, and logs stream cleanly. The shell comes
 from the `SHELL` env (fallback `/bin/bash`).
 
-## File intake
+### File intake (Telegram)
 
 Send a file to a bound topic with an active agent and the bot hands it to
 the agent:
@@ -675,9 +426,9 @@ the agent:
   bare `/clear` purges the topic's intake dir (the agent's context is gone,
   so the files are useless); files older than 30 days are swept daily.
 
-## Observability
+### Observability
 
-- **Output trace** — ON by default for every thread: each incoming update,
+- **Output trace** (Telegram) — ON by default for every thread: each incoming update,
   adapter emit, and outgoing Bot API call (with outcome, incl. 429 details)
   is recorded into hourly buckets `DATA_DIR/output-trace-*.jsonl` (pruned
   after 6h). `/trace off all` turns it off durably; bare `/trace` reports
@@ -686,11 +437,11 @@ the agent:
 - **Console tee** — the bot's stdout/stderr is mirrored to
   `DATA_DIR/bot-console-*.log` (same hourly buckets, same 6h prune), so
   boot logs stay readable post-incident without the operator's terminal.
-- **`/timestamps on`** — prepends each forwarded prompt's send time
+- **`/timestamps on`** (Telegram) — prepends each forwarded prompt's send time
   (local-offset ISO) so a days-long session knows what "yesterday" means.
   Agent-facing only, default off, persisted per topic.
 
-## Timezone
+### Timezone (Telegram)
 
 The bot runs on the host clock, which on a typical server is UTC. `/timezone`
 declares yours ONCE, instance-wide, and every clock the bot touches follows:
@@ -715,219 +466,7 @@ The current zone and its wall clock also show in `/status`. Nothing is stored
 until you set one, so an install that never runs `/timezone` behaves exactly as
 it did before.
 
-## Environment Variables
-
-### Set Before Launch
-
-| Variable | Description |
-|---|---|
-| `TELEGRAM_BOT_TOKEN` | Token from @BotFather |
-
-Start from the parent folder containing your projects: `cd ~/projects && telegramcode`.
-That `$PWD` is the folder the bot works in — nothing else to set for it.
-
-**Access control.** There is no user allow-list. Whoever is a **creator or
-administrator of the served forum group** may talk to the agent — read live from
-Telegram (`getChatAdministrators`) and cached for 1h. Promote someone in the
-group to grant access; demote/remove them to revoke it — the bot subscribes to
-`chat_member` updates, so an admin change invalidates the cache and takes
-effect immediately (the 1h TTL is only the fallback). The bot must be a group
-admin itself (it already needs that to create topics and pin). Anonymous admins
-can't be matched from their messages, so post non-anonymously. The DM surface
-(when enabled) is gated separately: only the configured `OWNER_USER_ID` may
-talk to the bot there.
-
-> **Security model — group admin (or the DM owner) ⇒ shell on the host.** The agents run with
-> permission checks disabled (`--dangerously-skip-permissions` for Claude,
-> auto-approve for OpenCode) and `/terminal` opens a raw `$SHELL` in the bound
-> folder, so anyone who can talk to the bot can execute arbitrary commands as
-> the bot's OS user. Only promote people you would trust with SSH access to
-> that machine, and keep the served group itself private.
-
-### External Optional
-
-| Variable | Default | Description |
-|---|---|---|
-| `ALLOWED_GROUP_ID` | (auto-pair) | Numeric forum supergroup id (`-100…`). Leave empty to auto-pair with the first forum group a group **admin/creator** contacts the bot from (id is saved to `state.json`; re-point with `/pair`). A **name** is not accepted. A numeric value disables auto-pairing |
-| `DATA_DIR` | `~/.telegramCode` | Per-instance state. **Mandatory** if you run two bots on the same host — otherwise both share `state.json` and `mcp.json` and corrupt each other |
-| `CHAT_MODE` | `both` | Which surface(s) this instance serves: `group`, `dm`, or `both` — see [Two surfaces](#two-surfaces-group-topics-bot-dm-or-both) |
-| `OWNER_USER_ID` | — | **Optional.** Numeric Telegram user id of the owner — leave it unset to run group-only (the DM surface stays inert; a group works fully without it). Set it only to enable the owner-DM surface; **required** solely for `CHAT_MODE=dm` |
-| `GROQ_API_KEY` | — | Recommended for voice transcription. Without it, voice messages are not transcribed unless you intentionally configure the OpenAI fallback |
-
-**Localized in 12 languages** — the bot UI (commands, buttons, notices) speaks
-中文, English, Français, ქართული, Deutsch, हिन्दी, 日本語, Português, Русский,
-Español, Українська, Oʻzbekcha. The language is automatic per Telegram chat:
-explicit `/language <locale>` override wins, then the sender's Telegram client
-language, then the last supported Telegram locale seen for that chat, then
-English.
-Supported locales: `en`, `de`, `fr`, `es`, `pt`, `ru`, `zh`, `ja`, `hi`, `uz`,
-`ka`, `uk`. Bare `/language` opens a single-message inline picker with each language
-shown by its own name (endonym), sorted A→Z by English name, and a `🌐 Auto` button
-(all 12 fit at once — no pagination). Tapping a language (or `🌐 Auto`) applies it, then the menu
-disappears and a short confirmation stays in the chosen language;
-`/language auto` returns a DM/group to automatic selection.
-
-Agent provider/auth setup is normally done inside the agents themselves:
-`claude login` for Claude CLI and `/connect <provider-id>` (for example,
-`/connect openrouter`) or OpenCode's own config/plugins for OpenCode. No provider
-API key env var is required by the bot for text sessions. For OpenCode, install
-any third-party provider plugins or authentication resolvers before launch if
-your chosen providers need them.
-
-### Advanced / Not Normally Needed
-
-| Variable | Default | Set only when |
-|---|---|---|
-| `WORK_ROOT` | `$PWD` | You cannot control the process cwd; normal launch uses `cd <projects-parent> && telegramcode` |
-| `OPENCODE_URL` | `http://localhost:4096` | You use a custom OpenCode port or external server; the port must differ per instance |
-| `OPENCODE_USERNAME` | `opencode` | `OPENCODE_PASSWORD` is set for a protected OpenCode server |
-| `OPENCODE_PASSWORD` | — | Connecting to a protected OpenCode server |
-| `OPENCODE_ALLOW_REMOTE` | — | `OPENCODE_URL` intentionally points outside loopback |
-| `OPENCODE_BIN` | (auto) | The `opencode` binary is not on PATH or you use a fork |
-| `CLAUDE_BIN` | (auto) | The `claude` binary is not on PATH due to nvm/asdf/systemd PATH differences |
-| `OPENAI_API_KEY` | — | You intentionally use OpenAI Whisper as the voice fallback instead of Groq |
-| `ANTHROPIC_API_KEY` | — | A custom MCP/OpenCode plugin/auth resolver explicitly reads it; not needed for normal Claude CLI auth. The json-stream Claude backend strips it from the agent's env (subscription billing) |
-| `SHELL` | `/bin/bash` | You want `/terminal` to open a different shell than your login shell (host env var, not set by the bot) |
-| `SCHEDULER_MCP_PORT` | an OS-chosen free loopback port | You need a stable, explicitly chosen port; it must differ from this instance's `OPENCODE_URL` port |
-| `CLAUDE_SCRAPE_DEBUG` | off | You are debugging Claude tmux scraping and need full RAW/FILTERED chunks |
-| `AGENT_IDLE_MINUTES` | `55` | A json-stream Claude topic idle for this long is compacted (when `/compact_on_idle` allows) and its process stopped; the session sleeps and the next message resumes it — shorten it only for a test; a non-positive or non-numeric value keeps the default |
-| `REQUEST_BACKSTOP_MINUTES` | `90` | A request (a Jira hand-over, a message in an answers-only topic) with nothing seen working on it for this long is re-posted to its session — shorten it only for a test; a non-positive or non-numeric value keeps the default |
-| `TMUX_SOCKET_NAME` | — (the default tmux server) | The instance must run its agents on its OWN tmux server (`tmux -L <name>`; any plain name except `default`). Recommended for a second instance on one host: at boot an instance kills every agent session on its server that its own state does not know |
-| `ENV_FILE` | — | Absolute path of the ONLY env file to read — no `~/.config/telegramcode/.env`, no `$PWD/.env`; its values win over the inherited environment. Set it in the launching environment, never inside an env file (the start refuses that). `scripts/run-isolated.sh <env-file>` starts an instance with a clean environment plus this variable |
-| `CONNECTORS` | `telegram` | Experimental: the surfaces this instance serves, as a comma list — see [Jira connector](#jira-connector-experimental). An instance that lists `jira` refuses to start on Node below 22.12 and without `ENV_FILE`, `TMUX_SOCKET_NAME` and `DATA_DIR/jira.json`, and — with Telegram off — with a `TELEGRAM_BOT_TOKEN` or any `ATLASSIAN_*` variable in its environment. Any instance refuses to start on a `DATA_DIR` that holds conversations of a surface it does not serve |
-
-> `WORK_DIR` (1.x) is retired. Use the wrapper from the desired parent folder
-> instead of carrying the old env forward.
-
-## Jira connector (experimental)
-
-The same core can serve **Jira Cloud issues** instead of (or next to) Telegram topics: an issue assigned to
-a dedicated AI account becomes a conversation with an agent, and the agent answers in comments.
-
-```
-a person assigns an issue to the AI account (in a trigger status)
-  → the instance polls Jira as the AI account and opens a request
-  → the agent works in the project's folder; its streamed output never reaches Jira
-  → it answers through the answer_request tool:
-      progress  → a comment, the issue stays with the AI
-      question  → a comment, the issue goes back to the person who handed it over
-      final     → a comment, the issue goes back to that person
-  → an agent that stops answering is reminded; when the reminders give up, a
-    comment says a person has to look, and the issue goes back
-```
-
-- **One issue = one conversation = one agent session**, bound to the folder its project maps to. The agent
-  reads the issue's text as information, never as instructions.
-- **The agent gets the whole issue.** Every request's prompt carries the issue's fields, the full description,
-  its sub-tasks or an epic's children, links and remote links, an attachment list and ALL comments (oldest
-  first, restricted ones marked) — with a trusted group, minus what outsiders wrote (see below). A screenshot
-  or video pasted into the description or a comment shows up as a placeholder where it sat, naming its
-  attachment. Nothing is cut: a comment over 10 000 characters, or any text
-  that would not fit the prompt, is written whole to a file in the conversation's folder under `DATA_DIR/files`
-  and the prompt says where. A later hand-over to the same conversation carries only what changed since the
-  agent's last prompt (new and edited comments, deleted ones named, the rest listed as unchanged); a fresh
-  session, or one whose context was compacted, gets the whole issue again.
-- **Who gets the answer.** Each hand-over is a request from its sender. Two people handing one issue over in
-  turn get two answers, each their own comment; the first closing answer hands the issue back to its sender,
-  the second finds the issue no longer the AI's and leaves the assignee alone. The same person handing over
-  again replaces their earlier open request; the agent answers only what the new hand-over adds (if it
-  already finished the first, a short pointer to that answer).
-- **Budget.** An issue handed over more than `runBudgetPer24h` times in 24 hours is handed back with a notice
-  and opens no request.
-- **Who can steer it.** With `trustedGroup` (see Setup) only the members of ONE Jira group, the AI account and
-  Jira's apps and automations count. A hand-over by anyone else — another person, a service-desk customer —
-  opens no request: one notice on the issue names the group and the issue goes back to that person. Text
-  written or edited by anyone else (a comment, the description, the summary, labels and extra fields, a
-  file's name and content) is replaced in the prompt by a `[withheld: …]` marker, so the agent knows there
-  is something and can ask its requester. Without `trustedGroup` everyone who can edit or comment steers the
-  agent, and the instance logs one line saying so.
-
-### Setup
-
-1. Create a Jira account for the AI (its API token is the instance's only secret) and note its account id.
-2. Recommended: create or choose a Jira group of the people whose words may steer the AI (for example
-   `ai-trusted`), and give the AI account the *Browse users and groups* global permission so that it can read
-   the group. Then the agent reads only the text and files of its members and of Jira's apps and automations,
-   and only their hand-overs start it.
-3. An instance of its own: a `DATA_DIR`, a `WORK_ROOT` with one folder per project, a private tmux server, and
-   an env file that is the ONLY configuration it reads:
-
-   ```bash
-   # /path/to/jira-instance.env
-   CONNECTORS=jira
-   DATA_DIR=/path/to/jira-instance/data
-   WORK_ROOT=/path/to/jira-instance/work
-   TMUX_SOCKET_NAME=jira-instance
-   OPENCODE_URL=http://localhost:4097   # a port of its own — the default 4096 is refused (other instances use it)
-   JIRA_AI_API_TOKEN=...                # referenced by jira.json below, never written there
-   ```
-
-4. `DATA_DIR/jira.json` — the allowlist, the trusted group and the credentials (`${VAR}` expands from the env file; an unknown
-   key is an error):
-
-   ```json
-   {
-     "site": "example.atlassian.net",
-     "email": "ai-account@example.com",
-     "apiToken": "${JIRA_AI_API_TOKEN}",
-     "accountId": "<the AI account's id>",
-     "projects": {
-       "PROJ": { "folder": "proj", "triggerStatuses": ["In Progress"], "extraFields": ["customfield_10042"] }
-     },
-     "trustedGroup": "ai-trusted",
-     "pollIntervalSeconds": 90,
-     "runBudgetPer24h": 5,
-     "model": "opus",
-     "effort": "high"
-   }
-   ```
-
-   `trustedGroup` (optional, but without it everyone who can edit or comment steers the agent) is the group's
-   NAME — one group per instance; a team with several trust circles runs a second instance. The instance
-   resolves it to the group's id at start, so renaming the group while it runs keeps working, and reads its
-   members again whenever its last read is older than 5 minutes: a removed member loses the AI's trust within
-   that time. List only projects where only your team can write, and where no automation acts on text or
-   actions from outside it — an e-mail handler, a portal form, a copy from another project, a rule that
-   hands an issue to the AI when someone outside the team acts: an app's or automation's text and hand-over
-   are trusted, so such a rule brings that outside text, or that person's hand-over, to the agent. Nor list a
-   project where anyone outside the team holds the *Edit all comments* permission: Jira Cloud keeps no history
-   of a comment's edits, so a comment is judged by its author and its LAST editor only — an outsider's edit of a
-   member's comment, followed by a member's own edit, reads as trusted.
-
-   `projects` maps each served project key to its folder under `WORK_ROOT` and the status names in which an
-   assigned issue is a request; the agent loads that folder's project memory (`CLAUDE.md`, `.claude/`, … in it
-   and in every parent) like any Claude Code session, while your user-level Claude setup stays out of its
-   sessions — except that for a folder under HOME that walk reads `~/.claude/CLAUDE.md` back in.
-   `pollIntervalSeconds` is 10–600 (default 90);
-   `runBudgetPer24h` defaults to 5; `model` and `effort` set the sessions' Claude model and reasoning effort
-   (optional; absent → `opus` and `high`, either key overrides only its own default). `extraFields` (optional,
-   none by default) names fields by id (`customfield_…`, or a system one like `duedate`) the agent should see next to the standard
-   ones, shown under their site name; an id the site does not list is logged at start and left out. `agentBinaries` (optional, host runtime) maps a tool name to the absolute path of an executable — for
-   example `{ "ffmpeg": "/opt/tools/ffmpeg" }` — which is checked at start and put on the agents' PATH. `adapter` is `claude-json-stream` (the default — the agent process is stopped when an issue
-   idles) or `claude-per-turn` (stopped after every answer); either way the issue's conversation sleeps between
-   requests and the next request resumes it.
-
-5. Start it with a clean environment, so nothing of the calling shell reaches it:
-
-   ```bash
-   scripts/run-isolated.sh /path/to/jira-instance.env
-   ```
-
-   The start refuses a missing `ENV_FILE`, `TMUX_SOCKET_NAME` or `jira.json`, an `OPENCODE_URL` on the default
-   port, a `TELEGRAM_BOT_TOKEN` or any `ATLASSIAN_*` variable when Telegram is off, a token that belongs to
-   another account, an unknown project or status, a `trustedGroup` the site does not have or the AI account
-   may not read, and a `DATA_DIR` holding another surface's state. An unreachable Jira does not refuse the start —
-   polling backs off and resumes.
-
-The agent sessions of a Jira instance run without the user-level Claude settings, hooks and skills, with the
-bot's MCP server only, without the native question tool, and with an environment reduced to a short allowlist
-— the Jira token is not in the agent's environment. The agent still runs as the instance's OS user and can read
-the instance's env file and `DATA_DIR`, so run the instance under an OS user that holds nothing else, with an AI
-account that sees only the allowlisted projects. **A production Jira account runs only in the Docker container**
-([Run with Docker](#run-with-docker)): there the agent can still read the instance's env file and `DATA_DIR`,
-but nothing of the host outside the container's mounts. Module details: `src/connectors/jira/README.md`.
-
-## Bot-injected agent tools
+### Bot-injected agent tools
 
 The bot injects its own `telegramBot` MCP server into every bot-started session
 — for Claude via a generated `--mcp-config`, for OpenCode via runtime
@@ -939,9 +478,6 @@ agent even when two clients use the same JSON-RPC request id. It exposes:
 
 - `schedule_create` / `schedule_list` / `schedule_cancel` — the agent-side
   scheduling API behind `/schedule`;
-- `jira_get_attachment` — Jira conversations only: saves the original of one attachment of the conversation's
-  own issue (any size) and returns its path, so the agent can read an image or run `ffmpeg` on a video (with a
-  trusted group, only a file uploaded by a trusted account);
 - `compact_conversation` — lets the agent compact its OWN session when you ask it
   to in plain words ("compact our conversation"). It arms the compaction and
   returns immediately; the bot runs the real compaction the moment the current
@@ -992,52 +528,7 @@ Third-party OpenCode MCP servers, including a separate `telegram-mcp`, belong to
 the OpenCode configuration of the Linux user that runs the bot. They are not
 injected by Charness; run `opencode mcp list` as that user to verify them.
 
-## Two instances on one host
-
-Two host instances, or a host instance next to a container: each pair of variables below must differ to avoid
-silent corruption. Two containers need only different tokens, groups, `DATA_DIR`s, container names and hostnames: their
-ports and tmux servers are their own.
-
-| What | Why it must differ |
-|---|---|
-| `TELEGRAM_BOT_TOKEN` | Telegram routes updates to a single long-poller per token; sharing → message loss |
-| `ALLOWED_GROUP_ID` | The bot gates by group id; sharing → cross-instance leakage |
-| `WORK_ROOT` | Each instance manages its subtree; sharing → tmux name collisions |
-| `DATA_DIR` | `state.json` / `mcp.json` / `threads/` per instance; sharing → corrupted JSON |
-| `OPENCODE_URL` port | OpenCode server binds the port; second start fails with `EADDRINUSE` and you'd silently share sessions |
-| `SCHEDULER_MCP_PORT` | Optional stable scheduler-MCP port; if set, it must differ from that instance's `OPENCODE_URL` port |
-| `TMUX_SOCKET_NAME` | Optional, recommended: each instance's boot kills the agent sessions on its tmux server that its own state does not know — on one shared server, the other instance's |
-
-## Updating a deployment (self-update, no root)
-
-`scripts/self-update.sh` refreshes a checkout in place, running as the
-checkout's owning user — no root, no cross-user copying. It is safe to run
-blindly (e.g. from cron):
-
-- fast-forward only: it skips silently when the tree has tracked changes, a
-  merge/rebase is in progress, or local history diverged from the upstream —
-  a dev clone that is ahead of origin is never touched;
-- `yarn install --immutable` runs only when `yarn.lock` / `package.json`
-  changed;
-- a hot-mode instance (`telegramcode hot`) rebuilds and restarts the worker
-  by itself (after a dependency install the script touches `tsconfig.json`
-  so `tsc -w` recompiles with the new modules); a non-hot instance gets
-  `yarn build` plus a restart notice — the script never kills processes;
-- changes to the hot supervisor itself (`src/cli.ts`, `src/cli/hot.ts`,
-  `nodemon.json`) are flagged with a warning: those need a manual
-  `telegramcode hot` restart (nodemon reloads only the worker).
-
-For unattended updates give the deploying user read access to the repo (e.g.
-a read-only GitLab deploy key on a passphrase-less SSH key) and add a cron
-entry:
-
-```cron
-*/10 * * * * /path/to/telegramcode/scripts/self-update.sh >> "$HOME/.local/state/telegramcode/self-update.log" 2>&1
-```
-
-(create the log directory once: `mkdir -p ~/.local/state/telegramcode`).
-
-## Restart behaviour
+### Restart behaviour
 
 Bot restarts are designed to be invisible: agents run in external
 processes (`tmux`, `opencode serve`), so the bot re-adopts them instead
@@ -1102,7 +593,7 @@ thread not found` from a send triggers binding cleanup. Closed topics
 are detected by `TOPIC_CLOSED` errors and surface a friendly message
 asking the user to reopen.
 
-In the Docker container (see [Run with Docker](#run-with-docker)) the same holds for a bot restart
+In the Docker container (see [Run with Docker](SETUP.md#run-with-docker)) the same holds for a bot restart
 inside the container; a restart of the container itself ends every agent process, and each conversation
 resumes with its next message.
 
@@ -1111,9 +602,9 @@ The default `control-group` mode kills tmux and `opencode serve` children,
 which defeats restart/reattach. Process restarts intentionally leave agent
 sessions alive; use `/quit` or `/quit-all` when you want to terminate them.
 
-## Troubleshooting
+### Troubleshooting
 
-### Bot doesn't see text
+#### Bot doesn't see text (Telegram)
 
 You disabled privacy mode in @BotFather **after** adding the bot. The
 flag is cached on join. Fix:
@@ -1124,7 +615,7 @@ flag is cached on join. Fix:
 
 Verify with `/doctor` — the privacy line should report it as disabled.
 
-### `/bind` says "folder not found"
+#### `/bind` says "folder not found" (Telegram)
 
 The folder you launched from doesn't contain a subfolder with that name (or
 it's a symlink pointing outside it). Run `/ls` to see what's available, or fix
@@ -1132,19 +623,19 @@ the host path. Path-traversal attempts (`../`, absolute paths,
 NUL bytes, NFC-vs-NFD mismatches) are rejected by design — see
 `validateSubdir` in `src/validation.ts`.
 
-### "Missing right" / `/clear_messages` does nothing
+#### "Missing right" / `/clear_messages` does nothing (Telegram)
 
 The bot needs admin rights `can_delete_messages` and `can_pin_messages`
 in addition to `can_manage_topics`. Open group settings → admins →
 the bot → tick the missing boxes. `/doctor` shows the exact gap.
 
-### Two instances on the same machine fight each other
+#### Two instances on the same machine fight each other
 
 You forgot to set distinct `DATA_DIR` and `OPENCODE_URL`. The bot logs
 `[startup] DATA_DIR=<path>` on boot — if both instances log the same
-path, fix `.env` and `docker compose down && up -d`.
+path, give each its own `DATA_DIR` and `OPENCODE_URL` port and restart both.
 
-### Claude opens a session picker instead of resuming
+#### Claude opens a session picker instead of resuming
 
 The 1.x adapter invoked `claude --resume` with no UUID and relied on the
 interactive picker, which doesn't survive a non-interactive pty. 2.0
@@ -1154,12 +645,12 @@ anyway, your local claude CLI is older than 2.1.x — upgrade with
 `npm i -g @anthropic-ai/claude-code` (the bot also auto-installs on
 first use, see `src/installManager.ts`).
 
-### OpenCode "address already in use"
+#### OpenCode "address already in use"
 
 Two instances on the same host with the same `OPENCODE_URL`. Pick a
 different port for the second instance (e.g. `4097`).
 
-## FAQ
+### FAQ
 
 **How do I run Claude Code from my phone?**
 Install Charness on your own machine or VPS, create a Telegram bot, and bind a forum topic (or the bot's DM) to a project folder. Start a Claude Code session in that topic and you drive it entirely from Telegram: type prompts, send voice notes, or drop in files, and the agent's output streams back into the same topic. Your phone never runs the agent; it stays on your machine.
@@ -1168,7 +659,7 @@ Install Charness on your own machine or VPS, create a Telegram bot, and bind a f
 Yes. The bot only makes outbound connections to Telegram, so nothing listens for inbound traffic and you never expose a port. OpenCode runs as a local HTTP server that the bot talks to on loopback, and you reach it from anywhere through Telegram.
 
 **How do I run a coding agent on a VPS and drive it from Telegram?**
-Set up your VPS once with git, your repos, the agent CLIs, and `telegramcode`, then launch the bot from your projects folder. You get an always-on dev box you drive from any device: phone, tablet, or voice. Because the agent lives on the server, it keeps working even when your laptop sleeps, and the same sessions are still reachable over plain SSH.
+Set up your VPS once with git, your repos, the agent CLIs, and `charness`, then launch the bot from your projects folder. You get an always-on dev box you drive from any device: phone, tablet, or voice. Because the agent lives on the server, it keeps working even when your laptop sleeps, and the same sessions are still reachable over plain SSH.
 
 **Does my session survive a restart?**
 Yes, both a bot restart and an agent-server restart. State is persisted to disk; on restart the bot re-attaches to the running Claude session in tmux or re-connects to OpenCode, and an in-flight turn is delivered once it is back. A prompt sent during startup is buffered and replayed, never dropped.
@@ -1179,19 +670,22 @@ Yes. Each topic picks its backend independently: OpenCode over its native HTTP+S
 **Can I talk to the agent by voice?**
 Yes. Send a voice message to a topic and it is transcribed with Whisper (via Groq or OpenAI) and forwarded to the agent as a normal prompt, so you can vibe code hands-free from your phone.
 
-## Documentation
+### Documentation
 
+- **[SETUP.md](SETUP.md)** — installing and configuring: Telegram, Jira, environment, updating; Docker as an alternative to npm.
 - **[DEVELOPMENT.md](DEVELOPMENT.md)** — architecture and local development (build, test, hot-reload, Docker dev loop).
 - **[MIGRATION_1_TO_2.md](MIGRATION_1_TO_2.md)** — upgrading a 1.x install to 2.0.
 
-## The story behind it
+### The story behind it
 
 I started running Claude Code on my own machine, and I kept wanting to check on it after I stepped away from the desk. Back then there was no way to reach it from a phone, so I put together a small bot that launched the agent and let me talk to it over Telegram. It ran on my own computer, which had to stay on the whole time.
 
 Then I moved the whole thing onto a server that never sleeps, added OpenCode next to Claude Code, and it grew into what it is now: voice control, file intake, scheduling, a raw terminal, and sessions that survive restarts. These days I run it every day and drive everything from my phone or tablet, no laptop required.
 
+The project was called TelegramCode before it became Charness: its npm package was `telegramcode` up to 2.0.3 and is `charness` since 3.0.0.
+
 Full write-up: [Vibe-coding by voice, from my phone](https://dev.to/olosegres/vibe-coding-by-voice-from-my-phone-claude-code-and-opencode-over-telegram-j75).
 
-## License
+### License
 
 MIT