docs(readme): refine user guide tone and examples (#23)

Co-authored-by: liyanbowne <liyanbowne@gmail.com>

Author: Dikevin

AGENTS.md

@@ -41,3 +41,8 @@ Detailed design notes live in `docs/internal/`.
 ## References
 
 - `docs/internal/codex-runtime-channels.md`
+
+## User Docs
+
+- Treat `README.md` and `README.zh-CN.md` as user-facing onboarding guides, not internal reference manuals.
+- Keep README sections short and task-oriented; prefer a few high-signal commands and examples over exhaustive command listings.

README.md

@@ -4,12 +4,12 @@
 
 `codex-team` provides the `codexm` CLI for managing multiple Codex ChatGPT login snapshots on one machine.
 
-It is built for people who regularly switch between multiple Codex accounts and want a simpler workflow for:
+Use it when you regularly switch between multiple Codex accounts and want a simpler way to:
 
-- saving named account snapshots
-- switching the active `~/.codex/auth.json`
-- checking quota usage across saved accounts
-- automatically switching and restarting when the current account is exhausted
+- save named account snapshots
+- switch the active `~/.codex/auth.json`
+- check quota usage across saved accounts
+- automatically switch and restart when the current account is exhausted
 
 ## Platform support
 
@@ -37,11 +37,7 @@ codexm add team1
 codexm launch --watch
 ```
 
-Typical flow:
-
-- `codexm add <name>` opens the ChatGPT login flow and stores a named snapshot
-- `codexm launch --watch` starts Codex Desktop and keeps a background watcher running
-- when the active account is exhausted, the watcher can switch to the best saved account automatically
+This adds a couple of named snapshots, launches Codex Desktop, and keeps a watcher running in the background.
 
 ### Linux / WSL with Codex CLI
 
@@ -57,11 +53,25 @@ In another terminal, start Codex through the wrapper:
 codexm run -- --model o3
 ```
 
-Typical flow:
+`codexm watch` monitors quota and can auto-switch accounts. `codexm run` wraps the `codex` CLI and restarts it when `~/.codex/auth.json` changes, so a long-running CLI session can follow account switches automatically.
+
+## Example output
+
+Redacted `codexm list` example:
+
+```text
+$ codexm list
+Current managed account: plus-main
+Accounts: 2/3 usable | blocked: 1W 1, 5H 0 | plus x2, team x1
+Total: bottleneck 0.84 | 5H->1W 0.84 | 1W 1.65 (plus 1W)
+
+  NAME         IDENTITY   PLAN  SCORE  ETA   5H USED  1W USED  NEXT RESET
+* plus-main    acct...123 plus  72%    2.1h  58%      41%      04-14 18:30
+  team-backup  acct...987 team  64%    1.7h  61%      39%      04-14 19:10
+  plus-old     acct...456 plus  0%     -     43%      100%     04-16 09:00
+```
 
-- `codexm watch` monitors quota and can auto-switch accounts
-- `codexm run` wraps the `codex` CLI and restarts it when `~/.codex/auth.json` changes
-- this lets a long-running CLI session follow account switches automatically
+This is the main command to use when deciding which account to switch to next.
 
 ## Core commands
 
@@ -95,18 +105,18 @@ Typical flow:
 
 Use `codexm --help` for the full command reference.
 
-## Notes
+## When should I use each command?
 
-- `codexm list` is the best overview command when choosing which account to use next.
+- `codexm list` is the best overview when choosing the next account.
 - `codexm watch` is the automation loop that reacts to quota exhaustion.
-- `codexm run` is mainly useful for CLI workflows where you want the running `codex` process to follow account switches.
-- Use `--json` for scripting and `--debug` for stderr diagnostics.
+- `codexm run` is useful in CLI workflows where the running `codex` process should follow account switches.
+- Use `--json` for scripting and `--debug` for diagnostics.
 
 For ChatGPT auth snapshots, `codex-team` can save and switch different users under the same ChatGPT account or workspace as separate managed entries when the local login tokens distinguish them.
 
 ## Shell completion
 
-Generate a shell completion script and install it with your shell's standard mechanism:
+Generate a completion script and install it with your shell's standard mechanism:
 
 ```bash
 mkdir -p ~/.zsh/completions

README.zh-CN.md

@@ -4,7 +4,7 @@
 
 `codex-team` 提供 `codexm` 命令，用来在一台机器上管理多个 Codex ChatGPT 登录快照。
 
-它适合经常在多个 Codex 账号之间切换的用户，主要解决这些问题：
+如果你经常在多个 Codex 账号之间切换，它可以帮你更简单地：
 
 - 保存多个命名账号快照
 - 切换当前生效的 `~/.codex/auth.json`
@@ -37,11 +37,7 @@ codexm add team1
 codexm launch --watch
 ```
 
-典型流程：
-
-- `codexm add <name>` 打开 ChatGPT 登录流程并保存一个命名快照
-- `codexm launch --watch` 启动 Codex Desktop，同时保持后台 watcher 运行
-- 当当前账号耗尽时，watcher 可以自动切换到最合适的已保存账号
+这会新增几个命名快照、启动 Codex Desktop，并在后台保持 watcher 运行。
 
 ### Linux / WSL + Codex CLI
 
@@ -57,11 +53,25 @@ codexm watch
 codexm run -- --model o3
 ```
 
-典型流程：
+`codexm watch` 会持续监控 quota，并在耗尽时自动切号。`codexm run` 会包装 `codex` CLI，在 `~/.codex/auth.json` 变化后自动重启，这样长时间运行的 CLI 会话就能自动跟随切号。
+
+## 输出示例
+
+下面是一个脱敏后的 `codexm list` 示例：
+
+```text
+$ codexm list
+Current managed account: plus-main
+Accounts: 2/3 usable | blocked: 1W 1, 5H 0 | plus x2, team x1
+Total: bottleneck 0.84 | 5H->1W 0.84 | 1W 1.65 (plus 1W)
+
+  NAME         IDENTITY   PLAN  SCORE  ETA   5H USED  1W USED  NEXT RESET
+* plus-main    acct...123 plus  72%    2.1h  58%      41%      04-14 18:30
+  team-backup  acct...987 team  64%    1.7h  61%      39%      04-14 19:10
+  plus-old     acct...456 plus  0%     -     43%      100%     04-16 09:00
+```
 
-- `codexm watch` 持续监控 quota，并在耗尽时自动切号
-- `codexm run` 包装 `codex` CLI，在 `~/.codex/auth.json` 变化后自动重启
-- 这样长时间运行的 CLI 会话可以自动跟随切号
+如果你想判断“接下来该切到哪个账号”，优先看这个命令。
 
 ## 常用命令
 
@@ -95,7 +105,7 @@ codexm run -- --model o3
 
 完整命令参考请使用 `codexm --help`。
 
-## 使用建议
+## 什么时候该用哪个命令？
 
 - 如果你想判断“接下来该用哪个账号”，优先看 `codexm list`
 - 如果你想自动切号，使用 `codexm watch`