Cattalog

List the catalogues in this workspace, newest-edited first. Returns each one's id, name, tags, when it was last edited and its current contentRevision. Start here: every other document tool takes an id from this list. Archived catalogues are excluded unless you ask for them.

list_documents

Every data source and media source in this workspace, whether or not it is attached to anything. This is what you call before attach_data_source or attach_media_source — list_data_sources and list_media_sources show only what one catalogue already has.

list_workspace_sources

Replace the file behind an existing data source, keeping its id. Every catalogue already reading it keeps its attachment and its variable, so a transform reading files['products'] goes on working — which is the whole reason to use this rather than creating a second source. Same base64 limits and the same cell-image caveat as create_data_source. The old stored file is deleted; previous cell-image bindings are cleared and their deletion locks are released.

replace_data_source

Render pages of a catalogue in headless Chromium and return them as images — the same layout pass the PDF export uses, so what you see is what prints. This is how you check your own work after an edit. Ask for up to 6 pages in ONE call: a call paginates once, up to the highest page requested, so capturing pages 55-58 together costs a quarter of what four separate calls do. Pages that do not exist are reported in "missing" rather than silently dropped. Screenshots come from what is STORED — make your edit with update_file or the component tools first. Rendering may fetch external assets referenced by the catalogue and writes render diagnostics.

screenshot_pages

Create a data source from a CSV or spreadsheet you provide as base64. Best for data you have generated — a CSV you assembled from a transform, an export you built. **The bytes travel through your own context**, roughly four characters per three bytes, so keep it under about 256 KB; a spreadsheet that already exists on disk is far cheaper to upload in the app. Hard limit 4.0 MB. Creating it does not attach it — call attach_data_source next. NOTE: pictures embedded in spreadsheet cells are NOT extracted on this path; that only happens when a workbook is uploaded through the app.

create_data_source

Upload one image into a media source, as base64. Best for something you generated — an SVG you wrote, a small chart. **The bytes travel through your own context**, so keep it under about 256 KB; a folder of photographs is far cheaper to drop into the app, which uploads them in parallel without them passing through a model at all. Hard limit 4.0 MB. Any image type except GIF, which has no meaning in a print layout.

upload_media_file

Report the account, workspace, role and permissions this access token resolves to. Takes no arguments. Use it to confirm the connection is working and to find out which workspace you are about to act on.

whoami

Create one or more reusable components on this document. Prefer creating components first and then composing them in template.hbs. Creating a component does NOT put it on a page — the entry has to place a page layout for anything to render. Every component is created unlocked; locks are the user's to set. The whole batch is validated together, so a parent and the child it calls can be created in one call regardless of array order, and either everything commits or nothing does. Changes are saved to the catalogue and can queue a thumbnail render that fetches external assets referenced by its content.

Delete one component. Refused if anything still calls it — including a component the entry cannot reach — and refused if it is locked or protected. Remove the {{> name}} calls from its callers first, then delete. Nothing is ever cascade-deleted and no caller's source is edited on your behalf. Changes are saved to the catalogue and can queue a thumbnail render that fetches external assets referenced by its content.

Search for files by name (case-insensitive partial match) within a media source. Returns matching files with their full paths and URLs, one page at a time: at most 100 matches per call by default (500 max), with "totalMatches" reporting the full count and "nextOffset" continuing when "hasMore" is true. Narrow the query rather than paging through a broad one. Use this when you need to find a specific image by name across all folders.

Search for folders by name (case-insensitive partial match) within a media source. Returns matching folders with their paths, one page at a time: at most 100 matches per call by default (500 max), with "totalMatches" reporting the full count and "nextOffset" continuing when "hasMore" is true. Use this when you need to locate a specific folder.

List all data sources attached to this document, including their variable names, column headers, and row counts. A source whose spreadsheet had pictures embedded in its cells also reports "cellImages": those cells hold [cattalog-media-ref:...] tokens naming images in a media source, and the report says which media source variable resolves them — or that it is not attached yet.

List files and folders at a specific path within a media source, one page at a time. Returns names, urls, mimeTypes, and whether each entry is a folder. Use path "/" for root level. Entries are paged folders-first under a single cursor: at most 100 per call by default (500 max), and when "hasMore" is true you call again with the returned "nextOffset". "totalFolders"/"totalFiles" always report the full counts at the path. Use this to browse the folder structure of a media source.

List all media sources attached to this document, including their variable names, folder/file counts, and top-level structure. At most 50 top-level folder names are listed per source; use list_files_in_media_source on path "/" to browse the rest. Use this first to discover what media is available.

Inspect this document's components. mode "list" returns summaries — name, type, what each calls and is called by, whether the entry can reach it, its explicit lock and any inherited protection — without any source. mode "read" returns one component's owned source. Read before editing: a summary is not the code, and protection decides whether an edit will be accepted at all.

Read rows from a data source, one page at a time. Returns at most 100 rows by default (500 max, and fewer when the rows are wide). When "hasMore" is true, call again with the returned "nextOffset" to continue. Only use this when the preview is insufficient — prefer read_data_source_preview, and prefer run_data_transform over paging through a whole sheet to inspect it.

Read the first 10 rows of a specific data source by its variable name. Use this to understand the structure and sample data before writing code.

Read the current content of one of the four root files. Use this before making edits to ensure you have the latest user-updated content. The returned contentRevision is the token to pass back to update_file and to the component tools — it is how a write proves it was built from the source that is actually stored.

Execute a data.transform.js script server-side and return its output along with any console.log/warn/error messages. Use this to test and debug your data transform code before committing it with update_file. The code must use the same `export default function dataTransform({ files, mediaSources }) { ... }` signature. The output is a SHAPE CHECK, not the data: anything larger than a few thousand characters comes back summarised — arrays as a length plus the first few items, objects cut at 20 keys and 3 levels deep, long strings cut — with a "note" saying so. Console output is capped the same way. Use it to confirm the structure and spot errors, not to read a catalogue.

Change the owned source or metadata of existing components. Every source part you provide is COMPLETE content, not a diff; an omitted part is left unchanged and an empty string clears it. Name, type and lock state cannot be changed. A protected component is refused with the name of what protects it — do not work around that by cloning it or overriding it from elsewhere; say so and let the user unlock it. Changes are saved to the catalogue and can queue a thumbnail render that fetches external assets referenced by its content.

Update one of the four root files. Always provide the COMPLETE file content, not a partial diff. The content is parsed before it is stored — if it has a syntax error, or if the composition is invalid, the file is NOT updated and the error is returned to you. Otherwise it is reformatted, committed, and applied to the live editor immediately, so you can screenshot the preview afterwards to check your work. Only these four names are accepted: a path like components/product-card/template.hbs is not a file and cannot be written here — use update_component. Changes are saved to the catalogue and can queue a thumbnail render that fetches external assets referenced by its content.