Tools reference

Report the resolved operating context: GraphQL endpoint, organization_id, store_id, store slug/name, the theme_id you are editing, WHETHER THAT THEME IS THE ONE THE STOREFRONT SERVES, and commerce_enabled. High-level tools auto-fill these; use this to learn the values for raw GraphQL.

Run a raw GraphQL MUTATION against the store. LAST-RESORT escape hatch ONLY for writes with NO dedicated tool. For pages use create_page/update_page/update_page_sections/publish_page; theme files use upsert_theme_file; content use create_content_type/create_content_record; products use create_product; menus use create_menu; publish uses publish_draft_theme. Those apply required contracts + defaults that a raw mutation skips. Remember store/org-scoped mutations need organization_id/store_id — call get_context to fetch them.

Run a raw GraphQL QUERY against the store. Escape hatch for anything not covered by a high-level tool. The API key's org scopes apply. Returns the `data` object.

Discover the GraphQL schema. With type_name, returns that type's fields and their argument/field types (use 'Query' or 'Mutation' to list all operations, or an input type to learn its shape). Without it, lists all type names.

Create (omit id) or update (set id) a record of a content type. Field values go in `values` keyed by field code.

Define a custom content type (e.g. houses, menu_items, projects) with typed fields. EAV-backed, no new tables. Records render on the storefront via the `content` Liquid Drop and the url_pattern router.

List records of a content type with optional search, facet filters, sort, and pagination. Filtering/search/sort run server-side over the full set, then the page is returned. Mirrors the storefront content-list (which a theme drives via ?q=/?<field>=/?sort=/?per_page= URL params). Returns { data, total (after filter), total_all, page, per_page }.

List the org's content types and their fields.

Generate a customizer-editable Liquid section (body + complete {% schema %}) from a spec and write it to sections/<handle>.liquid. Always ships a preset so it shows in the 'add section' picker. After this, call set_section_settings to place it on a page template.

Purge the storefront edge/Redis cache so theme/product edits show immediately. (Requires a key with settings/full-access scope.)

Create a short-lived preview token to view a theme (e.g. a draft) on the storefront without publishing.

Open a theme for editing — returns or lazily creates an unpublished draft clone you can safely edit before publishing.

Read a single theme file's content by path.

List the Liquid objects, per-template context variables, the dynamic `content` Drop, and custom filters the storefront exposes to theme sections. Use this BEFORE writing a section so you reference real variables (e.g. product.url_key, collection.products, content.<type>) instead of guessing.

List theme files (path + content_type + source), optionally filtered by path prefix.

Promote a draft (unpublished) theme to live (role=main).

Restore the theme to a snapshot taken by snapshot_theme: every file AND settings_data revert to exactly that checkpoint (files added since are deleted).

Merge global theme palette/typography/spacing into settings_data (CSS variables). Reads current settings_data, merges the given top-level keys (never clobbering the nested `sections` map), and writes it back.

Add or update a section instance on a page template (templates/<template>.json), setting its per-section settings/blocks and order. Reads the current template (inherited if the store has none), merges, and writes it back. ⚠️ CHROME sections (web-header / web-footer / announcement-bar) are LAYOUT-rendered, not template-placed: pass template:"layout" with their type and this writes the instance into the theme's settings_data.sections map — this is THE way to seed the header nav menu items (blocks: link + nested dropdown entries with real /pages/<slug> urls).

Capture an immutable checkpoint of the theme (every file + settings_data) into theme_versions. Returns the version id to restore later.

Add or update ONE section on a CMS page, INCREMENTALLY (store_pages.sections_data) — the page-record twin of set_section_settings. Reads the page's current sections, merges this one in (settings per-field: keys you don't pass are preserved; blocks replaced only when given), updates the render order, validates, and writes it back (auto-republishing a live page). Use it to build a CMS page SECTION-BY-SECTION so the user watches it fill in: create_page (empty) FIRST, then call this once per section, top to bottom — instead of dumping the whole page at once. Returns the page's storefront `path` so the preview follows to it.

Create or replace a theme file. Writes are validated against the platform design contract and REJECTED on violation: layout/theme.liquid must load assets/theme.js, render content_for_layout/content_for_header, AND carry the <style id="theme-settings-vars"> block (the customizer Theme-settings panel's canonical color_*/font_* keys only apply through it); sections/*.liquid need one complete {% schema %} whose settings include the canonical Style group (visible, bg_color, text_color, heading_color, padding_top/bottom, border_color/width/radius) and whose ids are referenced in the body; templates/*.json must be well-formed and only place existing section types. Error messages include the exact fix.

Create a CMS page (default type 'custom'). store_id is auto-filled. Pass `sections` (page-builder document — THE standard for designed pages, visually editable afterwards) or `body` (prose HTML, text-only pages). Without either the page is BLANK. Publish it with publish_page.

PERMANENTLY delete a CMS page (e.g. an accidental duplicate). Find the id with list_pages first; double-check it's the right page — this cannot be undone.

List the store's CMS pages (id, title, slug, type, status, content mode). ALWAYS check here before create_page — creating an existing slug mints a -2 duplicate.

Publish a CMS page so it's live on the storefront.

Update an existing CMS page: title/slug/meta, and its CONTENT — `sections` (page-builder document, the standard for designed pages) or `body` (prose HTML, text-only pages). Use this instead of re-creating a page.

Get the store's default language + the full set of languages the storefront serves (supported_locales). The default is served at the root URL; others at /<locale>/.

List existing translation overrides for a language (optionally filtered by resource type). Returns rows of {resource_type, resource_id, field, value}.

Set which languages the storefront serves (supported_locales on the store). Include the default locale. After this, translate content with upsert_translations and the storefront serves each non-default language at /<locale>/.

Write per-language translation overrides into the content_translations overlay. The default-language record is never changed — only the given language. An empty value removes an override. The storefront serves it at /<locale>/. Enable the language first with set_languages.

Search Pexels for real, royalty-free stock photos and return candidate image URLs. This is the DEFAULT image source for every slot — hero/section/blog/content photos. Pick the best-matching candidate URL and write it straight into the image setting; the server automatically re-hosts it into the store's media library (never hotlinked, no upload_image needed).

Upload an image (from a local file PATH or a remote URL) to the store's media library and return the hosted URL. Use this for ANY image — content-record galleries, section backgrounds, page OG images, blog featured/inline images — then pass the returned url into the matching field (a gallery value, a section image_picker, featured_image_url, etc.).

Load the full content of one shop skill (a build/redesign playbook) by name. Read shop-core-rules first — the other skills reference its §A–§I anchors.

List the available shop build/redesign skills (reusable playbooks) with a one-line description each. Call get_skill to load a full playbook before doing that kind of work.

VERIFY every internal link on ONE storefront page resolves (no 404s) — the core-rules §E acceptance check. Fetches the page, follows each internal href, returns the broken ones. Run it on EVERY page you created/changed and once on the homepage at the end; a page is NOT done while this returns broken links.

Fetch the TEXT content of a public http(s) URL — use this to read a design handoff (e.g. a claude.ai/design or Anthropic design-file export, an HTML/CSS file), a reference page to clone, or a JSON/Markdown spec the user links. Handles gzip-compressed responses automatically. Returns the raw body (HTML/CSS/JS/JSON/text), capped at 512KB. NOT for images: to put an image in the store, pass its URL to upload_image instead. Private/internal addresses are refused.

Search Pexels for real, royalty-free stock VIDEOS and return candidate looping-clip URLs (mp4, ~720–1080p) + a poster still. Use for a HERO / section BACKGROUND VIDEO when the design calls for a cinematic, motion-led look — NOT every store wants one. Write the returned `url` into the section's `video_url` setting and `poster` into `video_poster`; both auto re-host into the store's media library on write (never hotlinked). The hero renders it muted + autoplay + loop + playsinline with the poster as the still. For a plain still image use search_stock_images instead.

Toggle the store between a shop (true) and a content-only website (false). Merges store.settings.commerce_enabled. (Requires a key with settings/full-access scope.)

Write the store's ADMIN-level SEO + branding (Settings ▸ Branding/SEO): meta_title, meta_description, og_image_url, logo_url, favicon_url. THIS is where the SEO pass PERSISTS store SEO — the storefront <title>/<meta description>/OG read shop.meta_title/meta_description from here (never bake SEO into the theme, and do NOT hand-write a graphql mutation — there is a real tool, this one). Call it in the SEO step from the real brand + what the store sells.