ドキュメントとスクショの点検（docs-refresh）

docs/development.md の決まりでは、画面や機能を変えた PR が README・docs/guide.md・スクショを同じ PR で直すことになっている。それでも漏れは出る（#225 で撮ったスクショは、#227〜#248 の画面の変更を 1 枚も映していなかった）。この作業は、その漏れをリリースのたびにまとめて拾い、ドキュメントが長くなりすぎないようにも保つ。

CLAUDE.md の「Security」を常に守る。スクショと文章に載せるのはダミーデータ（tools/screenshots/gen.py・mkgit.py）だけで、手元の本物の履歴・パス・ユーザー名を撮ったり例に書いたりしない。

0. 範囲を決める

• 引数が shots なら 1 と 2 だけ、text なら 3 と 4 だけ、なければ全部
• 前回のリリースのタグを起点にする: git describe --tags --abbrev=0。changes/ の断片と CHANGELOG の ## Unreleased、そのタグから今までの変更が点検の手がかりになる
• 手順の元は docs/development.md の「Screenshots」と「Docs」の項目。食い違ったらそちらを正とし、このファイルも直す

1. スクショが古いかを確かめる

ダミーデータは乱数を固定しているが、日付を「今日」から作るので、撮るたびに中身が変わる。画像どうしをピクセルで比べても古さはわからない。古さは「最後に撮ったあとに画面が変わったか」で決める。

last=$(git log -1 --format=%H -- docs/screenshot.png)
git log --oneline "$last"..HEAD -- internal/web tools/screenshots

• 何も出なければ、スクショは新しい。2 を飛ばす
• 出たら、各コミットが README・guide に載っている画面（週のカレンダー、セッションの詳細、Worth a look、週のまとめ、週報の「Analyze with AI」）の見た目を変えたかを差分で確かめる。内部の整理だけで見た目が変わらないなら撮り直さない。迷ったら撮り直す

2. 撮り直して、目で確かめる

(cd tools/screenshots && npm ci --ignore-scripts && npx playwright install chromium)
sh tools/screenshots/run.sh

• Playwright の Chromium を取ってこられない環境（クラウドのコンテナなど）では、入っている Chromium を指定する: CHROMIUM=/opt/pw-browsers/chromium sh tools/screenshots/run.sh
• 撮る前の画像を一時ディレクトリに控え、撮ったあと 1 枚ずつ Read で開いて新旧を見比べる。確かめること:
  • 1 で見つけた変更が映っている
  • 崩れ・重なり・切れた文字・空の欄がない
  • 本物の履歴、手元のパス、ユーザー名が写っていない（session.png は右の列に一時パスが出るので左の列だけを撮る、という前提が保たれているか）
• 撮ったあと sh tools/screenshots/keep-changed.sh で、コミットしてある版と比べて描画のゆらぎだけの画像を戻す（demo.gif は止まって見える場面どうしで比べる）。ダミーデータは「今」から作るので、日付ごと戻せるのは同じ KIROKU_FAKE_NOW で撮ったときだけ（tools/release.sh は ci.yml の e2e と同じ時刻で撮る）
• demo.gif（README の先頭の動き）も同じ run.sh で撮り直される。いくつかのコマを ffmpeg で取り出して Read で確かめる
• 変わったのに理由を説明できない画像があれば、コミットせずに調べる

3. 文章が古いかを確かめる

対象は README.md、README.ja.md（README.md と同じ内容か）、docs/guide.md、docs/compatibility.md、docs/usability.md、docs/development.md、SECURITY.md、CONTRIBUTING.md。docs/sources.md の「What history records」は /source-audit の担当なので、ここでは明らかな食い違いを報告するだけにする。

• changes/ の断片、CHANGELOG の ## Unreleased、前回のタグからの各項目について、ユーザーに見える変更（新しい指標・ボタン・オプション・コマンド・既定値・名前の変更・消えたもの）がドキュメントに書かれているかを確かめる
• 逆向きにも確かめる: ドキュメントにある名前（ボタン・見出し・指標・オプション・環境変数）を grep で internal/ から探し、今もあるか、同じ綴りかを見る。消えたものの説明が残っていたら消す
• kiroku help と各コマンドの --help の出力を、guide のコマンド表・オプション表と見比べる
• README は入口なので、主な機能の一覧が今の画面と合っているか（大きな機能が抜けていないか、なくなった機能を宣伝していないか）を見る
• 指標の説明は HELP と guide の「How to read the metrics」の表を TestHelpMatchesGuide が突き合わせている。表を直したら HELP も直す

4. 長すぎるところを削る

ドキュメントは足すばかりだと読まれなくなる。次の目安に当たるところを探して直す。

wc -c README.md docs/*.md
awk 'length>800{print FILENAME": "NR" ("length" chars)"}' README.md docs/*.md

• 同じことを 2 か所以上に書いている → 1 か所にまとめ、ほかはリンクにする（README は要点とリンク、詳しいことは guide）
• 1 つの段落や表のマスに条件・例外・数字を詰め込んでいる → 箇条書きか小さな表に分ける
• 実装の経緯や内部の事情（「以前は〜だった」「〜のために〜した」）→ CHANGELOG か docs/development.md に任せ、利用者向けの文書からは消す
• README は 1 画面で読み終わる長さを保つ。新しい機能を足すときは、既存の項目と合わせて短くする

削るときの決まり:

• 意味を変えない。機能・数字・しきい値・注意書き（特にプライバシーとセキュリティ）を消さない
• 削った・移した内容を PR の本文に箇条書きで残す
• 大きく組み替えたくなったら（節の入れ替え、ファイルを分けるなど）、案をユーザーに見せて決めてもらう。この作業では手を付けない

5. 確かめて PR にする

gofmt -l .
go vet ./...
go test ./...

• 文章の英語は、まわりの文体（短い文、同じものは同じ言葉で、推定は推定と書く）に合わせる
• リンク（docs/guide.md#... の見出しへのリンクを含む）が切れていないかを確かめる
• 差分を読み直す。消した文の中に、まだ正しくて必要なことがなかったか
• ドキュメントとスクショだけの変更なら CHANGELOG には書かない（#225 と同じ）
• ブランチにコミットし、push して PR を作る。タイトルは英語で（例: Refresh the screenshots and bring the guide up to date）。本文に、古かったもの（どの PR の変更が映っていなかったか）、撮り直した画像、直した文章、削った・移した内容を書く
• subscribe_pr_activity で見守る
• 何も古くなく、削るところもなければ、PR は作らずにそう伝える

やらないこと

• 本物の履歴でスクショを撮らない
• 画面やコードを直さない。ドキュメントのほうが正しく画面が間違っているように見えたら、報告にとどめる
• 古さを確かめずに、念のためだけで撮り直した画像をコミットしない（1 で変更がなかったら撮らない）
• テストを消したり飛ばしたりして通さない