# Decks: instructions for AI agents

Your person has asked you to help edit presentations at https://decks.gszep.com.
You act for them: you can open and edit exactly the decks shared with their
Google account, at most as an editor. These steps work on Windows, macOS and
Linux, and with any agent that can run shell commands, whatever the model.

## 1. Check for Node.js

Run `node --version`. It needs to be 18 or newer. If it's missing, ask your
person before installing it: https://nodejs.org (or `winget install OpenJS.NodeJS.LTS`
on Windows, `brew install node` on macOS, your package manager on Linux).

## 2. Download the connector

Save https://agents.gszep.com/agents/decks-agent.mjs into your person's home folder:

- macOS or Linux: `curl -fsSL https://agents.gszep.com/agents/decks-agent.mjs -o ~/decks-agent.mjs`
- Windows (PowerShell): `Invoke-WebRequest https://agents.gszep.com/agents/decks-agent.mjs -OutFile $HOME\decks-agent.mjs`

Below, `CONNECTOR` means the full path of that file, for example
`/Users/ana/decks-agent.mjs` or `C:\Users\ana\decks-agent.mjs`.

## 3. Sign in as your person (once per machine)

Run `node CONNECTOR login`. It prints a short code and https://www.google.com/device.
Show both to your person and ask them to open the link, sign in with the Google
account the decks were shared with, and enter the code. The command finishes by
itself once they approve. Then `node CONNECTOR decks` lists the decks you can reach.

## 4. Use it

**If you can add MCP servers** (Claude Code, Codex, OpenCode, Cursor, the Claude
desktop app and most others), add a local stdio server named `decks` with command
`node` and arguments `CONNECTOR` and `mcp`. The usual JSON form is:

```json
{ "mcpServers": { "decks": { "command": "node", "args": ["CONNECTOR", "mcp"] } } }
```

Or by command: `claude mcp add decks -- node CONNECTOR mcp`, or
`codex mcp add decks -- node CONNECTOR mcp`. On Windows, write the path in JSON
with forward slashes or doubled backslashes. Restart or reload your MCP servers.

**If you can run commands but not add MCP servers**, call the tools directly:

```sh
node CONNECTOR tools
node CONNECTOR call list_decks
node CONNECTOR call read_slide documentId=DOC slide=title locale=en
node CONNECTOR call update_catalog_text documentId=DOC locale=en key=KEY "expectedCurrent=OLD TEXT" "value=NEW TEXT"
```

**If you can't run commands at all** (a plain chat window), stop here and tell
your person: they can edit directly at https://decks.gszep.com, and you can help
by drafting the new wording for them to paste in.

If you work in a sandbox with limited internet access, it must reach
agents.gszep.com, decks.gszep.com, oauth2.googleapis.com and www.google.com.

## Tools

- `list_decks`: decks shared with your person, with document IDs and your role.
- `get_presentation`: title, slide order and languages of one deck.
- `read_slide`: one slide's HTML and its text keys in a language.
- `read_styles`: the deck's stylesheets, to reuse its classes and colour tokens.
- `update_catalog_text`: replace the text of one key.
- `write_slide`: create or rewrite a slide (a full HTML document with its text
  in `strings`); new slides go at `position` (0 = first).
- `set_slide_order`: reorder slides, or leave some out to remove them.
- `read_guidance` / `write_guidance`: the design guidance the editor checks against.
- `write_editor_tool`: add a button to the browser editor's tool sidebar for your
  person; each person must enable it before it runs.

Every deck tool takes the `documentId` from `list_decks`. Slides can include
`<style>` blocks; scripts don't run.

## Policy

- **People's edits win.** Anything a person edited in the editor (text or an
  element) is protected: the server refuses to change it, and a slide holding
  it can't be removed. Everything else is yours to change. Don't work around
  the protection; tell your person what you would change and let them decide.
- Read before you write. Pass the exact text you read as `expectedCurrent`. If
  someone changed it meanwhile, read the slide again instead of retrying blindly.
- Change one piece of text at a time and tell your person what you changed.
  Collaborators see your edits live.
- You only have your person's access. If a deck is missing, ask them to have it
  shared with their Google account.
- Your person's email is used only to sign in and show who edited what:
  https://gszep.com/privacy.