feat(files): add SharePoint file search and site discovery tools

Problem

Entrabot can operate on a known file or list items already shared with the Agent User, but it cannot discover a relevant file by topic or enumerate accessible SharePoint sites when the user does not already have a URL.

Desired outcome

Add bounded, structured search_files and list_sites tools that use Microsoft Search and SharePoint site discovery without weakening the existing site denylist or permission model.

Recommended priority: P2.

Scope

• Implement search_files through Microsoft Graph Search for driveItem entities.
• Implement list_sites through the supported SharePoint site search endpoint.
• Return typed dataclasses with stable IDs and enough metadata to feed existing file tools.
• Enforce configured site deny rules before returning actionable results.
• Handle pagination, throttling, malformed result entries, and partial pages.
• Document KQL/query limitations and explicit-user-request guidance for tenant-level search.
• Verify existing setup/consent paths include the required Files/Sites permissions.

Non-goals

• Full tenant indexing or a local search crawler.
• Background or speculative searches on every turn.
• Creating sites or document libraries.
• Bypassing access controls or returning results the Agent User cannot access.
• Replacing resolve_file_url or list_recent_files.

Acceptance criteria

• Search and site discovery use stable Graph endpoints and typed result models.
• Results from denied sites are filtered before they reach the model, with a bounded denied count rather than leaked metadata.
• Query, page-size, and maximum-result bounds are validated.
• 429 and transient failures use the established retry helpers and preserve typed errors.
• Pagination and empty/partial result cases are covered by tests.
• Setup documentation and consent scripts are verified against Files.Read.All / Sites.Read.All; no unnecessary permission is added.
• MCP tool docs, configuration guidance, and full pytest/Ruff gates pass.

Sources and related work

• Files platform reference — search and sites
• Deferred Files plan
• Existing direct Graph implementation: src/entrabot/tools/files.py.

Start with the existing Graph implementation in src/entrabot/tools/files.py, then read the files platform reference and deferred Files plan linked in the issue. Trace the setup and consent paths, add tests for pagination, partial results, throttling, denied sites, and bounds, and verify the MCP documentation plus full pytest and Ruff gates.