Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# gsheet Card

# Gsheet Cards

**Location:** Anywhere in the box, commonly `_content/drive/`.

Each synced Google Spreadsheet has a `.gsheet.card` metadata file plus
an attach scope (`{basename}.attach/`) containing one JSON file per
sheet tab. The `sheets:` field lists `{ref, title, gid}` entries
pointing into that scope.

## Data format
Each tab is a JSON file with one row per line. Cell values are:
- Plain values: strings, numbers, booleans, or null
- Formula cells: `{"f": "=SUM(A1:B1)", "v": "$42.00"}` — `f` is the
  formula, `v` is the computed display value

## Reading spreadsheet data
1. Read the card to understand structure: title, tabs, Google link
2. Read the JSON tab files — plain values are bare, formula cells have
   both the formula and computed result

## Editing spreadsheet data
Edit the JSON file directly and commit. For plain cells, just change
the value. For formula cells, edit the `f` field (the `v` field will
be updated on next sync). On next sync (`bbx wakeup` or
`bbx drive sync`), local changes are pushed to Google Sheets. Do NOT
modify the card frontmatter — it is managed by the connector — with one
exception: `contains:` is agent-owned and survives sync; set it freely
(`bbx contains update`).

## Comments
Collaborative feedback from the upstream spreadsheet is captured as a
sidecar inside the attach scope (`{basename}.comments.json`), referenced
by the `comments.ref:` field when present. It holds the full comment
thread: content, author, timestamps, resolved status, the anchored text,
and replies. This is read-only context regenerated on each pull — editing
or pushing tab data does NOT write comments back upstream. Read it to
understand reviewer feedback; don't expect changes to round-trip.

## Moving spreadsheets
Moving the card moves its attach scope (with the tab data inside)
atomically — the `drive-id` field maintains the link to Google Drive.

## The `contains:` field

Give this card a one-sentence `contains:` — the prime retrieval field for
`bbx search` and listings. How to write a good one (carry the information when
it's concise, never a list of parts, under 200 characters) is in the agent
guide's ABOUT_CARDS section.