ccgauge 1.0.3 → 1.0.5

package/README.md

@@ -138,11 +138,12 @@ Background mode persists state under `~/.ccgauge/`:
 | `ccgauge start --background` | Start a detached background service. |
 | `ccgauge stop [--force]` | Stop the background service. |
 | `ccgauge restart [options]` | Stop and re-start with new options. |
-| `ccgauge status [--json]` | Inspect the background service. |
+| `ccgauge status [--json]` | Inspect the background service. Plain-text mode exits **3** (systemd "not running") when nothing is up so shell can `if ccgauge status; then …`; `--json` always exits 0 — read `payload.running` instead. |
 | `ccgauge open` | Open the running dashboard in your browser. |
 | `ccgauge logs [-f] [-n <lines>]` | Print background-service log file (the server's stdout). |
 | `ccgauge report [options]` | Print a formatted **usage report** to stdout (one-shot, no server). |
 | `ccgauge mcp` | Start the MCP server on stdio so LLMs can query usage. |
+| `ccgauge doctor` | One-screen diagnostic: version, env, build artifacts, state, indexer + per-provider scan. Paste into bug reports. |
 
 ### Report
 
@@ -384,7 +385,7 @@ debug "why did it answer X".
 
 | Symptom | Try |
 | --- | --- |
-| Client doesn't see ccgauge tools | Restart the client after editing the config; check `npx -y ccgauge mcp` runs in your shell |
+| Client doesn't see ccgauge tools | Restart the client after editing the config; run `ccgauge mcp --check` (or `ccgauge doctor`) to verify the bundle, indexer, and detected providers without an MCP client |
 | First call is slow | First call after a cold start indexes all JSONL files (~1–3 s for 100 files); subsequent calls are O(1) |
 | "no providers detected" in the resource | The MCP process can't see `~/.claude/projects` / `~/.codex/sessions`; pass `CLAUDE_CONFIG_DIR` / `CCGAUGE_CODEX_DIR` via `env` in the MCP config |
 | Want to see what the server is logging | Watch the client's MCP log; ccgauge writes to **stderr** (stdout is reserved for JSON-RPC) |
@@ -461,6 +462,8 @@ pnpm test              # codex parser smoke test (Node 22+)
 pnpm build             # next build + copy static into .next/standalone
 pnpm start             # run bin/cli.mjs against the standalone build
 pnpm screenshots       # regenerate docs/screenshots/*.png
+pnpm site:dev          # marketing site dev server, http://localhost:4321
+pnpm site:build        # build only the site/ marketing site
 pnpm clean             # rm -rf .next node_modules
 ```
 
@@ -473,8 +476,11 @@ pnpm publish --access public  # runs `pnpm build` first via prepublishOnly
 
 ## Troubleshooting
 
+> **First stop for any "why doesn't this work" question:** run `ccgauge doctor`. It prints version, env vars, build artifacts, background-service state, and the indexer's per-provider scan in one screen — perfect for pasting into a bug report.
+
 | Symptom | Try |
 | --- | --- |
+| Anything unexpected | `ccgauge doctor` — one-screen diagnostic for everything below |
 | Port keeps drifting | `ccgauge --strict-port --port 3737` |
 | Stale background service | `ccgauge status`, then `ccgauge stop --force` |
 | Background didn't start | `ccgauge logs` reads `~/.ccgauge/ccgauge.log` |

package/README.zh-CN.md

@@ -138,11 +138,12 @@ ccgauge stop
 | `ccgauge start --background` | 启动后台服务。 |
 | `ccgauge stop [--force]` | 停止后台服务。 |
 | `ccgauge restart [options]` | 停止再用新参数启动。 |
-| `ccgauge status [--json]` | 查看后台状态。 |
+| `ccgauge status [--json]` | 查看后台状态。纯文本模式后台未运行时退出码 **3**（systemd 约定），shell 可用 `if ccgauge status; then …`；`--json` 始终退 0，请改读 `payload.running`。 |
 | `ccgauge open` | 在浏览器打开正在运行的看板。 |
 | `ccgauge logs [-f] [-n <lines>]` | 查看后台服务的日志（server stdout）。 |
 | `ccgauge report [options]` | 命令行**用量报告**，直接打到终端（一次性，不起服务）。 |
 | `ccgauge mcp` | 起 MCP 服务（stdio），让 LLM 查你的用量。 |
+| `ccgauge doctor` | 一屏诊断：版本、env、构建产物、后台状态、indexer + 每个 provider 的扫描计数。报 issue 时直接粘。 |
 
 ### 命令行报告（report）
 
@@ -378,7 +379,7 @@ LLM 大概率会调的工具——方便你"为什么会这样回答"反查。
 
 | 现象 | 建议 |
 | --- | --- |
-| 客户端看不到 ccgauge 工具 | 改完配置重启客户端；终端里手动跑 `npx -y ccgauge mcp` 看是否能起 |
+| 客户端看不到 ccgauge 工具 | 改完配置重启客户端；不连 MCP 客户端就能验证 bundle / indexer / providers 的话直接跑 `ccgauge mcp --check`（或 `ccgauge doctor`）|
 | 第一次调用比较慢 | 冷启动后第一次会全量索引（100 文件 ~1–3s）；之后都是 O(1) |
 | Resource 显示 "no providers detected" | MCP 进程看不到 `~/.claude/projects` / `~/.codex/sessions`；通过 MCP 配置的 `env` 传 `CLAUDE_CONFIG_DIR` / `CCGAUGE_CODEX_DIR` |
 | 想看 server 在打什么日志 | 看客户端的 MCP 日志；ccgauge 把日志写到 **stderr**（stdout 被 JSON-RPC 占用）|
@@ -454,6 +455,8 @@ pnpm test              # codex parser 烟测（Node 22+）
 pnpm build             # next build + 把 static 拷进 .next/standalone
 pnpm start             # 用 bin/cli.mjs 跑 standalone 产物
 pnpm screenshots       # 重新生成 docs/screenshots/*.png
+pnpm site:dev          # 产品官网开发服务，http://localhost:4321
+pnpm site:build        # 只构建 site/ 产品官网
 pnpm clean             # rm -rf .next node_modules
 ```
 
@@ -466,8 +469,11 @@ pnpm publish --access public  # 会自动先跑 pnpm build（prepublishOnly）
 
 ## 排障
 
+> **任何"为啥不工作"的问题先跑一下：** `ccgauge doctor`。一屏列出版本、env、构建产物、后台状态、indexer 扫描计数，报 issue 直接粘过去就行。
+
 | 现象 | 建议命令 |
 | --- | --- |
+| 任何异常想先一屏看清 | `ccgauge doctor` — 下面所有项都在它的诊断里 |
 | 端口被自动换掉 | `ccgauge --strict-port --port 3737` |
 | 后台服务状态不对 | 先 `ccgauge status`，PID 仍存活但不响应再 `ccgauge stop --force` |
 | 后台启动失败 | `ccgauge logs` 查看 `~/.ccgauge/ccgauge.log` |
@@ -508,10 +514,11 @@ pnpm publish --access public  # 会自动先跑 pnpm build（prepublishOnly）
 ## 产品官网
 
 产品官网（Astro + Tailwind 自建、中英双语、暗 / 亮主题、独立部署）放在
-[`site/`](./site/) 目录。它跟着主仓库一起在 git 里，但**不会**进 npm 包。
+[`site/`](./site/) 目录。它跟着主仓库一起在 git 里，但**不会**进 npm 包；
+命令和依赖统一由根目录 `package.json` 管理。
 
 ```bash
-cd site && pnpm install && pnpm dev   # http://localhost:4321
+pnpm site:dev   # http://localhost:4321
 ```
 
 构建 / 部署细节见 [`site/README.md`](./site/README.md)。