Types

A workbook is the container. Every other concept lives inside one. Workbooks have a permission model — owners, editors, viewers — and a unique URL.

A block is a unit of work in a workbook. Blocks come in eight types: markdown for prose, sql for queries, code for Python or JavaScript transforms, filter for declarative row filtering, chart for visualizations, spreadsheet for cell-level editing, document for long-form authoring, and mcp for invoking an external tool. Every block has an id, a position, a config, and zero or more outputs.

A source is a named, queryable output. Sources come from three places: data uploaded into the workbook, blocks that produce rows (a sql block writes its result to a source name), or remote tables exposed by a connected warehouse. Anything downstream — another SQL block, a chart, a filter — names a source as its input. The list of valid source names is the workbook’s catalog.

A run is a recorded execution of a block. Runs are immutable. They carry a status, an output, the inputs they were computed against, and the actor who triggered them. The workbook keeps every run, so you can open last Tuesday’s result and compare it to today’s.

An actor is the who behind every action. Actors are either users or agents. Every edit, run, lock, and presence ping carries an actor.

A lock is held by the actor who is currently editing a block. Other clients see a lock badge and lose their edit affordances on that block. Locks expire after about a minute of inactivity. Edits arriving without a matching lock token are rejected.

Presence is the live list of actors currently in a workbook. The web app shows presence as colored avatars in the header.