docs: cover doctor on the human-facing surfaces (README, README.ja, llms.txt)

README.ja.md

@@ -225,6 +225,20 @@ codex:
 
 despawnは指定されたメンバーにのみ作用する — `despawn` を実行しているセッション自体は決して終了させられず、広い購読範囲を持つウォッチャーは別のロール宛の `ctrl:despawn` を無視する。
 
+### 誰が何を持っているかを見る（`doctor`）
+
+配信が沈黙したり、ロールがどうしても取得できないとき、`doctor` はインストール全体の状態を1画面にまとめて表示する: (project, type) ごとにグループ化された全登録、各actasロックとその所有者（まだ生きているかどうかも）、ウォッチャーとブリッジのプロセス、プロジェクトごとの配信モード — そして stale なものを名指しする warnings セクション。
+
+```
+/agmsg doctor                  # インストール全体 — すべてのチーム、プロジェクト、タイプ
+/agmsg doctor --team myteam    # 1つのチームに絞る
+/agmsg doctor --redacted       # 共有用に伏せたレポート — 何が隠れるかは下記参照
+```
+
+素の `doctor` が通常形だ: `claude doctor` や `brew doctor` と同じく、スコープを取らず全体を報告する。`--project <path>`・`--type <type>`・`--team <team>` はレポートを絞り込むもので、自由に組み合わせられる — 疑わしい箇所に当たりがついているときに使うのであって、doctorが要求するものではない。`--redacted` は共有用にレポートを伏せる — 何が隠れて何が残るかは正確に: ホームディレクトリの前置部分は `~` に畳まれ（ユーザ名は消えるが、`$HOME` **配下**のパスはそのまま見える）、`$HOME` の**外**のプロジェクトパスは一貫した仮名（`<project1>`）に置き換わり、チーム/エージェント名は `team1`/`agent2` になる。`$HOME` 配下のプロジェクトはディレクトリ名がそのまま出るので、公開 issue に貼る前に、出力に見られたくないものが残っていないか一度目を通すこと。
+
+doctorは**読み取り専用**だ: staleなロックや死んだウォッチャーのpidfileは報告されるだけで、決して掃除されない — 証拠はその場に残る。終了コードでスクリプトからも扱える — `0` は問題なし、`1` は1つ以上の警告、`2` は使い方または解決のエラー（未知の `--type`/`--team`、または明示したフィルタに何もマッチしない場合）。シェルやCIからは `~/.agents/skills/<cmd>/scripts/doctor.sh` として呼び出す。
+
 ## 配信モード
 
 受信メッセージがエージェントにどう届くか。初回参加時のプロンプトで1つ選ぶか、後で `/agmsg mode <name>` で変更する。

README.md

@@ -239,6 +239,20 @@ See **[docs/session-resurrect.md](docs/session-resurrect.md)** for the tmux-resu
 setup, how it resolves each pane, what does and doesn't come back automatically, and
 the manual fallback.
 
+### See who holds what (`doctor`)
+
+When delivery goes quiet or a role refuses to be claimed, `doctor` puts the state of the whole installation on one screen: every registration grouped by (project, type), each actas lock with its owner and whether that owner is still alive, watcher and bridge processes, the delivery mode per project — and a warnings section naming anything stale.
+
+```
+/agmsg doctor                  # the whole installation — every team, project, type
+/agmsg doctor --team myteam    # narrow to one team
+/agmsg doctor --redacted       # masked report for sharing — see below for what is hidden
+```
+
+Bare `doctor` is the normal form: like `claude doctor` or `brew doctor`, it takes no scope and reports on everything. `--project <path>`, `--type <type>`, and `--team <team>` narrow the report and combine freely — reach for them when you already suspect a corner, not because doctor requires them. `--redacted` masks the report for sharing — be precise about what it hides and what it keeps: your home directory prefix is collapsed to `~` (the username disappears, but the path *below* `$HOME` stays visible), project paths **outside** `$HOME` are replaced with consistent pseudonyms (`<project1>`), and team/agent names become `team1`/`agent2`. A project under `$HOME` still shows its directory names, so skim the output for anything you consider sensitive before pasting it into a public issue.
+
+Doctor is **read-only**: a stale lock or dead watcher pidfile is reported, never cleaned up, so the evidence stays in place. The exit code makes it scriptable — `0` clean, `1` one or more warnings, `2` usage or resolution error (an unknown `--type`/`--team`, or an explicit filter that matches nothing). From a shell or CI, invoke it as `~/.agents/skills/<cmd>/scripts/doctor.sh`.
+
 ## Delivery modes
 
 How incoming messages reach your agent. Pick one at first join via the prompt, or change it later with `/agmsg mode <name>`.

llms.txt

@@ -72,6 +72,7 @@ directly-invokable commands; `scripts/drivers/<axis>/` holds axis drivers and
 - [scripts/join.sh](scripts/join.sh): join or create a team.
 - [scripts/whoami.sh](scripts/whoami.sh): resolve this project's agent identity.
 - [scripts/delivery.sh](scripts/delivery.sh): get/set the delivery mode.
+- [scripts/doctor.sh](scripts/doctor.sh): report who holds what — registrations, locks, watchers, delivery — read-only.
 - [scripts/spawn.sh](scripts/spawn.sh) / [scripts/despawn.sh](scripts/despawn.sh): launch / tear down a peer agent.
 - [scripts/history.sh](scripts/history.sh): replay a room's history.
 - [SKILL.md](SKILL.md): the agent-facing skill definition (full command reference).