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:

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.