gdoc Card

Gdoc Cards

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

Each synced Google Doc has a .gdoc.card plus a markdown file inside the card's .attach/ scope (e.g. Project_Notes.attach/Project_Notes.md). The content.ref: field points at it.

Not to be confused with .doc.card — that's the generic in-box document type with no upstream sync.

Editing

Edit the .md file and commit. On the next sync the change pushes back to Google Drive (markdown is converted to Doc format on the server). 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).

Conflicts

If the upstream Doc was edited in Drive between your last pull and your push, the card status becomes conflict and the upstream version is written next to the local .md as {basename}.remote.md (inside the attach scope). Resolve by merging the two files, deleting the .remote.md, and committing — the next sync will push the resolved version.

Comments

Collaborative feedback from the upstream Doc 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 the .md does NOT write comments back upstream (a push may even orphan the upstream anchors). Read it to understand reviewer feedback; don't expect changes to round-trip.

Lossy content

The lossy: field enumerates features in the upstream Doc that don't survive markdown export (footnotes, embedded images, equations, suggestions, complex tables). When present, pushing local edits will replace those features with the markdown body — destroying them. If lossy is non-empty and a push is intended, surface the loss to the user before committing. (Comments are handled separately via comments.ref: above, not counted here.)

Moving docs

Moving the card moves its attach scope (and the .md 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.