---
title: Documents Permission (what a plugin must ask before touching your writing)
---

# Documents Permission (what a plugin must ask before touching your writing)

## What it is

A plugin that wants to reach the documents you wrote in the app must now **ask**, and the card tells
you which of two things it wants.

## Where to find it

**Where you see it:** the permission card when you install or re-approve a plugin. The card lists
everything that plugin is asking for, and approving it is what grants the ask.

A plugin you already have, once it begins declaring these permissions, shows the same card as a
**"Needs your permission"** prompt with a Re-approve button the next time you open it.

## How it behaves

### The two levels

- **Read your documents** — open and search everything you have written, and publish a
  document to a Google account you have connected.
- **Create, edit and delete your documents** — change or permanently remove anything you
  have written, including restoring an older version over your current one.

Deletion is named in the **title** of the second one, not buried in the small print, because
it is the part you cannot undo. Publishing is named in the first one for the same reason: it
sends a document out of the app, which "open and search" alone would not have told you.

There is no separate delete-only level. A plugin that can overwrite a document with nothing
has already destroyed it, so a third level would suggest a protection it could not deliver.

### Why the AI Writer will ask you to re-approve it

The Writer has always been able to create, edit and **delete** your documents. It just never
had to say so — its permission card was silent about it.

Now it declares what it uses, so you will see a **"Needs your permission"** prompt with a
Re-approve button the next time you open it. Approving restores it exactly as it was. The
prompt is the point: you are seeing, once, what it could always do.

### What this does NOT do yet

**No third-party plugin can reach your documents.** The Writer is still the only plugin
allowed near them, enforced separately from the permission.

Opening that door to other plugins is a deliberate later step. Splitting it this way means
the honesty arrives first, on its own, without changing who can actually get in.

## For agents

A plugin author declares what the plugin uses in `manifest.json`:

```json
{ "permissions": ["documents.read", "documents.write"] }
```

Each method is checked individually — reading needs `documents.read`, and creating, editing,
moving, deleting or restoring needs `documents.write`. AI-assisted editing keeps needing the
existing `ai` permission, because it spends the user's money.

Note the published plugin SDK does not yet carry these, and a third-party plugin cannot use
them until the separate step above lands.

Contract: [plugin-core-data-permission-contract.md](../../.claude/memory/contracts/plugin-core-data-permission-contract.md)

## Related

This is one of the permissions a plugin asks for on the same card as
[plugin-shared-signin.md](plugin-shared-signin.md), which covers the shared browser session a plugin
can request instead. Which plugins can be installed, and what the consent card looks like in
general, is [plugin-marketplace.md](plugin-marketplace.md). The documents themselves, and the Writer
that owns them, are described in [ai-writer.md](ai-writer.md).