Maket

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). Unspecified fields keep their current value.

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: 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 as a hierarchy of category paths. 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. 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 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: 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.

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 <input type="checkbox"> for booleans, <input type="text"> for strings, <select> for string enums, and <button type="button"> for the single-value editor. 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=<data-id> for a single element, format=text to strip tags. check — measure layout against the canvas + declared `canvas.margins`; no side effects. 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.

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: 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, 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=<name>.

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 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 page structure within a document — add, remove, rename, reorder, list. For page content, use maket_html instead. Manage pages within a document (structure only, not content). add — append a new page with initial HTML; 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 element counts; the active page is marked ●. 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: 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/<doc>.pdf. Charte CSS is inlined so fonts and tokens render identically to the live preview. 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: 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. open — launch the live preview URL (localhost) in the default browser. No params. snapshot — render a page via headless Chromium. Returns the PNG inline (binary) and as a file path on disk.

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. The target interface is document-owned standard HTML/CSS: Mustache interpolation is display-only. Editable terminal values must be declared explicitly with data-maket-bind on <input type="checkbox"> (boolean), <input type="text"> (string), <select> (string enum), or <button type="button"> (single-value editor). Use state.foo at the root and relative foo inside {{#state.items}} sections. Maket resolves transient JSON Pointers and synchronizes the store; it does not generate or style controls. init — attach a schema and initial data to a static document (revision 1; no expected_revision). get — read the schema and 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.

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 every pending user message across all docs and the workspace bucket as JSON. Each message carries its own `docName` (or none for workspace scope). ack_messages — drop the given `ids` from whichever bucket they live in.