sync: update from private repo (2336949a)

docs/tools/listfilestorelocations.md

@@ -0,0 +1,70 @@
+# ListFileStoreLocations / ListFileStoreFiles
+
+利用者が SharePoint / OneDrive / Box のうち「ここだけ見てよい」と決めて登録した
+フォルダを、エージェント側から一覧するための 2 つの道具。
+
+**中身は取得できない。** 取れるのは、そのフォルダの直下にある項目の
+名前・フォルダかどうか・大きさ・更新日時だけ。ファイルを開いて読むのは別の段で、
+この道具にはそのための引数も戻り値もない。
+
+## 使う順番
+
+1. `ListFileStoreLocations()` — 登録済みの場所を一覧する。引数なし。
+2. 出てきた `id` を `ListFileStoreFiles({ locationId })` に渡して、その直下を見る。
+
+`id` は 1 の一覧から得たものだけが使える。当てずっぽうの id は「見つかりません」に
+なる（他人の場所を当てても同じ答えなので、存在の有無は分からない）。
+
+## 例
+
+```
+ListFileStoreLocations()
+→ ## 外部ファイル保存の場所 — 2 件
+  - id: 7f3c…
+    service: SharePoint / OneDrive
+    path: /Shared Documents/請求書
+    library: Shared Documents
+    site: https://contoso.sharepoint.com/sites/sales
+    connection: 営業部 SharePoint
+  - id: 91ab…
+    service: Box
+    path: /経理/請求書
+    site: https://app.box.com/folder/123456789
+    connection: 経理部 Box
+
+ListFileStoreFiles({ locationId: "7f3c…" })
+→ ## /Shared Documents/請求書（Shared Documents）— 3 件
+  - 2026-07.xlsx  size=20.0 KB  updated=2026-07-31T09:00:00Z
+  - 2026-06.xlsx  size=19.2 KB  updated=2026-06-30T09:00:00Z
+  - [フォルダ] 控え  updated=2026-05-02T04:11:00Z
+```
+
+`service` は保存先の種類。Box にはライブラリ（文書ライブラリ）に当たる階層が
+無いので `library` の行が出ない。`site` の行は、SharePoint ならサイトの URL、
+Box ならそのフォルダのページの URL になる。
+
+## 制限
+
+| 事項 | 実際の動き |
+|------|-----------|
+| 深さ | 登録された 1 フォルダの**直下のみ**。中のフォルダには入れない |
+| 場所の指定 | 登録時に決まっている。SharePoint はサイトとライブラリとフォルダ、Box はフォルダ番号ひとつ |
+| 中身 | 取得できない。ダウンロードも本文の抽出もできない |
+| 件数 | 既定 500 件。超えた場合は「これで全部ではありません」と出力に付く |
+| 誰の資格情報か | **タスクの持ち主**のもの。共有されたタスクを別の人が動かしても、使われるのは持ち主の接続 |
+| 書き込み | できない。要求している権限は読み取りのみ |
+
+## 出ないとき
+
+出力の文面がそのまま次の一手になる。
+
+| 出力の趣旨 | 状況 | できること |
+|-----------|------|-----------|
+| この実行では使えません | 機能が有効になっていない実行 | 手元のワークスペースのファイルで進める |
+| 登録されている保存場所はありません | 接続はあるがフォルダ未登録 | 利用者に登録を頼む |
+| 見つかりません | id が違う・他人の場所 | `ListFileStoreLocations` を取り直す |
+| 接続がまだ済んでいません | 持ち主が未接続 | 利用者に設定画面からの接続を頼む |
+| 認可の期限が切れています | 更新できなくなった | 利用者に接続し直しを頼む |
+
+管理者がワークスペースの設定でツール分類 `filestore` を切っている場合、この 2 つは
+そもそもツール一覧に出ない。