feat: register isphere file receive list tool

docs/go-mcp-runbook.md

@@ -2,7 +2,7 @@
 
 This runbook is for the first Go MCP phase of `isphere-ai-bridge`. It lets an operator build and verify the Windows helper and the Go MCP server without reading the source code.
 
-Current scope: expose four WinHelper observation operations plus the first log-backed business read tool, `isphere_receive_messages`, through Go MCP. The receive tool is registered with an empty default source unless `ISPHERE_PACKET_LOG_FILE` points to an operator-local encrypted PacketReader log-line file.
+Current scope: expose four WinHelper observation operations plus four log-backed business read tools through Go MCP: `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files` list mode. These business read tools use an empty default source unless `ISPHERE_PACKET_LOG_FILE` points to an operator-local encrypted PacketReader log-line file.
 
 ## 1. Prerequisites
 
@@ -90,14 +90,15 @@ The verification confirms:
 - C# helper can be built.
 - Go MCP binary can be built.
 - MCP initialize/list/call flow works through the SDK harness.
-- Exactly seven tools are exposed: four WinHelper observation tools plus `isphere_receive_messages`, `isphere_search_contacts`, and `isphere_search_groups`.
+- Exactly eight tools are exposed: four WinHelper observation tools plus `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files`.
 - `win_helper_version` returns `ISphereWinHelper`.
 - `isphere_receive_messages` is callable and returns an empty `messages` array from the default empty source.
 - A synthetic configured-source smoke check proves `ISPHERE_PACKET_LOG_FILE` can drive `isphere_receive_messages` end-to-end with one redacted fixture message.
 - `isphere_search_contacts` is callable and returns JID-derived contact candidates from the same configured synthetic message fixture.
 - `isphere_search_groups` is callable and returns JID-derived group candidates from the configured synthetic groupchat fixture.
+- `isphere_receive_files` is callable in list mode and returns one file metadata candidate from the configured synthetic file-transfer fixture.
 - Verification uses synthetic/local helper checks and does not load raw N12-pre evidence.
-- Contact/group/file/search/send business tools remain later-stage work.
+- File download/cache mapping and send business tools remain later-stage work.
 
 ## 6. Configure optional message source
 
@@ -154,7 +155,7 @@ E:\coding\codex\isphere-ai-bridge\isphere-mcp.exe
 
 ## 8. Allowed tools
 
-These seven tools are currently allowed:
+These eight tools are currently allowed:
 
 | Tool | Source/op | Purpose |
 | --- | --- | --- |
@@ -165,6 +166,7 @@ These seven tools are currently allowed:
 | `isphere_receive_messages` | log-backed `EncryptedPacketLogSource` | Read normalized messages from the configured PacketReader log source. The default server source is empty until a loader is wired. |
 | `isphere_search_contacts` | log-backed message JIDs | Search contact candidates extracted from sender/receiver bare JIDs in the configured message source. |
 | `isphere_search_groups` | log-backed groupchat JIDs | Search group candidates extracted from groupchat/conference/MUC bare JIDs in the configured message source. |
+| `isphere_receive_files` | log-backed file-transfer messages | List file metadata candidates extracted from file-transfer message bodies. Download/cache mapping is not implemented yet. |
 
 Allowed parameters:
 
@@ -175,10 +177,11 @@ Allowed parameters:
 - `isphere_receive_messages`: `limit` only.
 - `isphere_search_contacts`: `query`, `limit` only.
 - `isphere_search_groups`: `query`, `limit` only.
+- `isphere_receive_files`: `conversation_id`, `message_id`, `file_id`, `name_contains`, `mode`, `limit` only. C14 supports `mode` empty or `list`; download is deferred.
 
 ## 9. Current tool surface and next-stage route
 
-The current runbook verifies seven tools:
+The current runbook verifies eight tools:
 
 - `win_helper_version`
 - `win_helper_self_check`
@@ -186,10 +189,12 @@ The current runbook verifies seven tools:
 - `win_helper_dump_uia`
 - `isphere_receive_messages`
 - `isphere_search_contacts`
+- `isphere_search_groups`
+- `isphere_receive_files`
 
-`isphere_receive_messages` currently has parser/source/tool registration and an empty default server source. Raw N12-pre evidence remains under ignored `runs/` paths and is not committed. The current command entry point can read an operator-local encrypted PacketReader log-line file via `ISPHERE_PACKET_LOG_FILE`; this is still not a production ingestion claim because raw evidence remains local and uncommitted.
+The current log-backed business read tools have parser/source/tool registration and an empty default server source. Raw N12-pre evidence remains under ignored `runs/` paths and is not committed. The current command entry point can read an operator-local encrypted PacketReader log-line file via `ISPHERE_PACKET_LOG_FILE`; this is still not a production ingestion claim because raw evidence remains local and uncommitted. `isphere_receive_files` currently supports list mode only; download/cache mapping is deferred.
 
-Core business tools for contacts, groups, messages, and files are defined in `docs/mcp-core-tools-contract.md`. Send/file capabilities enter the roadmap through that contract after source discovery, connector selection, preview metadata, execution metadata, and audit records are in place.
+Core business tools for contacts, groups, messages, and files are defined in `docs/mcp-core-tools-contract.md`. Send capabilities enter the roadmap through that contract after source discovery, connector selection, preview metadata, execution metadata, and audit records are in place.
 
 ## 10. Real-login UIA capture procedure
 
@@ -248,7 +253,7 @@ win_helper_scan_windows
 win_helper_dump_uia
 ```
 
-The MCP server also registers `isphere_receive_messages`, but its default source is empty and it should not be used as N12R UIA evidence collection.
+The MCP server also registers the log-backed read tools (`isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files`), but their default source is empty and they should not be used as N12R UIA evidence collection.
 
 After receiving an N12R package, validate it with `docs/n12r-return-package-validation-checklist.md` before using it as evidence for selector-design review. Prefer the scripted read-only validator: