connect-google

name	connect-google
description	Use when the user needs to set up or restore Google authentication for Famulus. Do not use for ordinary Google-service operations.

Generated from blueprint.yaml. Do not edit this block by hand.

Executable Interfaces:

Call famulus.invoke with required caller (caller skill), interface, version, and arguments; optional dry_run defaults to false. Compact uses ordered positionals plus an option mapping; ordered raw argv uses positionals: [] plus every argv token in list options. Never mix forms.

• connect-google._rtx.interface.bind-credential-file — Retry service-owned binding with an existing credential descriptor; never invoke OAuth authorization.
  • Caller: connect-google
  • Version: 1
  • Alternative: default Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {"--allow-account-change": "comma-separated-list", "--credential-file": "path", "--gmail-nickname": "name", "--home": "dir", "--services": "comma-separated-list"}, "positionals": [], "stdin": null} Required options: ["--credential-file", "--home", "--services"]; positional arity: 0..0; stdin: forbidden
• connect-google._rtx.interface.client-status — Report whether the canonical Google Desktop OAuth client is missing, valid, invalid, or needs migration from plaintext, including whether its opaque client-secret reference resolves, without exposing secrets.
  • Caller: connect-google
  • Version: 1
  • Alternative: default Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {"--home": "dir"}, "positionals": [], "stdin": null} Required options: []; positional arity: 0..0; stdin: forbidden
• connect-google._rtx.interface.connect-services — Run one combined OAuth authorization and bind its new credential file through the fixed service-owner map.
  • Caller: connect-google
  • Version: 1
  • Alternative: default Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {"--account-hint": "email", "--allow-account-change": "comma-separated-list", "--callback-port": "port", "--gmail-nickname": "name", "--home": "dir", "--no-open-browser": true, "--services": "comma-separated-list"}, "positionals": [], "stdin": null} Required options: ["--home", "--services"]; positional arity: 0..0; stdin: forbidden
• connect-google._rtx.interface.install-client — Validate a Google Desktop OAuth client JSON and atomically install a private canonical copy.
  • Caller: connect-google
  • Version: 1
  • Alternative: default Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed. {"options": {"--from-json": "client-json", "--home": "dir", "--replace": true}, "positionals": [], "stdin": null} Required options: ["--from-json"]; positional arity: 0..0; stdin: forbidden

Instruction Interfaces:

These are LLM-readable instruction surfaces. Read and follow them directly; do not invoke the MCP server for them.

• connect-google.source.instructions-connect-services.interface.connect-services@1 — Install or reuse a Google Desktop OAuth client and hand selected Google services to their owning skills.
• connect-google.source.instructions-create-client.interface.create-client@1 — Guide a user through creating and privately downloading a Google Desktop OAuth client for selected Famulus services.
• setup-python-environment.interface.repair-selected-packages@1 — Repair the core or one caller-owned package declaration in the exact selected Python environment without MCP.

Skill: connect-google

This is the shared router for Google OAuth-client preparation.

Before client inspection, authorization, or service binding, use the host-loaded setup-python-environment.interface.repair-selected-packages procedure for feature connect-google and its exact declaration ["keyring"]. Complete the initial fingerprint, pip and target checks, conditional repair, and byte-equal final fingerprint; stop without Google or credential activity on any failure. For each explicitly selected service, run that same procedure separately for its fixed owner and exact declaration ["keyring"] before invoking it: Drive is cloud-files, Calendar is online-calendar, and Gmail is email-client. Do not inspect or repair an unselected owner. A later satisfied declaration is a no-install result, so shared keyring is installed at most once.

1. Use connect-google._rtx.interface.client-status before asking the user for a file.
2. If the stored client is valid, use connect-google.interface.connect-services.
3. If no valid client is installed and status reports legacy candidates, ask before importing one; when candidates differ, ask which one to use. A confirmed candidate routes to connect-google.interface.connect-services.
4. If no candidate is selected, explain that Famulus needs a Google Cloud project to register its Desktop OAuth client. Present the two options:
   • use the developer's experimental Google Cloud project; or
   • use their own Google Cloud project. Then ask whether the Google account they want to connect has been added by the developer to the experimental project's OAuth test-user list.
   • If yes, ask for the local path to the Desktop OAuth client JSON provided by the developer, then route it to connect-google.interface.connect-services. If the user was added but does not have the file, tell them to obtain the JSON from the developer; never request its contents.
   • If no, route to connect-google.interface.create-client. After the user creates their own project and downloads its Desktop client JSON, obtain its local path and continue through connect-google.interface.connect-services.
   • If the user is unsure, tell them to confirm with the developer; do not assume enrollment.

When a user without a client asks why this step cannot be automated, explain that Google requires every application reaching an account to be registered in a Cloud project, and that Famulus runs locally with no server to hold a shared identity. Bundling one client would put every user under a single app identity, where one user's misuse suspends the app for everyone. Reproduce the following two sentences verbatim; do not paraphrase, soften, or add specifics such as costs or timelines:

Drive, Calendar, and Gmail require Google's restricted scopes, and verifying an app for those requires an annual third-party security assessment. Until an app passes it, Google's OAuth user cap allows at most 100 manually listed test users, and their refresh tokens expire after seven days, so those users must authorize again.

Owning a project removes that cap for its owner; using the developer's experimental project is subject to it. instructions/create-client.md repeats the second sentence at the configuration step; keep both copies identical.

Apply the same route to initial setup and reconnect requests. Recommend Drive, Calendar, and Gmail while allowing the user to choose a subset. The connection route creates one timestamped credential file and binds that exact path through service-owned machine interfaces. Treat only complete: true as success; retry an incomplete binding with bind-credential-file and the same file.

Never commit, publish, quote, or log the client JSON. Do not request, inspect, or move service access tokens, refresh tokens, account records, or user data. The deterministic coordinator invokes only the declared service-owned binders.

@./personal-preferences/default.md