When to use: add a diagram to a page. Works for flowcharts, sequence, class, ER, state, and XY chart diagrams. Pick this over manual SVG or nested divs when the thing you want is conceptually a graph.

Renders Mermaid syntax to durable inline SVG and injects it into the page HTML. The answer gives the document's reading path in Maket and the rendered diagram as an inline image (at most 1600 px and 1 MB of base64; beyond a 2:1 ratio, its top or left part). The source and semantic rendering choices stay on the wrapper so charte changes can rerender the diagram. The diagram scales with its wrapper (width/height drive the frame, not the SVG itself). If dataId already exists, the diagram is replaced in place — idempotent edits. A document charte is applied automatically through canonical diagram tokens and documented color/font fallbacks. tokenRefs selects any existing charte token explicitly; direct safe values take final precedence. Density controls are supported for flowchart and state diagrams by the current renderer. Source-level Mermaid styling directives are rejected; use charte tokens or safe diagram options. Header on its own line: graph TD\n A-->B (NOT graph TD; A-->B)

When to use: manage the asset library (images). view → meta is a required two-step: meta refuses any write without the context_token from the latest view call — proof the image was read before metadata is attributed.

Images live on disk under the assets dir; metadata lives in the store; both move together. list — list assets grouped by category; flags items missing metadata. view — load an asset inline (text + binary image) and return its context_token. MUST be called before meta. meta — write/update metadata; rejects without a current context_token. import — copy an asset in via url, path, or register-mode (filename-only for already-present files). Auto-optimises + thumbnails. delete — remove the file, thumbnail, and metadata row.

When to use: manage brand style guides (chartes). view is a prerequisite for any charte-aware HTML edit — it returns the context_token required by maket_html set/patch.

Design tokens become CSS variables (--charte-color-primary, etc.) injected into every page. Voice and rules guide content composition. maket_mermaid automatically consumes canonical diagram tokens and documented fallbacks from color/font groups; its tokenRefs option can target any existing safe token explicitly. list — list all chartes with a short colour-palette preview. view — read one charte; returns tokens, voice, rules, and context_token. set — create or overwrite a charte. delete — remove a charte.

When to use: manage data collections used by page placeholders.

Collections are typed by JSON Schema and contain ordered members. A page can be bound to one collection; rendering then produces one page per member. list — list collections. view — read one collection with fields and members. create — create an empty collection from a JSON Schema. validate_schema — check a schema against existing members without saving. change_schema — apply a schema only when existing members validate. add_row / update_row / delete_row — edit collection members. delete — remove a collection. bind / unbind — bind or clear a collection on a document page. cursor — read or move a bound page's preview cursor (doc + page required). Without mode/row it reads; with mode (template|rendered|all) and/or row (member id or 1-based number) it moves. The human's live canvas, this cursor and the exports all share this state.

When to use: attach durable data and immutable snapshot history to one living document.

Document state is separate from collections and mail merge. A state-backed document renders Mustache variables, sections, inverted sections, and loops from its latest revision. Every mutation stores a complete validated schema + data snapshot. History is unbounded unless the document has a revision retention. The page interface is HTML/CSS, a JSON Forms template, or HTML embedding the current form at . Configure the form with maket_page set_form. HTML uses display-only Mustache plus explicit data-maket-bind controls. JSON Forms uses the document-state JSON Schema and data, with an optional UI schema. Both formats resolve to the same JSON Pointer patches and revisioned store. init — attach a schema and initial data to a static document (revision 1; no expected_revision). get — read the schema, the revision retention (retention, null when unbounded), and the current revision. update — append a complete state snapshot; expected_revision is required. patch — apply RFC 6902 JSON Patch operations; expected_revision is required. validate_schema — validate a proposed schema against current or supplied data without saving. change_schema — atomically replace the schema and append compatible data; expected_revision is required. history — list immutable revisions newest first. revision — read one revision. restore — append a new revision containing an older schema + data snapshot; expected_revision is required. set_retention — keep retention previous revisions besides the current one and delete older ones now and after every later write; 0 keeps only the current state, null restores unbounded history. Applies to Workspace items and collection projections too.

When to use: create and operate a Structured Workspace — a schema-driven collection of items, listed in an index and opened as Maket documents built from templates.

Method (full recipe: maket_learn action=topic topic=structured-workspaces): 1) create with a data_schema alone that has a required "id" property (string), one value per item: Maket identifies the items by "/id" — or declare another identity per collection, e.g. representation_schema={"collections":{"items":{"name":"Items","identity":"/code"}}} — and Maket writes the index, detail, card templates and the detail form itself, in the Workspace category; 2) add_item; 3) check, which must answer verdict ready. Inline template HTML (detailTemplateHtml, compactTemplateHtml, indexTemplateHtml, detailForm) or names of existing template documents are the optional second and third paths. Identity: every collection has an identity, a JSON Pointer to a required string or number property of its items (e.g. "/code"); without one, "/id" when the schema requires an id property. Its value, as a string, is the item id used everywhere (item=, documents, cursors) and is unique across the whole Workspace, all collections included; Maket never generates one. add_item refuses data without it, or a value another item of the Workspace already bears (invalid_record, naming that item); update_item refuses a change of it: delete and add the item again instead. The identity of a collection holding items cannot be changed. create and update_definition refuse a definition with errors (isError, one line per error with collection, path and fix) and keep the previous definition; allow_incomplete=true persists it anyway. add_item and update_item refuse data that breaks the schema with its path, rule and fix.

The data schema validates every item. The representation schema declares one or more collections; each collection owns its global template and binds concrete schema paths to compact and detail templates. The item source holds the item data; an item's document is created from its detail template when the item is opened or exported. Template-controlled pages are synchronized from the template; instance-owned pages remain in the same document. Reading items is a cursor query: view answers one batch of item summaries for one collection (collection, default the first) with next (an opaque cursor, absent once the listing is exhausted), total and the group counts. Pass text (searches searchFields, by default every text property, ignoring case and accents), filters ([{"field":"/status","op":"eq","value":"todo"}], op in for a list), sort ({"field":"/title","direction":"descending"}) and batch (default indexPageSize, 50; at most 500) to start a new query, which also becomes the window every client sees in the index. To read the next batch, pass cursor= with the same query arguments (the answer gives the call in more): it reads the source directly and never depends on the shared window: no item that existed before and kept its sort value is skipped or read twice, while an item whose sort value changes during paging may move across the cursor. There is no page number and no previous: a new query restarts from the first item. view with neither query nor cursor answers the first batch of the collection's own order. Optional collection grouping: groupBy is a JSON Pointer into item data (e.g. "/status"), groupOrder lists group values to place first, and pageSize (default 24) caps the compact cards per collection page. With groupBy, each item slot receives a group header followed by its cards and the collection document flows onto as many pages as needed; without it, the collection stays one page. Optional collection sort: sortBy is a JSON Pointer into item data (e.g. "/place") and sortDirection is "ascending" (default) or "descending"; cards are ordered by that value inside each group, or across the slot without groupBy, items without a value last and ties in item id order; without sortBy, insertion order stays. list — list Structured Workspaces, each prefixed with ready or incomplete. view — verdict and finding count first, then the definition, item counts, pinned items, owned documents, one batch of the collection window (see the cursor query above), and reading: the reading path of that collection's index in Maket. check — the doctor: verdict ready or not ready and every finding with severity, object, sentence, fix and next call. Never writes. create — create a workspace from a data schema, with an optional representation schema; refuses errors unless allow_incomplete=true. update_definition — validate and replace the data and/or representation contract, then update the item and index documents that exist; an erroneous definition is refused and the previous one kept unless allow_incomplete=true. add_item — validate data and write the item to its source under the id its identity property holds; its document is created when the item is opened. update_item — replace item data with optimistic revision control. delete_item — delete the item from its source, with its document when it was opened. sync_template — propagate current detail-template pages while preserving instance-owned pages. rename — rename the Workspace without regenerating owned documents. delete — atomically delete the Workspace and every document, state revision, and annotation it owns.

When to use: first call for any agent entering Maket; source of operational guidance for using Maket MCP tools correctly.

Returns structured Markdown inside MCP text content. It teaches agents how to operate Maket: workflow, HTML composition, chartes, diagram styling, collections, living document state, Structured Workspaces, review loop, and client installation. This is not the user-facing Help document opened from the Maket UI.

Actions: overview — short operating model. topics — list available topics. topic — read one topic with topic=.

When to use: manage page structure within a document — add, remove, rename, reorder, list. For page content, use maket_html instead.

Manage pages within a document. HTML can embed the current JSON Forms template at . add — append a page with html, json_forms, or both with one form slot; sets it active. remove — delete a page by 1-based index or name; refused if it's the last page. rename — rename a page by index or current name. reorder — move a page from one 1-based position to another; activePage adjusts. list — list pages with their template format; the active page is marked ●. set_form — replace the current form, preserving HTML with a form slot; without a slot, switch to a full-page form. get_form — read one page's JSON Forms template.

Note: charte compliance (token-literal colours, font-family, box-shadow) is enforced by maket_html set/patch, not by maket_page add. If the new page must match a charte, follow maket_page add with maket_html set to validate.

When to use: every persistent document-lifecycle operation — create, clone, rename, delete, list, update metadata, or move bundles in/out. For session-level actions (open a doc/page in the preview, inspect state, lock), use maket_workspace. For per-page edits use maket_page and for content use maket_html.

doc is the doc in scope for every action except list. name only appears when you need a NEW name (duplicate, rename).

Manage design documents (the workspace unit: canvas + pages + meta). new — create a blank document at doc; sets it active. Previous unsaved work is lost. list — enumerate saved documents: pinned documents first (most recently pinned first, marked 📌, with their category), then the other documents as a hierarchy of category paths. lookup — read-only identity of doc by exact name, Workspace documents included: JSON {name, id, revision (monotonic modification token), pageCount, dataModel, stateRevision (null without state)}. It never opens the preview nor changes the active document. When absent, the error lists near matches. link — return a reading path for doc, using its stable document id and configured browser base path. Prefix it with the reachable gateway origin. delete — remove doc permanently; refused if it's the only document left. duplicate — clone doc → name (format variants, A/B copies). rename — rename doc → name. meta — update doc's metadata: designNotes, teamNotes, rating, category, charte, responsive. The responsive flag applies to every browser-reader page while canvas/PDF keep authored dimensions. Owned Workspace templates accept responsive alone; sync_template propagates it. pin — pin doc at the top of the document lists (desktop library, Reader navigation, list). The most recently pinned document comes first; pinning an already pinned doc keeps its place. Allowed on locked documents. Workspace item pins appear under their collection in the Workspace sidebar; indexes and templates cannot be pinned. unpin — remove doc's pin; free documents return to their category and Workspace items disappear from the pinned shortcuts. export — write a portable .maket bundle to EXPORTS_DIR. By default the bundle embeds referenced asset binaries (images, SVGs) so it survives transfer to another machine or a fresh datadir. Pass include_assets=false for a lighter structure-only snapshot. Include doc for a single document, docs for a list, or omit both to export every document. Referenced chartes, collections, and current document-state snapshots (with their revision retention) are embedded automatically; revision history stays local. Override the filename with output. import — load a .maket bundle from input (absolute path or EXPORTS_DIR-relative). Documents land with conflict-renamed names; chartes and collections skip names that already exist. Current document-state snapshots initialize revision 1, and assets are restored to ASSETS_DIR with the existing collision rule.

When to use: set or update the canvas (physical frame) of a document — format, orientation, background, margins. Call this before adding content to a fresh doc, or when switching a doc between formats.

Coordinates are in mm. Paper sizes — A2=420×594, A3=297×420, A4=210×297, A5=148×210, A6=105×148, A7=74×105, A8=52×74. Screen sizes — DESKTOP=288×205 (1440×1024), TABLET=167×239 (834×1194), MOBILE=79×170 (393×852). AUTO — width in mm is required; each page height follows its content. Orientation is ignored. Use normal HTML flow rather than a fixed-height wrapper. Unspecified fields keep their current value.

When to use: read and write page HTML. Pick set for the initial skeleton, patch for iterative edits, get to read, check to measure overflow without writing.

Every visible element MUST have a data-id. Use flex/grid with mm units. When a charte is loaded, prefer var(--charte-*) tokens. The compliance check is narrow: it rejects (1) hardcoded colour literals that duplicate an existing charte token value (e.g. #2563EB when primary=#2563EB), (2) any hardcoded font-family when the charte defines fonts, (3) any hardcoded box-shadow when the charte defines shadows. Fresh colours that don't duplicate a token pass untouched. Layout override: data-maket-layout="ignore" excludes exactly one marked non-interactive leaf block from overflow, overlap, clipping, and margin checks. The block must have no child elements or text; controls, links, data-maket-bind and focusable/ARIA elements are ineligible. Reserve it for intentional non-content decoration after visual review. Add it only with maket_html action=patch using attr on an existing data-id; the enabling op must be the only op in that patch request. Set, insert, replace, and content HTML cannot introduce it. For a state-backed document, Mustache is display-only. The document must author editable controls and all their CSS explicitly: data-maket-bind supports for booleans, and for strings, for string enums (or for a string whose options come from a state list with data-maket-options="state.list"), and for the single-value editor; a bound button with data-maket-value="" (optionally data-maket-action="set") writes that value on click instead. Use state.foo at the root and relative foo inside state sections; never persist data-maket-path or other runtime attributes. set — REPLACE the full page HTML. Rejects the whole payload on any violation. Requires context_token when the doc has a charte. patch — apply ops by data-id: style/content/attr/insert/replace/remove/clone/moveTo. Violating ops roll back individually, the rest still apply. get — return current HTML; pass id= for a single element, format=text to strip tags. check — measure layout against the canvas + declared canvas.margins, and report page links that target a missing page; no side effects. The page is measured as readers see it: a state-backed page hydrated with the current document state (a JSON Forms page on its rendered form), a collection page with the member its preview cursor shows (first member otherwise), a Structured Workspace collection document with its items; a list that flows onto continuation pages is measured page by page; other pages as authored. The report's first line names what was measured. set and patch measure the same way. Returns a Markdown measurement report with physical canvas and content extents, root geometry, problematic addressable blocks, parent/canvas excess per side, clipping, and overlap pairs. Status: ✓ OK, ⚠ tight (block crosses a declared margin band — tighten or move into the safe zone before shipping), ⛔ overflow (block escapes the canvas, not shippable; pairwise overlaps between [data-id] blocks are reported under this same status), or ⛔ unchecked when headless validation could not run. On tight/overflow, the next: block points to a snapshot + targeted patch; unchecked is diagnostic-only to avoid blind retry loops. Page links: (canonical, 1-based page number) or navigates to that page of the same document in Canvas, Reader and viewer, and becomes an internal link in print and PDF. In the authoring Canvas a plain click selects the link for editing; ⌘-click (Ctrl-click elsewhere) follows it. The href is a literal: set and patch refuse Mustache in a page link.

When to use: every session-level interaction with the live workspace — open a doc/page in the preview, inspect a doc's current state, toggle its lock, and process the user-message queue. For persistent CRUD on documents (create, rename, delete, duplicate, meta, import/export) use maket_doc.

focus — open doc at page page in the live preview (sets active doc + active page). state — summarise doc's current state: canvas, pages with element counts and data-source cursors (collection · mode · row), charte, pending messages. lock — lock or unlock doc. When locked, every doc-scoped mutation refuses until it's unlocked. Pass locked=true/false, or omit to toggle. fit_view — zoom out the client to fit the whole workspace (same as the Maximize button). list_messages — return pending annotations as JSON. With doc, return only that document's messages; without it, return all document and workspace messages. Each message carries docName (or none for workspace scope), pageIndex and elementId for its anchor, text, ts; a note the person changed after sending also carries edited: true and editedAt (epoch ms) — act on the current text. ack_messages — drop the given ids from whichever bucket they live in.

When to use: view documents outside the agent. open flips the live preview URL into the user's browser; snapshot rasterises a single page to PNG at its true mm size; show puts pages in front of the user inside the conversation.

open — launch the live preview URL (localhost) in the default browser. No params. snapshot — render a page via headless Chromium. Returns the full-size PNG as a file path on disk, the page's reading path in Maket, and the image inline (at most 1600 px on its longest side and 1 MB of base64, downscaled when larger; beyond a 2:1 ratio, the top or left part of the page). On hosts that render MCP Apps, the Maket reader also opens on that page. show — on hosts that render MCP Apps, open the Maket reader in the conversation: doc, pages ("all", 3, "3-5" or [1,4]), layout (scroll | page), start (page to open at), zoom (fit-width | actual). The user can then switch layout, jump through the page list, zoom and open the document in Maket. Other hosts get the reading path. Returns no image: use snapshot to inspect a page yourself.

Calls of the Maket reader view (ui://maket/page): page returns one rendered page without image data, image returns one of its images downscaled to the displayed width, write sets one value of a state document as the Maket form does. Not for agents.

When to use: export a document to PDF for sharing or print. One call renders every page in order. For a single-page raster (PNG), use maket_preview snapshot instead.

Renders every page via headless Chromium at the canvas's true mm size, then writes to EXPORTS_DIR/.pdf. Charte CSS is inlined so fonts and tokens render identically to the live preview. The result lists, by number and name, every page whose PDF rendering differs from its preview (element boxes, fonts, colours). quality — screen (96 DPI, smallest), print (150 DPI, default), hd (300 DPI). rows — collection-bound pages: preview (default, follows the page cursor), current (cursor row only), all (one page per row), template (raw placeholders). Check the cursor first with maket_collection action=cursor.

When to use: connect Gmail, search/read mail, download an attachment, or create a draft from a Maket document. All actions except connect require an active OAuth session — call connect first.

connect — restore the refresh token if present, otherwise open the browser for OAuth consent. Pass with_read=true to also request inbox access (drafts are always granted). search — list subject/from/date for messages matching a Gmail query. Capped at 50. Requires with_read=true at connect time. read — fetch one message by id: headers, body (3000-char truncated), attachments listing. Requires with_read=true at connect time. fetch_attachment — download one attachment (id + attachmentId from a prior read). Images land in the Maket asset library (validated, optimized, thumbnailed, metadata row). Other files (PDF, zip, docx, …) drop into <DATA_DIR>/attachments/ untouched. Requires with_read=true at connect time. draft — compose a Gmail draft from a document page. Charte tokens resolve to literals, assets inline as base64, listed docs attach as PDFs. Maket never sends — the user reviews and sends from Gmail.