vibego 0.2.52__py3-none-any.whl → 1.0.0__py3-none-any.whl

tasks/service.py

@@ -1,4 +1,4 @@
-"""任务持久化与业务逻辑。"""
+"""Persistence and business logic for the task subsystem."""
 from __future__ import annotations
 
 import asyncio
@@ -28,10 +28,10 @@ logger = logging.getLogger(__name__)
 
 
 class TaskService:
-    """封装任务相关的数据库操作。"""
+    """Wrap task-related database operations."""
 
     def __init__(self, db_path: Path, project_slug: str) -> None:
-        """初始化服务实例，绑定数据库路径与项目标识。"""
+        """Initialise the service with the database path and project slug."""
 
         self.db_path = Path(db_path)
         self.project_slug = project_slug
@@ -40,7 +40,7 @@ class TaskService:
         self._valid_statuses = set(TASK_STATUSES)
 
     async def initialize(self) -> None:
-        """确保数据库结构存在，并执行必要的迁移逻辑。"""
+        """Ensure the schema exists and run required migrations."""
 
         if self._initialized:
             return
@@ -58,7 +58,7 @@ class TaskService:
         self._initialized = True
 
     async def _create_tables(self, db: aiosqlite.Connection) -> None:
-        """创建或补全任务相关的全部表结构与索引。"""
+        """Create or augment all tables and indexes for tasks."""
 
         await db.execute(
             """
@@ -191,7 +191,7 @@ class TaskService:
         )
 
     async def _migrate_timezones(self, db: aiosqlite.Connection) -> None:
-        """将遗留的 UTC 字符串转换为上海时区表示。"""
+        """Convert legacy UTC timestamps to their Shanghai equivalents."""
 
         db.row_factory = aiosqlite.Row
         tables: Sequence[tuple[str, str, tuple[str, ...]]] = (
@@ -245,7 +245,7 @@ class TaskService:
             )
 
     async def _migrate_task_ids_to_underscore(self, db: aiosqlite.Connection) -> None:
-        """将历史任务 ID 的连字符/点号改写为下划线格式，保障 Telegram 命令可点击。"""
+        """Rewrite legacy task IDs with underscores so Telegram commands remain clickable."""
 
         db.row_factory = aiosqlite.Row
         async with db.execute(
@@ -265,7 +265,7 @@ class TaskService:
         if not legacy_row:
             return
 
-        logger.info("检测到旧版任务 ID，开始迁移: project=%s", self.project_slug)
+        logger.info("Detected legacy task IDs, starting migration: project=%s", self.project_slug)
         await db.execute("PRAGMA foreign_keys = OFF")
         await db.execute("PRAGMA defer_foreign_keys = ON")
         mapping: Dict[str, str] = {}
@@ -289,27 +289,27 @@ class TaskService:
                     continue
                 if new_id is None:
                     logger.error(
-                        "任务 ID 迁移检测到无法规范化的值: project=%s value=%s",
+                        "Task ID migration encountered a non-normalisable value: project=%s value=%s",
                         self.project_slug,
                         old_id,
                     )
-                    raise ValueError("任务 ID 迁移失败：存在无法规范化的 ID")
+                    raise ValueError("Task ID migration failed: unable to normalise ID")
                 if new_id != old_id and new_id in existing_ids:
                     logger.error(
-                        "任务 ID 迁移检测到潜在冲突: project=%s old=%s new=%s",
+                        "Task ID migration detected a potential conflict: project=%s old=%s new=%s",
                         self.project_slug,
                         old_id,
                         new_id,
                     )
-                    raise ValueError("任务 ID 迁移冲突：目标 ID 已存在")
+                    raise ValueError("Task ID migration conflict: target ID already exists")
                 if new_id in mapping.values() or new_id in mapping:
                     logger.error(
-                        "任务 ID 迁移检测到冲突: project=%s old=%s new=%s",
+                        "Task ID migration detected a conflict: project=%s old=%s new=%s",
                         self.project_slug,
                         old_id,
                         new_id,
                     )
-                    raise ValueError("任务 ID 迁移冲突")
+                    raise ValueError("Task ID migration conflict")
                 mapping[old_id] = new_id
 
             if not mapping:
@@ -338,13 +338,13 @@ class TaskService:
 
         self._write_id_migration_report(mapping)
         logger.info(
-            "任务 ID 迁移完成: project=%s changed=%s",
+            "Task ID migration completed: project=%s changed=%s",
             self.project_slug,
             len(mapping),
         )
 
     async def _archive_legacy_child_tasks(self, db: aiosqlite.Connection) -> None:
-        """归档遗留的子任务，防止其继续出现在任务列表中。"""
+        """Archive legacy child tasks so they stop appearing in listings."""
 
         now = shanghai_now_iso()
         cursor = await db.execute(
@@ -364,15 +364,15 @@ class TaskService:
             changed = 0
         await cursor.close()
         if changed > 0:
-            logger.info("已归档遗留子任务: project=%s count=%s", self.project_slug, changed)
+            logger.info("Archived legacy child tasks: project=%s count=%s", self.project_slug, changed)
 
     async def _drop_child_sequences_table(self, db: aiosqlite.Connection) -> None:
-        """移除已废弃的子任务序列表，避免后续访问错误。"""
+        """Remove the defunct child sequence table to prevent stale lookups."""
 
         await db.execute("DROP TABLE IF EXISTS child_sequences")
 
     async def _verify_status_values(self, db: aiosqlite.Connection) -> None:
-        """校验任务表中的状态值是否符合当前合法枚举。"""
+        """Validate task status values against the allowed enumeration."""
 
         async with db.execute(
             "SELECT DISTINCT status FROM tasks WHERE project_slug = ?",
@@ -382,14 +382,14 @@ class TaskService:
         for (status,) in rows:
             if status is None:
                 logger.error(
-                    "任务状态检查发现 NULL 值: project=%s",
+                    "Task status integrity check found NULL value: project=%s",
                     self.project_slug,
                 )
                 continue
             normalized = self._normalize_status_token(status, context="integrity_check")
             if normalized not in self._valid_statuses:
                 logger.error(
-                    "任务状态检查发现无法识别的值: project=%s value=%s",
+                    "Task status integrity check found unknown value: project=%s value=%s",
                     self.project_slug,
                     status,
                 )
@@ -405,7 +405,7 @@ class TaskService:
         description: Optional[str] = None,
         actor: Optional[str],
     ) -> TaskRecord:
-        """创建顶级任务并写入初始历史记录。"""
+        """Create a root task and capture the initial history entry."""
 
         async with self._lock:
             async with aiosqlite.connect(self.db_path) as db:
@@ -483,7 +483,7 @@ class TaskService:
         include_archived: bool = False,
         exclude_statuses: Optional[Sequence[str]] = None,
     ) -> List[TaskRecord]:
-        """按条件查询任务列表，支持分页与状态过滤。"""
+        """List tasks with optional filters, status exclusions, and pagination."""
 
         query = [
             "SELECT * FROM tasks WHERE project_slug = ?",
@@ -515,7 +515,7 @@ class TaskService:
         page: int,
         page_size: int = DEFAULT_LIMIT,
     ) -> Tuple[List[TaskRecord], int, int]:
-        """按标题或描述模糊搜索任务，并返回结果与分页总数。"""
+        """Search tasks by title or description and return results, pages, and totals."""
 
         if page_size <= 0:
             page_size = DEFAULT_LIMIT
@@ -556,7 +556,7 @@ class TaskService:
         return [self._row_to_task(row, context="search") for row in rows], pages, total
 
     async def get_task(self, task_id: str) -> Optional[TaskRecord]:
-        """根据任务 ID 返回任务详情，不存在时返回 None。"""
+        """Return a task by ID, or ``None`` when it does not exist."""
 
         canonical_task_id = self._canonical_task_id(task_id)
         if not canonical_task_id:
@@ -588,11 +588,11 @@ class TaskService:
         description: Optional[str] = None,
         archived: Optional[bool] = None,
     ) -> TaskRecord:
-        """更新任务字段并记录历史，返回最新任务。"""
+        """Update a task, write history entries, and return the refreshed record."""
 
         canonical_task_id = self._canonical_task_id(task_id)
         if not canonical_task_id:
-            raise ValueError("任务不存在")
+            raise ValueError("Task does not exist")
         task_id = canonical_task_id
         async with self._lock:
             async with aiosqlite.connect(self.db_path) as db:
@@ -602,7 +602,7 @@ class TaskService:
                 row = await self._fetch_task_row(db, task_id)
                 if row is None:
                     await db.execute("ROLLBACK")
-                    raise ValueError("任务不存在")
+                    raise ValueError("Task does not exist")
                 updates = []
                 params: List[object] = []
                 history_items: List[Tuple[str, Optional[str], Optional[str]]] = []
@@ -614,7 +614,7 @@ class TaskService:
                     normalized_status = self._normalize_status_token(status, context="update")
                     if normalized_status != status:
                         logger.warning(
-                            "任务状态入参已自动修正: task_id=%s raw=%s normalized=%s",
+                            "Task status input corrected automatically: task_id=%s raw=%s normalized=%s",
                             task_id,
                             status,
                             normalized_status,
@@ -676,7 +676,7 @@ class TaskService:
                 await db.commit()
         updated = await self.get_task(task_id)
         if updated is None:
-            raise ValueError("任务不存在")
+            raise ValueError("Task does not exist")
         return updated
 
     async def add_note(
@@ -687,11 +687,11 @@ class TaskService:
         content: str,
         actor: Optional[str],
     ) -> TaskNoteRecord:
-        """为任务追加备注，并同步写入历史记录。"""
+        """Append a note to a task and persist a corresponding history entry."""
 
         canonical_task_id = self._canonical_task_id(task_id)
         if not canonical_task_id:
-            raise ValueError("任务不存在")
+            raise ValueError("Task does not exist")
         task_id = canonical_task_id
         now = shanghai_now_iso()
         async with self._lock:
@@ -702,7 +702,7 @@ class TaskService:
                 task_row = await self._fetch_task_row(db, task_id)
                 if task_row is None:
                     await db.execute("ROLLBACK")
-                    raise ValueError("任务不存在")
+                    raise ValueError("Task does not exist")
                 cursor = await db.execute(
                     """
                     INSERT INTO task_notes(task_id, note_type, content, created_at)
@@ -738,7 +738,7 @@ class TaskService:
         )
 
     async def list_notes(self, task_id: str) -> List[TaskNoteRecord]:
-        """列出指定任务的所有备注，按时间升序排列。"""
+        """Return every note for a task ordered by creation time."""
 
         canonical_task_id = self._canonical_task_id(task_id)
         if not canonical_task_id:
@@ -766,7 +766,7 @@ class TaskService:
         ]
 
     async def list_history(self, task_id: str) -> List[TaskHistoryRecord]:
-        """返回任务的历史记录列表。"""
+        """Return the full history list for a task."""
 
         canonical_task_id = self._canonical_task_id(task_id)
         if not canonical_task_id:
@@ -809,11 +809,11 @@ class TaskService:
         payload: Optional[Dict[str, Any]] = None,
         created_at: Optional[str] = None,
     ) -> None:
-        """记录任务相关的动作事件。"""
+        """Record a structured task event."""
 
         canonical_task_id = self._canonical_task_id(task_id)
         if not canonical_task_id:
-            raise ValueError("任务不存在")
+            raise ValueError("Task does not exist")
         task_id = canonical_task_id
 
         event_token = (event_type or "task_action").strip() or "task_action"
@@ -825,7 +825,7 @@ class TaskService:
             try:
                 payload_text = json.dumps(payload, ensure_ascii=False)
             except (TypeError, ValueError) as exc:
-                logger.warning("事件 payload 序列化失败: task_id=%s error=%s", task_id, exc)
+                logger.warning("Failed to serialise event payload: task_id=%s error=%s", task_id, exc)
                 payload_text = None
         async with self._lock:
             async with aiosqlite.connect(self.db_path) as db:
@@ -835,7 +835,7 @@ class TaskService:
                 row = await self._fetch_task_row(db, task_id)
                 if row is None:
                     await db.execute("ROLLBACK")
-                    raise ValueError("任务不存在")
+                    raise ValueError("Task does not exist")
                 await self._insert_history(
                     db,
                     task_id,
@@ -850,7 +850,7 @@ class TaskService:
                 await db.commit()
 
     async def delete_task(self, task_id: str, *, actor: Optional[str]) -> TaskRecord:
-        """通过归档标记实现逻辑删除，并返回最新任务状态。"""
+        """Perform a logical delete by marking the task archived and return the state."""
 
         updated = await self.update_task(task_id, actor=actor, archived=True)
         return updated
@@ -863,7 +863,7 @@ class TaskService:
         page_size: int = DEFAULT_LIMIT,
         exclude_statuses: Optional[Sequence[str]] = None,
     ) -> Tuple[List[TaskRecord], int]:
-        """基于页码拉取任务列表，并返回总页数。"""
+        """Fetch a specific page of tasks and return both the page data and total count."""
 
         total = await self.count_tasks(
             status=status,
@@ -887,7 +887,7 @@ class TaskService:
         include_archived: bool,
         exclude_statuses: Optional[Sequence[str]] = None,
     ) -> int:
-        """统计满足条件的任务数量，用于分页。"""
+        """Count tasks that satisfy the provided filters."""
 
         query = "SELECT COUNT(1) AS c FROM tasks WHERE project_slug = ?"
         params: List[object] = [self.project_slug]
@@ -908,7 +908,7 @@ class TaskService:
         return int(row["c"] if row else 0)
 
     async def backup(self, target_path: Path) -> None:
-        """将当前数据库备份到指定路径。"""
+        """Backup the current database to the target path."""
 
         target_path = target_path.expanduser()
         target_path.parent.mkdir(parents=True, exist_ok=True)
@@ -921,7 +921,7 @@ class TaskService:
 
     @staticmethod
     def _convert_task_id_token(value: Optional[str]) -> Optional[str]:
-        """统一任务 ID 的分隔符，兼容历史格式。"""
+        """Normalise task ID separators to remain compatible with legacy formats."""
 
         if value is None:
             return None
@@ -930,14 +930,14 @@ class TaskService:
         if token.startswith("TASK"):
             suffix = token[4:]
             if suffix and not suffix.startswith("_"):
-                # 旧格式 TASK0001/TASK0001_1 需要补下划线
+                # Legacy formats like TASK0001/TASK0001_1 require an underscore.
                 token = f"TASK_{suffix}"
             else:
                 token = f"TASK{suffix}"
         return token
 
     def _canonical_task_id(self, value: Optional[str]) -> Optional[str]:
-        """将外部传入的任务 ID 规范化为统一格式。"""
+        """Normalise externally provided task IDs into the canonical format."""
 
         if value is None:
             return None
@@ -948,7 +948,7 @@ class TaskService:
         return self._convert_task_id_token(token)
 
     def _write_id_migration_report(self, mapping: Dict[str, str]) -> None:
-        """将任务 ID 迁移结果记录为 JSON 报告，便于排查。"""
+        """Write a JSON report describing task ID migration results."""
 
         if not mapping:
             return
@@ -969,13 +969,13 @@ class TaskService:
             report_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2))
         except Exception as exc:
             logger.warning(
-                "写入任务 ID 迁移报告失败: project=%s error=%s",
+                "Failed to write task ID migration report: project=%s error=%s",
                 self.project_slug,
                 exc,
             )
 
     async def _fetch_task_row(self, db: aiosqlite.Connection, task_id: str):
-        """从数据库查询指定任务的原始行。"""
+        """Fetch the raw task row from the database."""
 
         canonical_task_id = self._canonical_task_id(task_id)
         if not canonical_task_id:
@@ -988,7 +988,7 @@ class TaskService:
             return await cursor.fetchone()
 
     async def _next_root_sequence(self, db: aiosqlite.Connection) -> int:
-        """自增并返回 root 任务序列号。"""
+        """Increment and return the next root task sequence."""
 
         async with db.execute(
             "SELECT last_root FROM task_sequences WHERE project_slug = ?",
@@ -1022,7 +1022,7 @@ class TaskService:
         payload: Optional[str] = None,
         created_at: Optional[str] = None,
     ) -> None:
-        """写入任务历史记录，自动补齐时间戳。"""
+        """Insert a task history entry while filling timestamps automatically."""
 
         normalized = ensure_shanghai_iso(created_at) if created_at else None
         timestamp = normalized or shanghai_now_iso()
@@ -1044,16 +1044,16 @@ class TaskService:
         )
 
     def _normalize_status_token(self, value: Optional[str], *, context: str) -> str:
-        """将状态字符串标准化，兼容遗留 design 并记录异常数据。"""
+        """Normalise status strings, providing compatibility with legacy aliases."""
 
         if not value:
-            logger.warning("检测到空任务状态，已回退默认: context=%s", context)
+            logger.warning("Encountered empty task status; falling back to default: context=%s", context)
             return TASK_STATUSES[0]
         token = str(value).strip().lower()
         mapped = STATUS_ALIASES.get(token, token)
         if mapped not in self._valid_statuses:
             logger.warning(
-                "检测到未知任务状态: value=%s mapped=%s context=%s",
+                "Unknown task status detected: value=%s mapped=%s context=%s",
                 value,
                 mapped,
                 context,
@@ -1061,7 +1061,7 @@ class TaskService:
             return mapped
         if mapped != token:
             logger.info(
-                "任务状态已根据别名转换: raw=%s normalized=%s context=%s",
+                "Task status converted via alias: raw=%s normalized=%s context=%s",
                 value,
                 mapped,
                 context,
@@ -1074,7 +1074,7 @@ class TaskService:
         *,
         context: str,
     ) -> TaskRecord:
-        """将 sqlite row 转换为 TaskRecord 实例。"""
+        """Convert a sqlite row into a ``TaskRecord`` instance."""
 
         tags_raw = row["tags"] or "[]"
         try:

vibego-1.0.0.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: vibego
+Version: 1.0.0
+Summary: vibego CLI: tools for bootstrapping and managing the Telegram Master Bot
+Author: DavidChan
+License-Expression: LicenseRef-Proprietary
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: MacOS
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Environment :: Console
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiogram<4.0.0,>=3.0.0
+Requires-Dist: aiohttp-socks>=0.10.0
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: markdown-it-py<4.0.0,>=3.0.0
+Dynamic: license-file
+
+# vibego - vibe coding via Telegram anytime, anywhere
+
+**Drive your terminal AI CLI via Telegram anytime and anywhere (supports Codex / ClaudeCode)**
+
+For the Simplified Chinese version, see [README-zh.md](README-zh.md).
+
+## Features
+
+1. Control your terminal AI CLI through Telegram whenever you need it.
+2. Capture lightweight task management and bug reports directly inside Telegram.
+3. Switch between Codex / ClaudeCode terminal CLIs in one tap from Telegram.
+4. Send commands over the HTTPS channel provided by the Telegram Bot API, protected by end‑to‑end TLS.
+5. Keep runtime logs and state files under `~/.config/vibego/` so sensitive data never leaves the machine.
+
+## Environment Requirements
+
+- Install the core CLI dependencies with Homebrew to keep scripts aligned:
+  ```bash
+  brew install python@3.11 tmux
+  ```
+  The CLI verifies Python >= 3.11 when you run `vibego start` (see `pyproject.toml` `requires-python` and the Python
+  guard in `vibego_cli/main.py`). Validate with `python3 --version` (must show 3.11+) and `tmux -V`.
+- To run the Codex model you also need the Codex CLI:
+  ```bash
+  brew install codex
+  ```
+  `scripts/run_bot.sh` checks for the `codex` executable before the worker launches. Confirm with `codex --version`.
+- The scripts use the `python3` available on your `PATH` and automatically create `~/.config/vibego/runtime/venv` on
+  first launch to install Python dependencies. If you prefer to bootstrap manually:
+  ```bash
+  python3 -m venv ~/.config/vibego/runtime/venv
+  source ~/.config/vibego/runtime/venv/bin/activate
+  ```
+  Set `VIBEGO_RUNTIME_ROOT` if you need a custom runtime location (pipx users typically do not).
+
+## Quick Start
+
+### Create and retrieve a Telegram bot token
+
+Use the official Telegram BotFather guide (<https://core.telegram.org/bots#botfather>):
+
+1. Search for `@BotFather` in the Telegram client and start a chat.
+2. Send `/start`, then `/newbot`, and follow the prompts for bot name and username.
+3. BotFather returns an HTTP API token resembling `123456789:ABC...`; store it safely.
+4. To regenerate or reset the token, send `/token` in the same chat and pick the bot.
+
+### Install and start vibego
+
+Before continuing, make sure Codex / ClaudeCode CLIs are installed and logged in, and that you have a Telegram bot token
+ready.
+
+- Consider merging the contents of [AGENTS-en.md](AGENTS-en.md) into your `$HOME/.codex/AGENTS.md` or
+  `$HOME/.claude/CLAUDE.md`.
+
+```bash
+pipx install vibego  # or pip install --user vibego
+vibego init          # initialise the config directory and persist the Master Bot Token
+vibego start         # start the master service
+```
+
+## Directory Layout
+
+- `bot.py`: aiogram 3 worker that supports multiple model sessions (Codex / ClaudeCode / reserved Gemini).
+- `scripts/run_bot.sh`: one-click bootstrap (builds venv, starts tmux + model CLI + bot).
+- `scripts/stop_bot.sh`: terminates the worker for a project (tmux session + bot process).
+- `scripts/start_tmux_codex.sh`: low-level tmux/CLI launcher invoked by `run_bot.sh`, forces UTF‑8 via `tmux -u`.
+- `scripts/models/`: model configuration modules (`common.sh` / `codex.sh` / `claudecode.sh` / `gemini.sh`).
+- `logs/<model>/<project>/`: runtime logs (`run_bot.log`, `model.log`, `bot.pid`, `current_session.txt`), defaulted to
+  `~/.config/vibego/logs/`.
+    - `model.log` is rotated by `scripts/log_writer.py`, with 20 MB cap per file and 24-hour retention (override via
+      `MODEL_LOG_MAX_BYTES`, `MODEL_LOG_RETENTION_SECONDS`).
+- `.env.example`: configuration template to copy to `.env` and adjust.
+
+## Logs & Directories
+
+```
+~/.config/vibego/logs/
+  └─ codex/
+      └─ mall-backend/
+           ├─ run_bot.log     # output from run_bot.sh
+           ├─ model.log       # model CLI output captured through tmux pipe-pane
+           ├─ bot.pid         # current bot process PID (used by stop_bot.sh)
+           └─ current_session.txt  # pointer to the latest JSONL session
+```
+
+> Starting in 2025, all logs, databases, and state files default to `~/.config/vibego/`. Use
+`./scripts/migrate_runtime.sh` to migrate legacy files created inside the repository back into the runtime directory.
+
+## Model Switching
+
+- Supported model parameters: `codex`, `claudecode`, `gemini` (placeholder).
+- Switch flow: `stop_bot.sh --model <old>` → `run_bot.sh --model <new>`.
+- Each model keeps an isolated configuration in `scripts/models/<model>.sh`; shared logic lives in
+  `scripts/models/common.sh`.
+- `ACTIVE_MODEL` is echoed in `/start` replies and logs, and exported to the environment for `bot.py`.
+
+### Codex
+
+| Variable             | Description                                                                      |
+|----------------------|----------------------------------------------------------------------------------|
+| `CODEX_WORKDIR`      | Codex CLI working directory (defaults to the value in `.env` or repository root) |
+| `CODEX_CMD`          | Launch command, default `codex --dangerously-bypass-...`                         |
+| `CODEX_SESSION_ROOT` | JSONL root directory (default `~/.codex/sessions`)                               |
+| `CODEX_SESSION_GLOB` | JSONL file pattern (default `rollout-*.jsonl`)                                   |
+
+### ClaudeCode
+
+| Variable              | Description                                                  |
+|-----------------------|--------------------------------------------------------------|
+| `CLAUDE_WORKDIR`      | Project directory (defaults to the same value used by Codex) |
+| `CLAUDE_CMD`          | CLI launch command, for example `claude --project <path>`    |
+| `CLAUDE_PROJECT_ROOT` | JSONL root directory (default `~/.claude/projects`)          |
+| `CLAUDE_SESSION_GLOB` | JSONL file pattern (default `*.jsonl`)                       |
+| `CLAUDE_PROJECT_KEY`  | Optional: explicitly set `~/.claude/projects/<key>`          |
+
+### Gemini (placeholder)
+
+- `scripts/models/gemini.sh` currently contains a placeholder command to be expanded once the official CLI is available.
+
+## aiogram Worker Behaviour
+
+- `/start`: returns `chat_id`, `MODE`, and `ACTIVE_MODEL`; logs record `chat_id` and `user_id`.
+- Text messages:
+    1. Pick the `SessionAdapter` based on `ACTIVE_MODEL`, read `current_session.txt`, and search `MODEL_SESSION_ROOT` if
+       necessary.
+    2. Inject the prompt into tmux (send `Esc` to clear modes, `Ctrl+J` for newline, `Enter` to submit).
+    3. Initialise offsets from `SESSION_OFFSETS`; `_deliver_pending_messages()` streams tail updates from the JSONL log.
+    4. During the watcher phase, the bot informs the user the `ACTIVE_MODEL` is processing and pushes the result once
+       ready (Markdown preserved).
+- MODE = A still honours `AGENT_CMD` for direct CLI execution.
+
+## New Scripts
+
+- `run_bot.sh`
+    - `--model <name>`: codex / claudecode / gemini.
+    - `--project <slug>`: directory name for logs/sessions; defaults to a slug derived from the working directory.
+    - `--foreground`: keep the process in the foreground (default: background via `nohup`).
+    - `--no-stop`: skip the pre-launch stop step (defaults to invoking `stop_bot.sh` for idempotency).
+- `stop_bot.sh`
+    - Idempotent stop: issues `tmux kill-session`, terminates the process from `bot.pid`, and clears cached files.
+    - Example: `./scripts/stop_bot.sh --model codex --project mall-backend`.
+
+## Configuration Highlights
+
+### `.env` (master global configuration)
+
+- Location: `~/.config/vibego/.env` (override with `VIBEGO_CONFIG_DIR`).
+- `MASTER_BOT_TOKEN`: token for the master bot; collected by `vibego init` and required for startup.
+- `MASTER_CHAT_ID` / `MASTER_USER_ID`: captured automatically the first time you interact with the master in Telegram to
+  mark authorised admins.
+- `MASTER_WHITELIST`: comma-separated list of chat IDs. Leave empty to allow any chat; latest value always wins if auto
+  updates occur.
+- You can add optional variables for proxies, log level, default model, etc. Scripts fall back to sensible defaults if
+  unspecified.
+
+- Project definitions persist in `~/.config/vibego/config/master.db` (SQLite) with a JSON mirror at
+  `~/.config/vibego/config/projects.json`. For offline edits, use the `config/projects.json.example` template in the
+  repository.
+- The master “⚙️ Project Management” menu can create/edit/delete projects; offline JSON edits are imported at startup
+  and synced to the database.
+- Required fields: `bot_name`, `bot_token`, `project_slug`, `default_model`.
+- Optional fields: `workdir` (project path), `allowed_chat_id` (pre-authorised chat). Leave blank to let the worker
+  capture the first valid chat and persist it to `~/.config/vibego/state/master_state.json`.
+- Other custom fields are currently ignored.
+
+### Automatic Authorisation & State
+
+- If `allowed_chat_id` is empty when the worker starts, the first authorised message writes to `state/state.json` and is
+  applied immediately.
+- Master restarts: call `stop_bot.sh` first, then restore running projects from the saved state.
+
+## Roadmap
+
+- Master bot will poll all project bots and invoke run/stop scripts to orchestrate workers; current version ships the
+  worker layout and logging standard first.
+- Gemini CLI support will be added once an official integration path is available.
+
+## Notes
+
+- `~/.config/vibego/.env` stores sensitive tokens and admin metadata—never commit it.
+- To trim log size, clean up `logs/<model>/<project>/` as needed or adjust script thresholds.
+- If you previously ran an old source checkout, run `./scripts/migrate_runtime.sh` and ensure only `.example` templates
+  remain in the repository to avoid committing databases or logs.
+- The master caches version checks and reminds you once per release; rerun `/projects` or restart the master to force a
+  new check.
+
+## Master Control
+
+- Launch the admin bot with `MASTER_BOT_TOKEN` (running `python master.py`).
+- Master stores the project list in `~/.config/vibego/config/master.db`; use the project management menu or edit
+  `~/.config/vibego/config/projects.json` directly. Key fields:
+    - `bot_name`: Telegram bot username (with or without `@`; CLI adds `@` when displaying).
+    - `bot_token`: Telegram token for the worker.
+    - `default_model`: default model (codex / claudecode / gemini).
+    - `project_slug`: directory/log slug.
+    - `workdir`: project working directory (optional).
+    - `allowed_chat_id`: authorised chat injected into the runtime environment.
+- State snapshot: `~/.config/vibego/state/master_state.json` records the active model and running status for each
+  project. On restart the master calls `stop_bot.sh`, then restores workers according to the state file.
+
+### Management Commands
+
+| Command                     | Description                                                                 |
+|-----------------------------|-----------------------------------------------------------------------------|
+| `/projects`                 | List all projects with their current status and model.                      |
+| `/run <project> [model]`    | Start a project worker; optional `model` overrides the default/current one. |
+| `/stop <project>`           | Stop the project worker.                                                    |
+| `/switch <project> <model>` | Stop the worker and relaunch it with a new model.                           |
+| `/start`                    | Show help and the total number of projects.                                 |
+| `/upgrade`                  | Run `pipx upgrade vibego && vibego stop && vibego start` to self-upgrade.   |
+
+- `<project>` accepts either the `project_slug` or `@bot_name`. Responses automatically render clickable `@` links.
+
+> The master only interacts with the admin bot. Project bots continue to handle business traffic through the worker (
+`bot.py`) launched by `run_bot.sh`.