sheets-readonly git:20260928.ccf35a8A

Immutable. This exact content never changes and is served at /api/v1/blob/a7681bd8e36fbded.

---
name: sheets-readonly
description: Read-only Google Sheets access for bounded context pulls. Trigger when a Google Sheets URL or spreadsheet ID needs to become compiled context. Executable truth lives at connectors/sheets.py; this skill is a signpost, never a second implementation.
---

# sheets_readonly — signpost to connectors/sheets.py

The executable is the specification. Run it; do not reimplement it.

## The three moves

1. Identity and mint (one-time, interactive):
   `python connectors/sheets.py`
   Prints the OAuth wiring status (credentials.json path, its project_id,
   token path) and, in a real terminal, mints ~/.config/pipulate/sheets_token.json
   via the browser handshake. After that, every run is headless.

2. LIST with size gauge:
   `python connectors/sheets.py "<URL-or-ID>"`
   Every tab's rows x cols x ~cells prints BEFORE any fetch; overflow-shaped
   tabs are flagged. A #gid= fragment in a pasted URL selects that tab and
   performs a bounded fetch of it directly.

3. Bounded FETCH:
   `--sheet "<Tab>"` (row-bounded server-side) or `--range "'Tab'!A1:F50"`,
   capped by -n/--max (default 25), `--format tsv|json|markdown` (tsv default).

## Rules inherited from the connector contract

- THE PROBE ECONOMY RULE: read the LIST size gauge before any fetch.
- Client URLs and spreadsheet IDs live in adhoc.txt, never in tracked source.
- Auth is OAuth as YOUR account (gmail.py pattern): no sharing gate, no
  service accounts. A separate sheets_token.json exists because token files
  are scope-scoped — never reuse gmail's token.
- 403 SERVICE_DISABLED means the Sheets API toggle in the OAuth client's
  Cloud project (identity mode prints its project_id); any other 403/404
  means your own account cannot open that sheet.
- Errors and auth guidance ride stderr; stdout stays parseable.

See connectors/README.md for the full connector contract.