Files
PaperClipAI/doc/memory/google-connector-memory.md
T
DottaandClaude Opus 5.5 12cb18e17d docs(connections): Google Workspace approval checklist, code-fix plan and working memory (#21996)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The built-in Google Workspace connector lets agents read and write
Gmail, Drive, Docs, Sheets, Slides and Calendar data
> - The connector stays behind an experimental setting until Google
approves its data access and the security assessment is accepted
> - The approval work has many steps, and the decisions behind them were
spread across chats and private notes
> - This pull request adds one checklist, one code-fix plan and one
temporary working-memory file for that effort
> - The benefit is that contributors and agents share one source for the
scope contract, the decisions and the remaining work

## Linked Issues or Issue Description

**Type of issue**
Missing documentation for an in-progress effort.

**Description**
The Google Workspace connector needs Google approval before it can go to
all users. There is no single document that lists what "approved and
released" means, which code changes must land before submission, or the
decisions taken so far (launch transport, owner, test instance, 14-scope
contract).

**Proposed change**
Add a production and approval checklist, a code-fix plan for section 2
of that checklist, and a temporary working-memory file. Keep
identifiers, credentials and review correspondence out of the public
repository.

## What Changed

- Added `doc/plans/2026-11-17-google-workspace-production-checklist.md`:
the "done means" criteria, the 14-scope contract, and checklists for
decisions, baseline, product and code, policy, security assessment,
reviewer environment, live acceptance, demo video, submission, release
and ongoing work.
- Added `doc/plans/2026-11-17-google-workspace-code-fixes.md`: ten
ordered code fixes (disclosure in the picker, scope lock to 14,
`gmail.modify` removal from the managed client, injection screening
check, revoke on last disconnect, retention audit, scan findings, gate
removal, REST-backed tool set, scope cleanup). Each item is marked
confirmed or to check.
- Added `doc/memory/google-connector-memory.md`: a temporary file with
decisions, open questions, environments, Google app layout, scopes,
review history and privacy-policy gaps. It says to delete it once the
connector is released.

## Verification

- Docs only. No code, schema or test changes.
- Read all three files before the push and confirmed that they contain
no passwords, client IDs, client secrets, project numbers or review
login codes.
- Relative links between the three files and to
`doc/connections/GOOGLE-WORKSPACE.md` resolve in the repository.
- CI checks on this PR.

## Risks

- Low risk. Documentation only.
- The plans describe intended work. Some items are marked "to check" and
can change after the code is traced.
- The working-memory file is temporary and must be deleted after
release.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`, Anthropic), used through Claude
Code with tool use (shell, git, GitHub CLI) to commit the files and open
this PR.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 06:57:30 -06:00

7.5 KiB

Google connector working memory

Temporary. Holds the decisions and details we keep needing while the built-in Google Workspace connector goes through Google approval and into production. Delete this file once the connector is approved and released.

This repository is public. Keep passwords, client IDs and secrets, project numbers, review login codes and review correspondence out of this file; they live in the private operator handoff.

Related: production checklist, code-fix plan, connector doc.

Last updated: November 17, 2026.

Decisions

Date Decision Detail
Nov 17 Owner for everything is Dotta Submission, security, privacy and release.
Nov 17 Launch on our own tools over Google's REST APIs Google's hosted Workspace MCP servers are still Developer Preview and cannot be offered to the public. We build our own tool set for agents that have this connector.
Nov 17 The REST tool set must be swappable for Google's MCP later Same tool names, inputs and results as Google's MCP tools, so switching back is a change of endpoint, not a rewrite.
Nov 17 The REST tool set lives in its own folder Nothing Google-REST-specific leaks into shared code; removing it later means deleting the folder and flipping one registration. Follow the boundary-discipline principle and rules/module-boundaries.mdc.
Nov 17 Engineering test instance moves to staging Create googletester.staging.paperclip.app; staging is far easier to deploy to.
Nov 17 Scopes must line up everywhere What the picker asks for, what the code accepts, what the Cloud broker allows, and what the Google Console declares are the same 14 scopes.
Nov 17 Assessment prep starts before Google asks Run the scans and fix findings now; the formal assessment starts on Google's notice.

Still open

  • What we send to the reviewers. Not decided: the new staging tester or something else. Whatever it is must use the separate Google app (below).
  • Privacy policy edits (see "Privacy policy" below).
  • Which security lab to use, and the budget.
  • Whether Google accepts the AI-agent client setting on a client that calls the REST APIs rather than MCP. To check before the staging tester is wired.

Environments

Name Address Notes
Earlier tester googletester.paperclip.app (company prefix GOO) On production. Used for earlier tests. Hard to deploy to; do not build on it further.
New tester googletester.staging.paperclip.app To be created on staging. Engineering qualification happens here.
Test 02 In the private handoff Staging stack used for the October proof. Holds Dotta's own Gmail grant, so not for reviewers.
Reviewer destination Undecided See "Still open".

Reviewer login: Google's reviewers could not use our normal sign-in, so we gave them a custom password for the Paperclip login. Any reviewer environment needs that again. The password itself goes only through the review channel.

Google apps (Cloud projects)

App Purpose State
Original production app The one under Google verification It was released to more than 100 users while unverified and hit Google's 100-user cap. Nobody new can sign in or sign up with it until it is verified.
New app for us and the tester Created so we and Google's reviewers can sign in at all Separate Cloud project, set to In Production. Google asked for exactly this in its October 7 message. The reviewer environment must use this app's client.
  • The client labelled "managed staging" belongs to the original production app, despite the name. A flow that used it does not satisfy Google's separate-project request.
  • Verification is of the original production app; the new app only gives reviewers a way in.
  • With the REST transport, each project needs the Gmail, Drive, Docs, Sheets, Slides and Calendar APIs enabled, not the MCP APIs.

Scopes

One connection, three groups, 14 scopes across all modes (9 for the default all-read-and-write selection, 8 for all read-only). Prefix: https://www.googleapis.com/auth/.

Group Read only Read & write
Gmail gmail.readonly gmail.readonly, gmail.compose
Drive, Docs, Sheets, Slides drive.readonly, documents.readonly, spreadsheets.readonly, presentations.readonly drive.readonly, drive.file, documents, spreadsheets, presentations
Calendar calendar.calendarlist.readonly, calendar.events.readonly, calendar.events.freebusy calendar.calendarlist.readonly, calendar.events
  • Restricted (trigger the security assessment): gmail.readonly, gmail.compose, drive.readonly.
  • Gmail write means drafts only. gmail.compose would let an app send; our tool list has no send action. Never say the scope itself prevents sending.
  • Out of scope: Chat, Contacts, Directory, cross-service Search. Not in the picker, the request, the tools, the docs or the submission.

Known mismatches to clean up:

  • The workspace.all profile in code is still the 21-scope legacy union, and the server accepts any subset of it.
  • The standalone Gmail card offers a Paperclip-managed "Read & archive" option that requests gmail.modify (restricted, not in the submission).
  • What the Cloud broker allows and what the Google Console declares have not been compared with the 14 yet.

Google review history

  • September 30: we sent a revised submission.
  • October 7: Google replied. Reviewers could not sign in because of the 100-user cap, and the video did not show gmail.readonly working end to end. They asked for a separate test project set to In Production, working reviewer login, and a new video showing a full email in Paperclip and then the same email in Gmail.
  • No newer message from Google as of November 15.
  • Branding was verified at the last Console check; data access was still under review. Not rechecked since.
  • The older videos and replies describe separate per-service connectors and removed services. Do not reuse them.

Privacy policy

  • Lives in the paperclip-website repository at web/app/privacy/page.tsx, published at https://paperclip.ing/privacy. Last updated July 23, 2026.
  • It already has what Google looks for first: a Google user data section (4.1) with the Limited Use statement and links to Google's policy.
  • Gaps found November 17, not yet fixed:
    • It does not say that Google content is sent to AI model providers to carry out tasks. It only names "cloud hosting and infrastructure providers".
    • It says connected-account data is kept only while the connection is active. In the product, email and file content that an agent read stays in task and run history after disconnect.
    • It says "read or send access to Gmail". We create drafts and do not send.
    • It names connect.paperclip.ing as the sign-in path; check that this matches the current flow.
    • It gives no steps or timeline for deleting data.

Other things to remember

  • Security assessment: Google assigns the tier, we choose and pay the lab, and it repeats every 12 months.
  • The connector is behind the default-off enableGoogleWorkspaceConnector experimental setting until Google approves.
  • The synthetic test email has the marker PAPERCLIP-QA-BODY-20261028.
  • The October 31 live evidence predates many changes to the sign-in code and must be redone.