docs: add msglib enrichment runbook

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 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 or `ISPHERE_PACKET_LOG_DIR` points to an operator-local directory of encrypted PacketReader `.log`/`.txt` files.
+Current scope: expose four WinHelper observation operations plus four 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 message source unless `ISPHERE_PACKET_LOG_FILE` points to an operator-local encrypted PacketReader log-line file or `ISPHERE_PACKET_LOG_DIR` points to an operator-local directory of encrypted PacketReader `.log`/`.txt` files. Contact/group display names can also be optionally enriched from an operator-local copied `MsgLib.db` through the bounded read-only `MsgLibReadSidecar`.
 
 ## 1. Prerequisites
 
@@ -100,6 +100,7 @@ The verification confirms:
 - `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.
+- The deterministic verification path clears MsgLib env variables, so it proves the default no-MsgLib behavior remains stable.
 - File download/cache mapping and send business tools remain later-stage work.
 
 ## 6. Configure optional message source
@@ -128,7 +129,73 @@ The directory loader recursively reads `.log` and `.txt` files, sorts paths dete
 
 Then start the MCP server normally. The command entry point uses `ISPHERE_PACKET_LOG_FILE` when the file variable is set, otherwise `ISPHERE_PACKET_LOG_DIR` when the directory variable is set. The repeatable verification script checks three paths: default empty source, a temporary synthetic encrypted fixture file, and a temporary synthetic encrypted fixture directory.
 
-## 7. Configure MCP client command
+## 7. Configure optional MsgLib display-name enrichment
+
+This is optional. It enriches contact/group display metadata; it does not turn `MsgLib.db` into the primary message source. `isphere_receive_messages` still needs a PacketReader source to return messages, and MsgLib only fills safe display fields such as `sender_name` and `conversation.display_name`.
+
+Build the bounded x86 sidecar first:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\build-msglib-sidecar.ps1
+```
+
+Then configure all three MsgLib variables before starting the MCP server:
+
+```powershell
+$env:ISPHERE_MSGLIB_SIDECAR_EXE = "E:\coding\codex\isphere-ai-bridge\runs\msglib-sidecar\MsgLibReadSidecar.exe"
+$env:ISPHERE_MSGLIB_SQLITE_DLL = "<path-to-copied-System.Data.SQLite.dll>"
+$env:ISPHERE_MSGLIB_DB = "<path-to-copied-MsgLib.db>"
+```
+
+Optional password override:
+
+```powershell
+$env:ISPHERE_MSGLIB_PASSWORD = "123"
+```
+
+Rules:
+
+- Set all of `ISPHERE_MSGLIB_SIDECAR_EXE`, `ISPHERE_MSGLIB_SQLITE_DLL`, and `ISPHERE_MSGLIB_DB`, or set none of them. Partial MsgLib config fails server startup.
+- Keep copied DB/provider files under ignored `runs/` paths or another operator-local location. Do not commit them.
+- `MsgLibReadSidecar` is read-only and bounded to schema/display metadata operations. It does not send messages, download files, mutate DB rows, log in, hook processes, or return raw rows.
+- Standard `scripts\verify-go-mcp.ps1` intentionally clears MsgLib variables to keep the default smoke deterministic.
+
+Verify the optional provider path:
+
+```powershell
+$env:ISPHERE_MSGLIB_SQLITE_DLL = "<path-to-copied-System.Data.SQLite.dll>"
+$env:ISPHERE_MSGLIB_DB = "<path-to-copied-MsgLib.db>"
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-msglib-sidecar.ps1
+```
+
+Expected provider evidence contains `provider_checked=true`, a `display_source_count`, and sanitized `display_entity_summaries` with counts/source table names only.
+
+Verify MCP-level optional enrichment, including receive-message display fields:
+
+```powershell
+$env:ISPHERE_MSGLIB_SQLITE_DLL = "<path-to-copied-System.Data.SQLite.dll>"
+$env:ISPHERE_MSGLIB_DB = "<path-to-copied-MsgLib.db>"
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-msglib-mcp-enrichment.ps1
+```
+
+Expected MCP evidence is sanitized and should include:
+
+```json
+{
+  "ok": true,
+  "receive_display_smoke": true,
+  "receive_sender_name_populated": true,
+  "receive_conversation_display_populated": true,
+  "printed_entity_values": false,
+  "message_bodies_returned": false,
+  "file_paths_returned": false,
+  "raw_rows_returned": false
+}
+```
+
+The optional MCP smoke internally uses copied-DB display metadata to build a synthetic encrypted PacketReader fixture, but the printed output must stay limited to counts, booleans, and `msglib:<source_table>` refs. It must not print entity values, JIDs, message bodies, local DB paths, attachment paths, or raw rows.
+
+## 8. Configure MCP client command
 
 After building a stable binary, configure your MCP client to run the Go MCP executable as a stdio server.
 
@@ -163,7 +230,7 @@ If you used `go build ./cmd/isphere-mcp` without `-o`, point the command to:
 E:\coding\codex\isphere-ai-bridge\isphere-mcp.exe
 ```
 
-## 8. Allowed tools
+## 9. Allowed tools
 
 These eight tools are currently allowed:
 
@@ -189,7 +256,7 @@ Allowed parameters:
 - `isphere_search_groups`: `query`, `cursor`, `source_preference`, `include_archived`, `limit` only. `source_preference` currently supports empty/`auto`/`local_readonly`; `cursor` must be empty until pagination is implemented.
 - `isphere_receive_files`: `conversation_id`, `message_id`, `file_id`, `name_contains`, `mode`, `output_dir`, `cursor`, `source_preference`, `preview`, `limit` only. C22 supports `mode` empty or `list`; `source_preference` currently supports empty/`auto`/`local_readonly`; `cursor` and `output_dir` must be empty in current list-only mode; download is deferred.
 
-## 9. Current tool surface and next-stage route
+## 10. Current tool surface and next-stage route
 
 The current runbook verifies eight tools:
 
@@ -202,11 +269,11 @@ The current runbook verifies eight tools:
 - `isphere_search_groups`
 - `isphere_receive_files`
 
-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` or a directory of `.log`/`.txt` files via `ISPHERE_PACKET_LOG_DIR`; this is still not a production ingestion claim because raw evidence remains local and uncommitted. `isphere_receive_messages` now exposes contract-facing fields for digital-employee consumption while preserving older aliases for compatibility, supports `conversation_id`, keyword `query`, and RFC3339 `since` filtering, and validates the remaining safe contract args without pretending unsupported connectors/pagination exist. Contact and group search also accept the safe local-readonly contract args. `isphere_receive_files` supports list mode with safe contract arg validation; download/cache mapping remains deferred.
+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` or a directory of `.log`/`.txt` files via `ISPHERE_PACKET_LOG_DIR`; this is still not a production ingestion claim because raw evidence remains local and uncommitted. `isphere_receive_messages` now exposes contract-facing fields for digital-employee consumption while preserving older aliases for compatibility, supports `conversation_id`, keyword `query`, and RFC3339 `since` filtering, and validates the remaining safe contract args without pretending unsupported connectors/pagination exist. Contact and group search also accept the safe local-readonly contract args and can optionally enrich display metadata from `MsgLibReadSidecar`; receive-message `sender_name` and `conversation.display_name` can use that same optional metadata when MsgLib env is configured. `isphere_receive_files` supports list mode with safe contract arg validation; download/cache mapping remains deferred.
 
 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
+## 11. Real-login UIA capture procedure
 
 This is a later real-login capture gate used to collect live UI structure for connector work.
 
@@ -247,7 +314,7 @@ Procedure:
 
 8. Review and redact any sensitive content before sharing reports.
 
-## 11. If this outer-network environment cannot log in
+## 12. If this outer-network environment cannot log in
 
 iSphere is internal-network only. If the current repository environment is outside that network, use two separate routes:
 
@@ -278,7 +345,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\validate-n12r-retu
 
 Keep the validation report outside `$captureRoot`; the returned package is evidence input and should remain unchanged.
 
-## 12. Troubleshooting
+## 13. Troubleshooting
 
 - If C# helper build fails, run `scripts\build-win-helper.ps1` directly and check for missing .NET Framework reference assemblies.
 - If `win_helper_version` fails, rerun `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1` first.