fix: clarify thread status markers and sanitize docs paths

Author: tonyHu08

README.md

@@ -2,57 +2,105 @@
 
 [English](#english) | [中文](#中文)
 
-## English
-Zero-configuration remote control for Codex (`Desktop App + Relay + local Codex execution`).
-
-Goal: users download the app, complete setup in the wizard, and control Codex from Telegram without command-line steps.
-
-### Monorepo
-- `packages/bridge-core`: execution orchestration, health checks, config, launchd manager.
-- `apps/desktop`: Electron + React desktop app (wizard + advanced settings + menu bar entry).
-- `services/cloud-relay`: Fastify + WebSocket relay service.
-- `src` (legacy): previous bridge implementation kept for compatibility.
-
-### Current capabilities
-- Desktop setup wizard + app home (Current Status / Advanced Settings / Logs & Feedback).
-- Telegram bot pairing via QR code.
-- Bound-thread remote turns with status + final response.
-- Telegram usage query (`/usage`, alias `/limits`).
-- Thread list with live per-thread task state in `/threads`.
-- Approval routing (`/approve` / `/deny`).
-- Menu bar control (status, remote on/off, open settings).
-- i18n support for **English + Chinese** (`en`/`zh`) across desktop UI, tray, and Telegram responses.
-
-### Dev quick start
+## 中文
+
+把 Codex 从“只能坐在电脑前用”，变成“手机 Telegram 随时远程用”。
+
+### 这个项目解决什么痛点
+- 你离开电脑后，Codex 对话无法继续跟进。
+- 你在手机上只能看消息，不能像在 Codex 里那样继续驱动任务。
+- 需要远程审批、查看状态、切换线程时，缺少统一入口。
+
+Codex Bridge Desktop 的目标是：**让你用 Telegram 像远程控制台一样操作本机 Codex**，并尽量保持与 Codex 线程一致。
+
+### 你现在可以做到什么
+- 在 Telegram 中发送文本/图片，转给已绑定的 Codex thread 执行。
+- 在 Telegram 中查看最近线程、绑定线程、查看当前对话快照。
+- 在 Telegram 中处理审批（`/approve` / `/deny`）。
+- 查询 Codex 用量（`/usage` 或 `/limits`）。
+- 使用 macOS 菜单栏快速查看状态、启停远程能力。
+- 使用桌面 App 完成首次引导、机器人配置、日志排查。
+
+## 2-3 分钟上手（普通用户）
+
+### 1) 下载并打开 App
+1. 打开 Releases 页面下载最新版：  
+   `https://github.com/tonyHu08/CodeX_Bridge/releases`
+2. 安装并打开 `Codex Bridge Desktop`。
+3. 保证本机已安装并登录 Codex App。
+
+### 2) 配置 Telegram 机器人
+1. 在 Telegram 打开 `@BotFather`。
+2. 用 `/newbot` 创建机器人，拿到 Bot Token。
+3. 在桌面 App 中粘贴 Token，保存并启用。
+
+### 3) 手机配对
+1. 在桌面 App 点击“开始配对”。
+2. 用 Telegram 打开配对链接（或扫码）。
+3. 配对成功后，机器人会回复已绑定。
+
+### 4) 绑定要操作的 Codex 会话
+1. 在 Telegram 里发送 `/threads`。
+2. 选择线程按钮，或用 `/bind <编号>`、`/bind latest`。
+3. 之后直接发消息即可远程驱动该线程。
+
+### 5) 日常使用
+- 直接发送文本任务（可附图）。
+- 随时用 `/status`、`/current`、`/usage` 查看状态。
+- 需要停止当前任务时用 `/cancel`。
+
+## 常用 Telegram 命令
+- `/threads`：查看最近线程并快速绑定
+- `/bind latest`：绑定最新线程
+- `/bind <index|threadId>`：绑定指定线程
+- `/current`：查看当前绑定线程快照
+- `/detail <index|threadId>`：查看线程详细信息
+- `/usage` / `/limits`：查询 Codex 用量
+- `/status`：查看桥接状态
+- `/cancel`：终止当前运行并清空排队
+- `/unbind`：解绑当前线程
+- `/help`：帮助
+
+## 技术实现（面向开发者）
+
+### Monorepo 结构
+- `apps/desktop`: Electron + React 桌面端（引导、主页、菜单栏）
+- `packages/bridge-core`: 线程编排、审批、状态管理、Codex App Server 客户端
+- `services/cloud-relay`: Relay 服务（可选，自托管场景）
+- `src` (legacy): 历史实现
+
+### 核心机制
+- 使用 `codex app-server`（JSON-RPC）控制本机 thread：
+  - `thread/list`、`thread/read`、`thread/resume`、`turn/start`
+- Telegram 侧做消息接入、命令路由、审批回传。
+- SQLite 持久化绑定、去重和审批状态。
+- macOS 菜单栏常驻，桌面窗口用于配置与诊断。
+
+### 本地开发
 ```bash
-cd /Users/junweihu/clawd/codex-remote-bridge
+cd /path/to/codex-remote-bridge
 npm install
 npm run setup
 npm run dev:relay
 npm run build:desktop
 npm run start:desktop
 ```
 
-### Quality checks
+### 构建校验
 ```bash
 npm run typecheck
 npm run build
 ```
 
-### Key environment variables
-- `HOST` (default `127.0.0.1`)
-- `PORT` (default `8787`)
-- `RELAY_PUBLIC_BASE_URL` (default `http://127.0.0.1:8787`)
+### 关键环境变量
+- `HOST`（默认 `127.0.0.1`）
+- `PORT`（默认 `8787`）
+- `RELAY_PUBLIC_BASE_URL`（默认 `http://127.0.0.1:8787`）
 - `RELAY_BOT_USERNAME`
 - `TELEGRAM_BOT_TOKEN`
-- `BRIDGE_LOCALE` (`zh` or `en`)
-
-### Local data paths
-- `$HOME/.codex-bridge/config.json`
-- `$HOME/.codex-bridge/data/codex_bridge.db`
-- `$HOME/.codex-bridge/logs/agent.log`
+- `BRIDGE_LOCALE`（`zh` 或 `en`）
 
-### Documents
+### 文档
 - [Configuration](./docs/CONFIG.md)
 - [Commands](./docs/COMMANDS.md)
 - [Architecture](./docs/ARCHITECTURE.md)
@@ -61,59 +109,42 @@ npm run build
 - [Privacy](./docs/PRIVACY.md)
 - [Self-hosting](./docs/SELF_HOSTING.md)
 - [Threat model](./docs/THREAT_MODEL.md)
-- [Contributing](./CONTRIBUTING.md)
-- [Security](./SECURITY.md)
-- [Code of Conduct](./CODE_OF_CONDUCT.md)
-- [Open Source Checklist](./OPEN_SOURCE_CHECKLIST.md)
 
 ---
 
-## 中文
-零配置远程控制能力（`桌面 App + Relay + 本地 Codex 执行`）。
+## English
 
-目标体验：用户下载安装后，通过向导完成配对，即可用 Telegram 远程操作 Codex，无需命令行。
+Turn Codex from a desktop-only experience into a Telegram-based remote workflow.
 
-### Monorepo 结构
-- `packages/bridge-core`：执行编排、健康检测、配置与 launchd 管理。
-- `apps/desktop`：Electron + React 桌面端（向导、设置、菜单栏入口）。
-- `services/cloud-relay`：Fastify + WebSocket Relay 服务。
-- `src`（legacy）：历史桥接实现，保留兼容用途。
-
-### 当前能力
-- 桌面端向导 + 应用主页（当前状态 / 高级设置 / 日志与反馈）。
-- Telegram 二维码配对。
-- 绑定线程后的远程执行（状态 + 最终回包）。
-- Telegram 用量查询（`/usage`，兼容 `/limits`）。
-- `/threads` 中展示每个会话的实时任务状态。
-- 审批流转（`/approve` / `/deny`）。
-- 菜单栏控制（状态、远程开关、打开设置）。
-- 国际化：桌面 UI、菜单栏、Telegram 回包支持 **中英文**（`zh`/`en`）。
-
-### 开发快速开始
+### What this project solves
+- You cannot continue Codex tasks when you are away from your computer.
+- You need a mobile control surface for thread operations, status, and approvals.
+- You want a practical remote bridge without changing your existing Codex workflow.
+
+Codex Bridge Desktop lets you control local Codex threads from Telegram, with thread binding, status, approvals, and usage visibility.
+
+### What you can do
+- Send text/image messages from Telegram to a bound Codex thread.
+- List and bind recent threads from Telegram.
+- Handle approvals remotely (`/approve`, `/deny`).
+- Check Codex rate limits (`/usage`, `/limits`).
+- Use macOS tray/menu bar for quick status and remote on/off.
+
+### Quick start (2-3 minutes)
+1. Download the desktop app from Releases:  
+   `https://github.com/tonyHu08/CodeX_Bridge/releases`
+2. Open the app and complete the onboarding wizard.
+3. Create a Telegram bot via `@BotFather` and paste the Bot Token.
+4. Start pairing in the app, then open the pairing link in Telegram.
+5. In Telegram, run `/threads` and bind a thread.
+6. Send your message to start remote Codex execution.
+
+### Development quick start
 ```bash
-cd /Users/junweihu/clawd/codex-remote-bridge
+cd /path/to/codex-remote-bridge
 npm install
 npm run setup
 npm run dev:relay
 npm run build:desktop
 npm run start:desktop
 ```
-
-### 质量检查
-```bash
-npm run typecheck
-npm run build
-```
-
-### 关键环境变量
-- `HOST`（默认 `127.0.0.1`）
-- `PORT`（默认 `8787`）
-- `RELAY_PUBLIC_BASE_URL`（默认 `http://127.0.0.1:8787`）
-- `RELAY_BOT_USERNAME`
-- `TELEGRAM_BOT_TOKEN`
-- `BRIDGE_LOCALE`（`zh` 或 `en`）
-
-### 本地数据路径
-- `$HOME/.codex-bridge/config.json`
-- `$HOME/.codex-bridge/data/codex_bridge.db`
-- `$HOME/.codex-bridge/logs/agent.log`

docs/COMMANDS.md

@@ -12,7 +12,7 @@
 
 ### Session commands
 - `/threads`
-  - Each thread now shows live task state inline (`⏳ running` / `🕒 queued` / `✅ idle`).
+  - Each thread shows bridge task state inline (`⏳ running` / `🕒 queued` / `⚪ unobserved`).
 - `/bind latest`
 - `/bind <threadId|index>`
 - `/usage` (alias: `/limits`)
@@ -41,7 +41,7 @@
 
 ### 会话命令
 - `/threads`
-  - 每个 thread 行内会展示任务状态（`⏳ 运行中` / `🕒 排队中` / `✅ 空闲`）。
+  - 每个 thread 行内会展示桥接任务状态（`⏳ 运行中` / `🕒 排队中` / `⚪ 未观测`）。
 - `/bind latest`
 - `/bind <threadId|编号>`
 - `/usage`（别名：`/limits`）

docs/OPERATIONS.md

@@ -3,7 +3,7 @@
 ## English
 ### Local dev
 ```bash
-cd /Users/junweihu/clawd/codex-remote-bridge
+cd /path/to/codex-remote-bridge
 npm install
 npm run setup
 npm run dev:relay
@@ -26,7 +26,7 @@ npm run dist:desktop
 ## 中文
 ### 本地开发
 ```bash
-cd /Users/junweihu/clawd/codex-remote-bridge
+cd /path/to/codex-remote-bridge
 npm install
 npm run setup
 npm run dev:relay

docs/SELF_HOSTING.md

@@ -5,7 +5,7 @@ You can run your own relay and bot.
 
 ### Start relay
 ```bash
-cd /Users/junweihu/clawd/codex-remote-bridge/services/cloud-relay
+cd /path/to/codex-remote-bridge/services/cloud-relay
 npm install
 npm run dev
 ```
@@ -23,7 +23,7 @@ Set desktop relay URL to your hosted relay endpoint.
 
 ### 启动 relay
 ```bash
-cd /Users/junweihu/clawd/codex-remote-bridge/services/cloud-relay
+cd /path/to/codex-remote-bridge/services/cloud-relay
 npm install
 npm run dev
 ```

packages/bridge-core/src/agent.ts

@@ -92,7 +92,7 @@ interface DisplayThreadsState {
   usingSidebarVisibility: boolean;
 }
 
-type ThreadTaskState = 'running' | 'queued' | 'idle';
+type ThreadTaskState = 'running' | 'queued' | 'unknown';
 
 interface TurnConversationSummary {
   turnId: string;
@@ -463,7 +463,7 @@ function buildThreadButtonTitle(
   taskState: ThreadTaskState,
 ): string {
   const title = truncate(compactText(item.title || localeText(locale, `会话 ${index + 1}`, `Thread ${index + 1}`)), 24);
-  const status = taskState === 'running' ? '⏳' : taskState === 'queued' ? '🕒' : '✅';
+  const status = taskState === 'running' ? '⏳' : taskState === 'queued' ? '🕒' : '⚪';
   return `${isCurrent ? '✅ ' : ''}${status} 🧵 ${title}`;
 }
 
@@ -975,7 +975,7 @@ export class BridgeAgent extends EventEmitter {
     if (this.queuedByThread.has(threadId)) {
       return 'queued';
     }
-    return 'idle';
+    return 'unknown';
   }
 
   private formatThreadTaskStateLabel(taskState: ThreadTaskState): string {
@@ -985,7 +985,7 @@ export class BridgeAgent extends EventEmitter {
     if (taskState === 'queued') {
       return this.t('🕒 排队中', '🕒 Queued');
     }
-    return this.t('✅ 空闲', '✅ Idle');
+    return this.t('⚪ 未观测', '⚪ Unobserved');
   }
 
   async handleIncomingMessage(event: IncomingUserMessageEvent): Promise<void> {
@@ -1616,6 +1616,7 @@ export class BridgeAgent extends EventEmitter {
     if (state.usingSidebarVisibility && state.hiddenCount > 0) {
       lines.push(this.locale === 'en' ? `Filtered sidebar-invisible threads: ${state.hiddenCount}` : `已过滤侧边栏不可见会话: ${state.hiddenCount}`);
     }
+    lines.push(this.t('状态说明：仅⏳/🕒表示桥接中任务；⚪表示当前未观测到桥接任务。', 'Status note: only ⏳/🕒 indicate bridge tasks; ⚪ means no bridge task currently observed.'));
     lines.push('');
     lines.push(this.t('可用: /bind [编号] | /detail [编号] | /bind latest', 'Available: /bind [index] | /detail [index] | /bind latest'));
     lines.push(this.t('快速查看当前: /active', 'Quick view current: /active'));