ADR-0011 · Google Workspace API over rclone mount for Vault access

Status

Accepted

Context

ADR-0001 chose Google Drive as the single source of truth for documents, with an rclone mount on the Agent Host as the agent access path. ADR-0004 named this path the Drive Bridge and described it as an rclone mount.

In practice, the rclone mount was never deployed: the VPS config held an empty OAuth token from May 2026, and no file was ever exposed through it. Meanwhile, the Hermes google-workspace skill — an OAuth2 API client covering Drive, Docs, Sheets, Gmail, Calendar and Contacts — matched the real use cases more closely: targeted full-text search, native .gdoc/.gsheet reads, read-only scopes, and zero disk footprint. The use cases identified in August 2026 (paperwork, dossier tracking, deadline watch) require Gmail and Calendar access, which an rclone mount cannot provide at all — rclone only mounts Drive.

The decision is structural: it defines how the agent reaches the Knowledge Vault (API client vs filesystem mount), which OAuth world is used (a Google Cloud OAuth client vs rclone’s own token), and which services are reachable (Drive only vs Drive + Docs + Sheets + Gmail + Calendar + Contacts).

Decision

The Drive Bridge is implemented with the Google Workspace API (Hermes skill google-workspace, OAuth 2.0 client hermes-workspace, read-only scopes), not with an rclone mount. The rclone mount is retired from the architecture. It remains a documented fallback (phase 2) only if a filesystem view of Drive is ever genuinely needed — and even then it would reuse the same Google Cloud OAuth client, keeping a single OAuth world.

The operating guide is docs/operations/google-workspace-read-api.md — it is the SSOT for how Vault access is configured (scopes, setup steps, security, revocation).

Considered Options

• rclone mount (original ADR-0001 choice): real filesystem view (ls/grep over the vault). Cons: FUSE service to operate and monitor (systemd, remount, token refresh); on-the-fly export latency and “empty” files for native .gdoc/.gsheet; cannot reach Gmail, Calendar or Contacts; was never actually deployed.
• Google Workspace API (chosen): native .gdoc/.gsheet reads, full-text search, Gmail/Calendar/Contacts in read-only, zero disk footprint, fine-grained OAuth scopes, one OAuth world shared with any future rclone use. Cons: no filesystem view; Google API quotas (comfortable for personal use).
• Hybrid (API now, rclone only if a filesystem need appears): the chosen staged path — API is the default, rclone stays a documented fallback rather than a deployed component.

Consequences

• Good: docs.ducatillon.net reflects the actual architecture — the Drive Bridge is the Workspace API, not a mount.
• Good: no FUSE service to operate, monitor, or troubleshoot; no rclone token to refresh.
• Good: Gmail/Calendar/Contacts become reachable in read-only, which the paperasse/dossier-tracking use cases require.
• Good: a single OAuth world (Google Cloud client hermes-workspace) — if an rclone mount is ever added, it reuses the same client and one revocation covers both.
• Trade-off: no ls/grep over the whole vault; exploration stays search-based (see the guide’s “no filesystem view” pitfall).
• Trade-off: API quotas and rate limits apply (comfortable for targeted personal use; full-Drive listing remains forbidden).
• References to the rclone mount in ADR-0001, ADR-0004 and the architecture pages are updated to point to this decision; the historical context (that ADR-0001 envisioned a mount) is preserved in the ADRs’ own history.