# Google Drive Plugin

Bring a Google Drive folder into a nest — Google Docs as markdown, Sheets as tables, text files verbatim — and search Drive live from the nest. Two ways to give it access: **connect a Google account** (two minutes, revocable from the nest) or a **Workspace service account** (no sign-in, for headless servers).

## What comes in

| Drive type | Lands as |
|---|---|
| Google Doc | markdown (Drive's native export) |
| Google Sheet | a markdown table |
| Google Slides | plain text |
| `.md`, `.txt`, JSON, YAML | verbatim |
| PDF, images, Office files | skipped — noted in the run log |

Folder structure is preserved under the target folder you choose. The first run walks the whole tree; later runs read Drive's **Changes** feed, so only edited files are fetched. Deleting a file in Drive never deletes the nest page. Pages edited in the nest are never overwritten.

## Setup — connect a Google account

The quick path. A server admin does step 1 once; anyone who can edit the nest does step 2.

**1. Register an OAuth client (admin, once per server)**

Server settings → Advanced → Plugins → *Connect accounts* shows the redirect URL to register — `https://<your nest>/auth/plugins/callback`. In Google Cloud Console → APIs & Services → Credentials, create an **OAuth client** of type *Web application* with that redirect URL, then paste its client ID and secret into the same settings panel. (`PUBLIC_BASE_URL` must be set on the server.)

**2. Connect it in the nest**

Nest → **Plugins** → Google Drive: set **Folder ID** (the id in the folder's URL), save, and press **Connect Google account**. Google asks for read-only Drive access; you land back on the Plugins tab connected. The nest keeps a refresh token and pulls with your permissions — you never paste anything. **Disconnect account** revokes it from the same panel; removing the plugin does too.

## Setup — service account

For a headless server, the `ctx` CLI, or when nobody should own the connection. You need a Google Cloud project and, for reading a user's Drive, Workspace admin access. About ten minutes.

**1. Create the service account**

In Google Cloud Console: enable the **Google Drive API** for the project, create a **service account**, and create a **JSON key** for it. Keep the file — you'll paste it into the nest.

**2. Give it access to the folder** — one of:

- *Share the folder* with the service account's email (the `client_email` in the key). Simplest; works for a single folder or shared drive.
- *Domain-wide delegation* — in the Workspace Admin console → Security → API controls → Domain-wide delegation, add the service account's client ID with the scope `https://www.googleapis.com/auth/drive.readonly`. The plugin can then act as any user in your domain.

**3. Connect it in the nest**

Nest → **Plugins** → Google Drive:

| Setting | Value |
|---|---|
| Service account key | paste the whole JSON file (not needed when an account is connected — a connected account wins) |
| Folder ID | the id in the folder's URL (`drive.google.com/drive/folders/<id>`), or a shared drive's id |
| Act as user | with domain-wide delegation: a user who can see the folder, e.g. `docs@acme.com` |
| Shared drive ID | only when the folder lives in a shared drive |
| Include subfolders | on by default |
| Max files per run | 500 by default |

Press **Test connection** — it reads the folder and reports its name. Choose raw or summary, a target folder, a pull cadence, then **Run now**.

## Searching Drive from the nest

With the plugin enabled, a nest search with *include live sources* also runs a Drive full-text search. Hits show under *Live sources · not governed* with a link to open the file in Drive and a **Promote** action that imports just that file, through review.

## Notes

- The key JSON is stored write-only on the server; it is never shown again after you save it.
- Only read scope is requested (`drive.readonly`). The plugin never writes to Drive.
- Docs are exported through Drive's markdown export; complex layouts (multi-column, drawings) come across as plain text.