@craftware/crafty-sdk 0.6.0 → 0.9.0

package/skills/crafty-cms/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: crafty-cms
-description: "Build on Crafty CMS — configure sites, pages, blocks, collections, entries, forms, and media through the Crafty MCP server, then develop a frontend with the @craftware/crafty-sdk JavaScript SDK. Use when connecting an agent to a Crafty MCP server; calling Crafty MCP tools like list_sites, create_page, create_block_type, publish_form, upload_media, or request_media_upload; modelling site content with block types (repeater and stringList fields); installing or importing @craftware/crafty-sdk or createCraftyClient; fetching Crafty pages, entries, collections, or media; rendering page blocks; submitting Crafty forms; or preparing a site for the Crafty visual editor (crafty.attrs, enableVisualEditing, preview tokens, configure_visual_editor)."
+description: "Build on Crafty CMS — start a new site from an official starter with `npm create crafty`, configure sites, pages, blocks, collections, entries, forms, and media through the Crafty MCP server, then develop a frontend with the @craftware/crafty-sdk JavaScript SDK. Use when starting a new Crafty site or project (npm create crafty, crafty create, starters); connecting an agent to a Crafty MCP server; calling Crafty MCP tools like list_sites, create_page, create_block_type, publish_form, upload_media, or request_media_upload; modelling site content with block types (repeater and stringList fields); installing or importing @craftware/crafty-sdk or createCraftyClient; fetching Crafty pages, entries, collections, or media; rendering page blocks; submitting Crafty forms; or preparing a site for the Crafty visual editor (crafty.attrs, enableVisualEditing, preview tokens, configure_visual_editor)."
 license: MIT
 metadata:
   author: craftware
@@ -8,6 +8,12 @@ metadata:
 
 # Crafty CMS (MCP + JavaScript SDK)
 
+> **MCP prompt: `build-site`.** It takes a site from a business description to a published website: content model, pages, frontend with the SDK, preview and deploy, confirming the plan with you before it writes. Arguments: `description` (the business and what the site needs) and optionally `site_id` (an existing site). Needs a token with `crafty:write`.
+>
+> In Claude Code, type `/` and pick `mcp__<server>__build-site`, where `<server>` is the name you gave the Crafty server; other clients list it in their prompt menu. If your client does not show MCP prompts, ask the agent to call `get_guide getting-started` and follow it.
+>
+> Redesigning a client's existing site? The `redesign-site` prompt reads their current site and social media and proposes the new one before building it (see `get_guide migrate`).
+
 Crafty is a headless, multi-tenant CMS. There are two integration surfaces, and they are used at different stages:
 
 | Surface | Purpose | Auth | Use it to |
@@ -15,15 +21,36 @@ Crafty is a headless, multi-tenant CMS. There are two integration surfaces, and
 | **MCP server** | Author and configure content | Bearer token (PAT or OAuth), scoped | Create sites, pages, blocks, collections, entries, forms; upload media; publish |
 | **`@craftware/crafty-sdk`** | Read published content into an app | `X-API-Key` environment token | Fetch pages/blocks, entries, collections, media; submit forms from a site |
 
-The normal flow is **configure with the MCP server → build a frontend with the SDK**.
+The normal flow is **configure with the MCP server → build a frontend with the SDK**. For a **new site**, `npm create crafty` does both in one step (see [Start a new site](#start-a-new-site)).
 
 ## When to Use
 
+- Starting a new Crafty site or frontend project from scratch (`npm create crafty`, `crafty create`, official starters).
 - Connecting Claude, Cursor, VS Code, Codex, or ChatGPT to a Crafty tenant's MCP server.
 - Driving Crafty MCP tools (`list_sites`, `create_page`, `create_entry`, `create_form`, `publish_page`, `upload_media`, …).
 - Installing or importing `@craftware/crafty-sdk` / `createCraftyClient`.
 - Fetching Crafty pages, entries, collections, or media in app code, or submitting a Crafty form.
 
+## Start a new site
+
+When the user wants a **new** site (not Crafty added to an existing frontend), don't model content and write the frontend by hand: scaffold it from an official starter.
+
+```bash
+npm create crafty@latest mi-sitio -- --url=https://<tenant>.crafty.do
+# same flow: npx @craftware/crafty-cli create mi-sitio --url=https://<tenant>.crafty.do
+```
+
+It asks for the framework and template (today: Astro, `astro-services` = "sitio de servicios" or `astro-docs` = "documentación"; Next.js and Nuxt are coming), logs in through the browser (device flow; the user approves, an admin account is needed), creates the site with the starter's block types, collections, form and demo content, configures the visual editor routes, and writes `.env` (`CRAFTY_API_URL`, `CRAFTY_API_KEY`, `CRAFTY_SITE`), `crafty.json` and `src/crafty.types.ts`. Then:
+
+```bash
+cd mi-sitio && npm install && npm run dev   # npm run deploy → Crafty Hosting
+```
+
+- Flags (after `--`): `--url`, `--framework=astro`, `--template=astro-services|astro-docs`, `--name`, `--site=<slug>`, `--draft` (keep demo content as drafts; by default it is published so the static build shows it), `--yes` (no prompts). Agents should pass `--url` and `--yes` so nothing blocks on a prompt; the browser approval still needs the user.
+- The command is interactive only for the login: tell the user to open the printed URL and approve the code.
+- After it finishes, **read the project's `AGENTS.md`** and follow its conventions (one renderer per block type in `src/render/blocks/`, routes in `src/lib/routes.ts`, `npm run types` after changing the content model) instead of the generic steps in Phase 2.
+- If the site slug already exists it fails before creating anything; if provisioning fails midway it names the half-created site: delete it in the panel or rerun with another `--site`.
+
 ## Scope
 
 - **In scope:** using a *deployed* Crafty tenant via its MCP server and the published SDK.
@@ -59,9 +86,9 @@ How to model it:
   - several images (gallery, slider, logo wall): `{ key: "gallery", type: "multiReference", model: "Media" }`, value `[42, 43, 44]`;
   - an image per repeater item: a `reference` subfield with `model: "Media"` (`multiReference` is top-level only).
 
-  The public API returns the id under the field key and adds `<key>_media` with the file (`{ id, url, file_name, mime_type, size, is_public }`, a list for `multiReference`), so the frontend reads `block.data.image_media?.url`. Editors get a media picker in the panel and the visual editor can swap the image. A `photo_url` string field gives them none of that and breaks when the file moves.
+  The public API returns the id under the field key and adds `<key>_media` with the file (`{ id, url, file_name, alt, mime_type, size, is_public, image_transform_base }`, a list for `multiReference`), so the frontend renders `crafty.image(block.data.image_media, { width: 800, format: "auto" })` with `alt={block.data.image_media?.alt ?? ""}`. Editors get a media picker in the panel and the visual editor can swap the image. A `photo_url` string field gives them none of that and breaks when the file moves.
 - **Shared data** (address, phone, social links, footer text used in several places): block types have no global blocks. Put it in a dedicated page (e.g. slug `site-settings`) with one `site-settings` block and read it with `crafty.pages.get("site-settings")`.
-- **Languages**: pages have no locale or translation link. Use one page per language with different slugs (`home`, `home-en`) and pick the slug in your router.
+- **Languages**: do not duplicate pages per language. Set the site's locales (`configure_locales`, e.g. default `es` plus `en`), write the default-locale content as usual, then add each translation with `upsert_translation` (entries; pages with their blocks by id). The frontend passes `locale` (`createCraftyClient({ locale })` or per call) and untranslated fields fall back to the default. Mark fields that must never change per language (SKU, codes) with `translatable: false`. `meta.translations` on `get()` lists the locales an item has, for `hreflang`. When AI translation is enabled for the workspace (from Crafty central) and for the site (`configure_translation` with `enabled: true`), `translate_content` translates an entry or page (with its blocks) into the site's locales without overwriting what a person wrote, and `configure_translation` also turns on re-translation after every change plus a glossary of untranslated terms.
 - There is no `json` field type in block types. If you catch yourself wanting one, model it as a repeater or `stringList`.
 - **References to records**: `{ type: "reference", collection: "<collection slug>" }` (one entry) or `multiReference` (several); the API expands them into the referenced entries.
 
@@ -99,14 +126,18 @@ Block types: `get_block_type` (`site_id` + `block_type_id` or `slug`) → `creat
 
 Collections/entries: `list_collections` → `create_entry` (`collection_slug`, `site_id`, `slug`, `data`, optional `status: "draft"` to prepare it unpublished) → `update_entry` (snapshots a revision) → `publish_entry` / `unpublish_entry`. To publish or unpublish a page or entry at a given time, use `schedule_publication` (`publish_at` / `unpublish_at`).
 Forms: `create_form` (`site_id`, `name`, `slug`, `fields`) → `publish_form` → `list_form_submissions`.
-Media: upload files before you fill content, and put the returned media `id` in `reference` / `multiReference` fields with `model: "Media"` (`list_media` lists existing ids). `upload_media` (`url`, `site_id`, optional `collection_name`, `sha256`) takes an http(s) URL or a small base64 data URI (256 KB decoded). For a **local binary file** call `request_media_upload` (`site_id`, `file_name`, `sha256`, optional `collection_name`) and run the returned `curl -T` command from your shell; the bytes never pass through the model and the upload is verified against the sha256. Files land on a public disk only if the `collection_name` repository is public — create or change it with `manage_media_collection` (`site_id`, `key`, `is_public`) BEFORE uploading.
+Media: upload files before you fill content, and put the returned media `id` in `reference` / `multiReference` fields with `model: "Media"` (`list_media` lists existing ids). `upload_media` (`url`, `site_id`, optional `collection_name`, `sha256`) takes an http(s) URL or a small base64 data URI (256 KB decoded). For a **local binary file** call `request_media_upload` (`site_id`, `file_name`, `sha256`, optional `collection_name`) and run the returned `curl -T` command from your shell; the bytes never pass through the model and the upload is verified against the sha256. Files land on a public disk only if the `collection_name` repository is public — create or change it with `manage_media_collection` (`site_id`, `key`, `is_public`) BEFORE uploading. **Always set alt text on content images**: pass `alt` (a concise description of what the image shows, in the site language, max 500 characters) to `upload_media` / `request_media_upload`, or set it later with `update_media` (`site_id`, `media_id`, `alt`); `list_media` shows `alt: null` for files still missing it. Purely decorative images may keep `alt` empty.
 Cache: `set_api_cache_status` (`site_id`, `enabled`) to toggle per-site; `flush_api_cache` (`site_id`, optional `resource`) to invalidate cached responses after bulk edits.
 Visual editor: `configure_visual_editor` (`site_id`, optional `environment`, `frontend_url`, `routes`, `render_mode`, `upload_media_collection`) — see `references/visual-editor.md`.
 
 > `update_page` **replaces all blocks** when `blocks` is supplied (send every block again with its `id` to keep it). `update_entry` creates a revision. `create_page` always starts as `draft`.
 
+Migrating an existing site (WordPress, Webflow, a static site…)? Don't recreate it by hand: follow `references/migrate-to-crafty.md` — it uses `bulk_upsert_entries` (100 entries per call, drafts, `dry_run`), `import_media_from_urls` (50 URLs per call, deduplicated) and `upsert_redirects` so old URLs keep working.
+
 ## Phase 2 — Build a frontend with the SDK
 
+Starting a new site from scratch? Use `npm create crafty` ([Start a new site](#start-a-new-site)) and follow the starter's `AGENTS.md` instead of the steps below. Adding Crafty to an existing frontend:
+
 ```bash
 npm install @craftware/crafty-sdk
 ```
@@ -128,12 +159,18 @@ const hero = page.block("hero");          // first block of that type, or null
 const posts = await crafty.entries.list("posts", { per_page: 15 });
 ```
 
+**Generate types before writing code against the content.** Field shapes depend on the site's collections and block types — do not guess them. Run `npx @craftware/crafty-cli types` (reads `CRAFTY_API_URL` + `CRAFTY_API_KEY` from `.env`, or pass `--url` / `--api-key`; `--out` changes the file) to write `crafty.types.ts` with `<Slug>Entry` per collection, `<Slug>BlockData` / `<Slug>Block` per block type and the `CraftyPageBlock` union; cast SDK results to them (`page.blocks as unknown as CraftyPageBlock[]`). Types follow the API key's environment (staging may differ from production); re-run it after `create_block_type` / `update_block_type` / `update_collection`. The raw JSON Schema is `GET /api/v1/schema`. Details: `references/sdk-development.md`.
+
+Images: render every Crafty image with `crafty.image(media, { width, format: "auto" })` and `crafty.srcset(media, [400, 800, 1200], { format: "auto" })` instead of the raw `url`; they return resized AVIF/WebP URLs when the server has image transformations enabled and fall back to the original `url` otherwise. Never hand-build `/cdn-cgi/image/` URLs.
+
 `pages.get()` returns the page enriched with block helpers (`page.block(type)`, `page.blocksOf(type)`, `page.byType`, …). **Full client config, every resource and return shape, block helpers, errors, and an end-to-end example: read `references/sdk-development.md`.**
 
 Serving `llms.txt` / `llms-full.txt` for AI agents and crawlers: `crafty.llms.handler()` as a route (Next/Astro/Nuxt), or `crafty.llms.index()` / `full()` written into `dist/` for a static build. Title, summary, language, and routeless collections are configured on the "llms.txt" admin screen or the `configure_llms` MCP tool. **Full API, per-framework wiring, and error handling: `references/sdk-development.md`.**
 
 Analytics and ad pixels (Google Tag Manager, GA4, Meta Pixel, TikTok Pixel): do **not** hard-code their snippets into the site. Set the IDs on the "Analítica" admin screen or with the `configure_analytics` MCP tool; Crafty hosting injects the official loaders into every HTML page on the next deploy. If the site already loads GA4 or pixels through GTM, set only the GTM container. Hosted elsewhere: render `(await crafty.analytics.get()).head` before `</head>` in SSR, or call `crafty.analytics.load()` once in the browser (it skips itself when the deploy already injected them). **Details: `references/sdk-development.md`.**
 
+Structured data (schema.org JSON-LD for Google rich results and AI search): do **not** write JSON-LD by hand. Fill the business data (type, address, hours, phone, social profiles) with the `configure_structured_data` MCP tool, map collections to Product / Article / BlogPosting / FAQPage / Event / Service with `structured_data` on `create_collection` / `update_collection`, and render `crafty.structuredData(page, entries)` in `<head>`: the home page carries the business JSON-LD, mapped entries their own. For FAQ blocks, `crafty.structuredData(crafty.faqPage(block.data.items))`. **Details: `references/sdk-development.md`.**
+
 ## Phase 3 — Deploy a static site with the CLI
 
 ```bash
@@ -184,12 +221,15 @@ These are two different credentials — do not mix them:
 - **Wrong tenant host** → the MCP endpoint won't resolve. Use the exact `https://<tenant-domain>/mcp`; each tenant has its own endpoint.
 - **401 from the MCP server** → the Bearer token is missing, invalid, or expired; reconnect or regenerate it.
 - **A tool is missing or fails with "Insufficient OAuth scope"** → the token lacks that tool's scope; re-issue it with `crafty:write` / `crafty:publish` / `crafty:submissions` as needed.
-- **`forms.submit()` throws `BAD_REQUEST`** → `siteSlug` was not set in `createCraftyClient()`. Submissions hit the public endpoint and deliberately omit the API key.
+- **`forms.submit()` throws `BAD_REQUEST`** → `siteSlug` was not set in `createCraftyClient()`. Submissions hit the public endpoint; the API key, when set, only picks the environment the submission lands in.
 - **`update_entry` / `update_page` wipe fields you don't send** → both MCP tools do a **full replace**, not a merge. If you send only the new fields, all existing fields are deleted in that revision. Always fetch the current entry first (`get_entry`), merge your changes into the full field map, then call `update_entry` with the complete merged object. Entry `data` is validated against the collection schema: invalid values are rejected and undeclared keys are dropped (listed in `warnings`).
 - **`create_page` / `update_page` reject block data** → block data is validated against the block type (`blocks.2.data.items.1.title: …`), `number` fields are integers (use `decimal` for prices), `select` values must be one of the declared options, `string` fields max 255 characters, and `block_type_id` must belong to the same site. Read the schema with `get_block_type` first.
 - **Data silently missing from a block** → keys not declared in the block type are dropped; check the `warnings` array in the response.
 - **Modelled a list as a collection or a `json` field** → use a block type with a `repeater` (or `stringList`) instead; see "Model content with block types first". Inside a collection, use a `repeater`, `stringList`, `select` with `multiple: true` or `multiReference` (to media or to another collection) instead of `json`.
-- **Stored an image as a `url` / `string` field (`photo_url`, `image`, `logo`)** → upload it to the media library and use a `reference` (`multiReference` for several) with `model: "Media"`; render `<key>_media.url`. Change an existing field with `update_block_type` / `update_collection` and re-save the content with media ids.
+- **Guessed a field name or shape (`block.data.title` vs `heading`, a select value, `image` vs `image_media.url`)** → generate `crafty.types.ts` with `crafty types` and let the compiler catch it.
+- **Stored an image as a `url` / `string` field (`photo_url`, `image`, `logo`)** → upload it to the media library and use a `reference` (`multiReference` for several) with `model: "Media"`; render `crafty.image(<key>_media, { width, format: "auto" })`. Change an existing field with `update_block_type` / `update_collection` and re-save the content with media ids.
+- **Serving the original image (`<img src={media.url}>`)** → large uploads hurt LCP. Use `crafty.image(media, { width, format: "auto" })` plus `crafty.srcset()`; it falls back to `url` when transforms are unavailable.
+- **Uploaded images without alt text** → set `alt` with `update_media` for every content image (`list_media` shows which have `alt: null`) and render `<key>_media.alt` in the frontend's `<img alt>`.
 - **Content not visible via the SDK** → it isn't published. Pages/forms must be published (`publish_page` / `publish_form`); entries created as drafts need `publish_entry`.
 - **Confusing the two tokens** → the SDK `apiKey` (X-API-Key) is not an MCP Bearer token.
 - **Stale skill copy** → a project copy of this skill (e.g. `.claude/skills/crafty-cms`) does not update with the SDK. After upgrading `@craftware/crafty-sdk`, copy `node_modules/@craftware/crafty-sdk/skills/crafty-cms` over it.
@@ -198,4 +238,5 @@ These are two different credentials — do not mix them:
 
 - `references/mcp-configuration.md` — connecting every client, scopes, and the full MCP tool catalog with workflows.
 - `references/sdk-development.md` — the complete SDK surface, block helpers, error handling, and examples.
+- `references/migrate-to-crafty.md` — migrating an existing site (WordPress or any other) into Crafty: crawl, classify, model, bulk import as drafts, media, redirects, human review, publish.
 - `references/visual-editor.md` — preparing a site for the visual editor: the mandatory question, marking, preview tokens, bridge, headers, `configure_visual_editor`, verification.

package/skills/crafty-cms/references/mcp-configuration.md

@@ -31,6 +31,8 @@ When you create the client manually in your profile you are shown the `client_id
 
 OAuth clients that support MCP auto-discovery (Claude.ai, Claude Code, Codex, Cursor, ChatGPT) can find everything from the server URL alone: discovery is published at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, with `authorization_endpoint` `/oauth/authorize`, `token_endpoint` `/oauth/token`, dynamic `registration_endpoint` `/oauth/register`, PKCE (`S256`), and grants `authorization_code` + `refresh_token`. Registered redirect URIs must be `https`, a custom app scheme, or `http` on a loopback address (so local CLI callbacks work). These OAuth endpoints live at the tenant **root**, not under `/mcp`.
 
+Clients that implement the MCP 2026-07-28 authorization spec can skip registration and use a **Client ID Metadata Document** (CIMD): the `client_id` is an `https` URL serving the client's metadata as JSON (`client_id` equal to that URL, `redirect_uris`, optional `client_name`). Crafty advertises `client_id_metadata_document_supported: true`, fetches the document on `/oauth/authorize` (public addresses only, no redirects, 5 KB max, cached per its `Cache-Control` max-age), and requires the `redirect_uri` to be listed in it. Only public clients (`token_endpoint_auth_method: "none"`) are accepted this way. Dynamic registration keeps working for clients that still use it.
+
 ## Scopes
 
 When you create a token (PAT or OAuth client) you grant one or more scopes. Scopes are **enforced per tool**: a tool is only advertised when your token carries its required scope, and invoking one without the scope fails with an MCP error (`Insufficient OAuth scope`). Grant the scopes the agent needs:
@@ -106,9 +108,11 @@ All tools return a JSON text response. IDs are integers; slugs are strings. Pagi
 | `list_collections` | — | `site_id` | active collections (with their `id`, used by `update_collection` / `delete_collection`) |
 | `list_entries` | `collection_slug` | `site_id`, `status`, `per_page` | paginated entries (newest id first), each with `status` and `published_at` |
 | `get_entry` | `entry_id` | — | one entry with its collection |
-| `list_media` | `site_id` | `collection`, `per_page` | paginated media for the site |
+| `list_media` | `site_id` | `collection`, `per_page` | paginated media for the site; each item has `alt` (`null` when missing) |
 | `list_forms` | — | `site_id`, `status`, `per_page` | paginated forms, ordered by name |
 | `get_form` | `form_id` | — | one form with its field definitions |
+| `list_redirects` | `site_id` | `environment` (default `production`) | the environment's redirects `{ source, destination, status_code }` |
+| `list_webhooks` | `site_id` | `environment` (default `production`) | content webhooks (admins only) with their events and last deliveries; `upsert_webhook` / `delete_webhook` manage them (`crafty:write`) |
 
 ### Submissions (`crafty:submissions`)
 
@@ -136,15 +140,23 @@ Form submissions may contain personal data, so they require their own scope.
 | `delete_collection` | `collection_id`, `confirm: true` | — | **permanently** deletes the collection and all its entries |
 | `create_entry` | `collection_slug`, `site_id`, `slug` | `data`, `status` | `status` = `draft` (default, hidden from the public API until `publish_entry`) or `published`; `data` = field key/value pairs, validated against the collection schema (`number` integer, `decimal` within `min`/`max`/`precision`, `select` one of its option values or an array of distinct values when `multiple`, `repeater` items against their subfields; invalid data is rejected as `data.<field>: <message>`; undeclared keys are dropped and listed in `warnings`) |
 | `update_entry` | `entry_id` | `data`, `slug` | snapshots the prior data into a new revision; `data` is validated like `create_entry` (required fields are not enforced, only provided ones are checked) and rejected data creates no revision |
-| `upload_media` | `url`, `site_id` | `collection_name` (default `library`), `file_name`, `sha256` | http(s) URL or base64 data URI (max 256 KB decoded); `sha256` rejects and discards the upload on mismatch; the response returns the stored `sha256`, `visibility` and a `warning` when the file is private |
-| `request_media_upload` | `site_id`, `file_name`, `sha256` | `collection_name` (default `library`), `size` | returns a 15-minute single-use signed URL and a ready `curl -T` command for uploading a **local binary file** without sending its bytes through the model; max 25 MB; verified against `sha256` |
+| `bulk_upsert_entries` | `site_id`, `collection_slug`, `entries` | `dry_run`, `publish` | up to 100 `{ slug, external_id?, data }` per call; matches an existing entry by `external_id` first, then by `slug`, else creates it; `data` is validated like `create_entry` and **replaces** the stored data on update (with a revision); new entries are drafts unless `publish: true` (needs `crafty:publish`); items fail individually; `dry_run` reports `created` / `updated` / `failed` per item without saving |
+| `upload_media` | `url`, `site_id` | `collection_name` (default `library`), `file_name`, `sha256`, `alt` | `alt` = alt text for images (max 500 chars); http(s) URL or base64 data URI (max 256 KB decoded); `sha256` rejects and discards the upload on mismatch; the response returns the stored `sha256`, `visibility` and a `warning` when the file is private |
+| `import_media_from_urls` | `site_id`, `urls` | `collection_name` (default `library`) | up to 50 public http(s) URLs per call, with the same SSRF, size and type checks as `upload_media`; a URL already imported to the site (or repeated in the batch) is not downloaded again; per URL: `status` `imported` / `existing` / `duplicate` / `failed`, `media_id`, `original_url` |
+| `request_media_upload` | `site_id`, `file_name`, `sha256` | `collection_name` (default `library`), `size`, `alt` | `alt` is stored with the file once uploaded; returns a 15-minute single-use signed URL and a ready `curl -T` command for uploading a **local binary file** without sending its bytes through the model; max 25 MB; verified against `sha256` |
 | `manage_media_collection` | `site_id`, `key` | `name`, `description`, `is_public` | creates or updates a media repository; `is_public: true` gives permanent public URLs (existing files are moved in the background); new repositories are private |
+| `update_media` | `site_id`, `media_id`, `alt` | — | sets the alt text (max 500 chars) of one media file; `null` or `""` clears it |
 | `delete_media` | `site_id`, `media_id`, `confirm: true` | — | **permanently** deletes one media file (ids from `list_media`) |
 | `create_form` | `site_id`, `name`, `slug` | `description`, `fields` | `fields: [{ key, type, label, required? }]`; starts as `draft` |
 | `update_form` | `form_id` | `name`, `slug`, `description`, `fields`, `notification_emails` | only supplied fields change; `fields`/`notification_emails` replace |
 | `configure_visual_editor` | `site_id` | `environment` (default `production`), `frontend_url`, `routes` (`page_pattern`, `home_slug`, `collections`, `fixed`), `render_mode` (`ssr`/`hybrid`/`static`/`unknown`), `upload_media_collection` | visual editor settings of one environment; only sent keys change, `null` resets to the fallback; with only `site_id` it just reads; returns the effective settings plus `llms_warnings` (the `llms.txt` generator's warnings, since routes affect it too) |
 | `configure_llms` | `site_id` | `environment` (default `production`), `title`, `summary`, `language`, `excluded_collections` (routed collections to drop), `included_collections` (routeless collections to opt in), `collection_languages` | admins only; same read/partial-update semantics as `configure_visual_editor`; only sent keys change, `null` resets to the fallback; with only `site_id` it just reads; returns the effective settings, the configuration warnings, and the first 40 lines of the generated `llms.txt` |
 
+| `upsert_redirects` | `site_id`, `redirects` | `environment` (default `production`), `dry_run` | up to 500 `{ source, destination, status_code? }` per call, matched by `source`; `source` is a path starting with `/` (no spaces, `?` or `#`; Cloudflare Pages `*` splats and `:placeholders` allowed), `destination` a path or absolute http(s) URL, `status_code` 301 (default) / 302 / 307 / 308; invalid items are listed in `failed` and skipped. Crafty hosting writes them to `_redirects` on the next deploy (after the site's own rules; limit 2000 static + 100 dynamic); custom frontends read `GET /api/v1/redirects` |
+| `delete_redirect` | `site_id`, `source` | `environment` (default `production`) | deletes one redirect |
+
+Redirect tools follow the **Pages** permission: reading needs access to pages, changing needs write access.
+
 ### Publish (`crafty:publish`)
 
 | Tool | Required | Effect |
@@ -163,7 +175,7 @@ Form submissions may contain personal data, so they require their own scope.
 
 1. `list_sites` → choose a `site_id` (or `create_site`).
 2. For each section of the design, `create_block_type` (or `get_block_type` if it exists). Use a `repeater` for lists of items, `stringList` for lists of plain strings, and `reference` / `multiReference` with `model: "Media"` for images (upload them first); only use a collection for large independent record sets.
-3. `create_page` (one page per language, e.g. `home` and `home-en`) with `blocks: [{ block_type_id, data }, …]`; fix any `blocks.N.data.…` errors and check `warnings`.
+3. `create_page` in the default locale with `blocks: [{ block_type_id, data }, …]`; fix any `blocks.N.data.…` errors and check `warnings`. For other languages, `configure_locales` once and then `upsert_translation` per page (blocks by id from `get_page`), or `translate_content` to let AI translate it once AI translation is enabled for the workspace and the site (`configure_translation`).
 4. `publish_page`.
 5. To change a schema later, `update_block_type` with the FULL field list (use `force: true` only if you accept orphaning data that blocks already hold).
 
@@ -189,9 +201,13 @@ Form submissions may contain personal data, so they require their own scope.
 **Media**
 
 1. Need permanent public URLs? `manage_media_collection` with `site_id`, `key`, `is_public: true` first (otherwise files get expiring signed URLs).
-2. From a URL or a tiny file: `upload_media` with `url` and `site_id` (optionally `collection_name`, `sha256`).
-   From a local file: compute `shasum -a 256 <file>`, call `request_media_upload`, then run the returned `curl -T` command.
-3. `list_media` to confirm and retrieve URLs.
+2. From a URL or a tiny file: `upload_media` with `url`, `site_id` and `alt` (optionally `collection_name`, `sha256`).
+   From a local file: compute `shasum -a 256 <file>`, call `request_media_upload` (with `alt`), then run the returned `curl -T` command.
+3. `list_media` to confirm and retrieve URLs; give every content image without `alt` one with `update_media`.
+
+**Migrate an existing site**
+
+Follow `migrate-to-crafty.md`: crawl → classify → model → `import_media_from_urls` → `bulk_upsert_entries` (drafts, `dry_run` first) → `upsert_redirects` → human review → publish.
 
 **Visual editor**
 

package/skills/crafty-cms/references/migrate-to-crafty.md

@@ -0,0 +1,93 @@
+# Migrating an existing site to Crafty
+
+> **MCP prompt: `migrate-site`.** It runs this whole runbook for you and stops at every checkpoint for you to confirm. Arguments: `site_id` (the target site), `source` (the old site's URL, its `sitemap.xml` or a description of the export) and optionally `environment` (default `production`) and `research` (default `yes`: it also researches the brand on the web and proposes content the old site lacks; `no` for a strict 1:1 move). Needs a token with `crafty:write`.
+>
+> In Claude Code, type `/` and pick `mcp__<server>__migrate-site`, where `<server>` is the name you gave the Crafty server; other clients list it in their prompt menu. If your client does not show MCP prompts, ask the agent to call `get_guide migrate` and follow it.
+>
+> **Redesign instead of a 1:1 move? MCP prompt: `redesign-site`.** It studies the client's current site, social media and what the rest of the web says about them, sums up their brand, voice and content, and proposes a new site (site map, sections built from your block types, draft copy, visual direction) before it creates anything. Once you approve the proposal it builds it as drafts and never publishes. Arguments: `website` (the current site's URL) and optionally `social` (profile URLs or handles), `goals` and `site_id` (leave it out to make the proposal before the client has a Crafty site). Needs a token with `crafty:write`. Social networks often block automated reading, so be ready to paste the bio and a few posts or share screenshots.
+
+Runbook for moving a site that already exists (WordPress, Webflow, Wix, a static site, another headless CMS) into Crafty with an agent and the MCP server, without breaking its URLs. Work in this order; each phase has a checkpoint where a human confirms before the next one.
+
+Tools used: `bulk_upsert_entries`, `import_media_from_urls`, `upsert_redirects` (plus the usual `create_block_type`, `create_collection`, `create_page`, `publish_*`). Token scopes: `crafty:read` + `crafty:write`; add `crafty:publish` only for the final phase.
+
+## Golden rules
+
+- **Everything lands as a draft.** Never pass `publish: true` until a human has reviewed the content in the panel.
+- **`dry_run: true` first** on every `bulk_upsert_entries` and `upsert_redirects` batch; fix the `failed` items, then run it for real.
+- **Use `external_id`** (the old CMS post/page ID, or the old URL when there is no ID) on every entry. Re-running an import then updates instead of duplicating.
+- **Batches:** up to 100 entries, 50 media URLs, 500 redirects per call. Keep a local manifest (JSON/CSV) of what each batch sent and what came back (`entry_id`, `media_id`), so a failed run can resume.
+- **Media quota:** imports count against the tenant's media quota. Import only what the pages actually use, skip thumbnails and resized copies (WordPress `-300x200.jpg` variants), and ask before importing more than a few hundred files.
+- Work against the `production` environment of the target site unless the user asks for another (tools take `environment`).
+
+## Phase 1 — Crawl
+
+Build an inventory of every URL of the old site:
+
+1. Sources, best first: the CMS export or API (WordPress REST `/wp-json/wp/v2/posts?per_page=100&page=N`, `/pages`, `/media`; or the WXR export), `sitemap.xml` (and sitemap indexes), then a crawl of internal links from the home page.
+2. For each URL record: old path, title, type guess, language, last modified, the main content (HTML), the images and files it uses, and the old ID if known.
+3. Also collect the URLs that already redirect (HTTP 301/302) and anything in the old site's redirect plugin or `.htaccess`: those must be carried over too.
+4. Research the brand beyond its site: search the web for its name (Google Business profile and reviews, social media, press, directories and marketplaces, award or partner pages). List what the old site lacks as **proposed additions**: reviews and testimonials, FAQs drawn from customer questions, opening hours, locations, services or products listed elsewhere, awards, press mentions, social links. Give each one its source URL and how sure you are, flag information that contradicts the site or looks outdated, and never invent facts. Keep the additions apart from the inventory: they are proposals, not migrated content. Skip this step for a strict 1:1 move (the `migrate-site` prompt takes `research: "no"`).
+
+**Checkpoint:** show the user the counts per type, any URL you could not fetch and the proposed additions. Only the additions the user picks are added, in phase 5, as new drafts.
+
+## Phase 2 — Classify
+
+Group the URLs into:
+
+- **Singleton pages** (home, about, contact, landing pages) → Crafty **pages** built from block types.
+- **Repeating content** (posts, news, products, team members, case studies, events) → one **collection** per type, one entry per item.
+- **Archives and taxonomy listings** (`/category/x`, `/tag/y`, `/page/2`, author pages, date archives) → usually not migrated as content: the new frontend generates them; they only need redirects.
+- **Junk** (search results, feeds, attachment pages, `?replytocom=` …) → drop; redirect to the closest useful page when they had traffic.
+
+Decide the new URL scheme with the user (e.g. `/blog/2019/05/hello-world` → `/blog/hello-world`), and write the old → new mapping into the inventory now.
+
+**Checkpoint:** the user approves the content types and the URL scheme.
+
+## Phase 3 — Model
+
+Follow "Model content with block types first" in `SKILL.md`:
+
+1. Inspect the current schemas: `list_block_types`, `list_collections`.
+2. For singleton pages, `create_block_type` per recurring section (hero, text + image, cards → `repeater`, FAQ → `repeater`, CTA). Reuse existing block types when they fit.
+3. For each repeating type, `create_collection` with the fields the content really has: `title` (`string`), `excerpt` (`text`), `body` (`longText`, HTML), `cover` (`reference`, `model: "Media"`), `gallery` (`multiReference`), `published_on` (`datetime`), `tags` (`stringList`), `category` (`select`), SEO fields (`seo_title`, `seo_description`). No `json` fields for content editors maintain.
+4. Mark the repository the images will go to as public first if the site needs permanent URLs: `manage_media_collection` with `is_public: true`.
+
+**Checkpoint:** the user reviews the schemas in the panel before any import.
+
+## Phase 4 — Media
+
+1. From the inventory, list the distinct image and file URLs the migrated content uses (full-size originals only).
+2. `import_media_from_urls` in batches of up to 50: `{ site_id, urls, collection_name }`. Each result has `status` (`imported`, `existing` when the URL was already imported, `duplicate` within the batch, `failed`) and `media_id` / `original_url`.
+3. Save the old URL → `media_id` / `original_url` map. Retry `failed` items once; report the rest (private hosts, redirects, too large or unsupported types are refused on purpose — download those locally and use `request_media_upload`).
+
+## Phase 5 — Content (as drafts)
+
+1. Transform each item to the collection schema: clean the HTML (drop builder shortcodes, inline styles, tracking pixels), rewrite internal links to the **new** paths, and replace image URLs in the HTML with the `original_url` values from phase 4. Put media references (`cover`, `gallery`) as `media_id` values.
+2. `bulk_upsert_entries` with `{ site_id, collection_slug, entries: [{ slug, external_id, data }], dry_run: true }`. Fix every `failed` item (the errors name the field, e.g. `data.published_on: …`) and check `warnings` (dropped keys = a field missing from the schema).
+3. Run the same batch without `dry_run`. Entries are created as **drafts**; existing ones (same `external_id` or `slug`) are updated with a revision.
+4. Write the additions the user picked in phase 1 as new drafts (no `external_id` from the old site) and list them, with their sources, in the review report.
+5. Singleton pages: `create_page` with `blocks` in the default locale; they start as drafts too. Other languages of the old site go in with `configure_locales` and `upsert_translation`, not as extra pages.
+
+## Phase 6 — Redirects
+
+1. From the inventory, one redirect per old URL whose path changes: `{ source: "/old/path", destination: "/new/path", status_code: 301 }`. Use 301 for permanent moves; 302/307 only for temporary ones.
+2. Collapse patterns into dynamic rules when possible (`/category/*` → `/blog`, `/blog/:year/:month/:slug` → `/blog/:slug`): Crafty hosting allows 2000 static and 100 dynamic rules per deploy, including the site's own `_redirects`.
+3. `source` must be a path (no domain, no `?query`, no `#fragment`); `destination` a path or an absolute http(s) URL. Don't redirect a URL to itself or create chains (A → B → C: point A straight at C).
+4. `upsert_redirects` with `dry_run: true`, fix `failed`, then for real (500 per call). Check with `list_redirects`.
+5. Hosted on Crafty: they apply on the next deploy. Custom frontend: read `GET /api/v1/redirects` in the middleware (Next.js `middleware.ts`, Nuxt server middleware) and answer with the `status_code` and `Location` header.
+
+## Phase 7 — Human review
+
+Give the user a short report: counts created/updated/failed per type, media imported/skipped, redirects created, and the list of items that need a human (failed transformations, missing images, pages that did not map to a block type). Ask them to review the drafts in the panel (and in the visual editor if it is configured). Apply their corrections with `update_entry` / `update_page`, or re-run the import batch (it updates by `external_id`).
+
+## Phase 8 — Publish and switch over
+
+Only after the user's explicit go-ahead:
+
+1. Publish: `bulk_upsert_entries` again with `publish: true` (token with `crafty:publish`) or `publish_entry` / `publish_page` per item; or `schedule_publication` for a set launch time.
+2. Deploy the new frontend, point the domain at it, then spot-check a sample of old URLs (they must answer 301 to the new ones) and the sitemap.
+3. Keep the redirects: removing them later breaks links and search rankings.
+
+## Not covered yet
+
+There is no WordPress WXR importer, sitemap importer or broken-link report in the panel: the agent does those steps itself with the tools above.

package/skills/crafty-cms/references/sdk-development.md

@@ -23,7 +23,7 @@ const crafty = createCraftyClient({
 });
 ```
 
-`createCraftyClient(config)` returns a plain object with six resources (`collections`, `entries`, `pages`, `forms`, `mediaCollections`, `mediaFiles`) and the visual editor helpers `attrs`, `attrsHtml` and `previewFromRequest`.
+`createCraftyClient(config)` returns a plain object with six resources (`collections`, `entries`, `pages`, `forms`, `mediaCollections`, `mediaFiles`), the image helpers `image` and `srcset`, and the visual editor helpers `attrs`, `attrsHtml` and `previewFromRequest`.
 
 ### Config options
 
@@ -70,7 +70,7 @@ crafty.entries.list(collectionSlug, query?, options?)  // => { data: CraftyEntry
 crafty.entries.get(collectionSlug, id, options?)       // => { data: CraftyEntry }
 ```
 
-`query`: `sort_by`, `sort_order` (`asc`/`desc`), `per_page`, `page`, plus any extra key/value filters passed through to the API.
+`query`: `q` (text search over the collection's text fields), `sort_by`, `sort_order` (`asc`/`desc`), `per_page`, `page`, plus any extra key/value filters passed through to the API.
 
 ### `pages`
 
@@ -113,7 +113,7 @@ const cta = landing.requireBlock("cta");            // throws plain Error if abs
 | `boolean` | boolean |
 | `stringList` | `string[]` (e.g. `["AI", "Cloud"]`) |
 | `repeater` | array of objects; every declared subfield is present, `null` when empty (e.g. `[{ icon, title, text, tags: string[] }]`) |
-| `reference` | collection reference: entry summary `{ id, slug, label }` or `null`; media reference (`model: "Media"`): the media id, plus `<key>_media` with `{ id, url, file_name, mime_type, size, is_public }` or `null` |
+| `reference` | collection reference: entry summary `{ id, slug, label }` or `null`; media reference (`model: "Media"`): the media id, plus `<key>_media` with `{ id, url, file_name, mime_type, size, is_public, image_transform_base }` or `null` |
 | `multiReference` | collection: array of entries; media (`model: "Media"`): array of media ids, plus `<key>_media` with the files in the same order (missing files are skipped) |
 
 Entries expose media references the same way (`entry.image` is the id, `entry.image_media.url` the file).
@@ -124,21 +124,73 @@ const items = solutions?.data.items ?? [];
 items.map((item) => `${item.title}: ${item.tags.join(", ")}`);
 
 const hero = home.block("hero");
-const heroUrl = hero?.data.image_media?.url;           // reference, model "Media"
+const heroUrl = crafty.image(hero?.data.image_media, { width: 1600, format: "auto" }); // reference, model "Media"
 const slides = hero?.data.gallery_media ?? [];         // multiReference, model "Media"
 ```
 
+### Images: always go through `crafty.image()`
+
+Render every Crafty image with `crafty.image(media, { width, format: "auto" })` (and `crafty.srcset(media, widths, { format: "auto" })` for responsive images) instead of the raw `url`. Sites that ship the original upload fail Core Web Vitals (LCP).
+
+```tsx
+const photo = block.data.image_media;
+
+<img
+  src={crafty.image(photo, { width: 800, format: "auto" })}
+  srcSet={crafty.srcset(photo, [400, 800, 1200, 1600], { format: "auto" })}
+  sizes="(min-width: 768px) 50vw, 100vw"
+  width={800}
+  height={450}
+  loading="lazy"
+  alt={block.data.title ?? ""}
+/>
+```
+
+- `crafty.image(media, { width?, height?, fit?, quality?, format? })` → string. `media` is a `<key>_media` object, a `CraftyMediaFile`, or a URL string. `width`/`height` 1–4096, `quality` 1–100, `fit`: `scale-down` | `contain` | `cover` | `crop` | `pad`, `format`: `auto` | `webp` | `avif` | `jpeg` | `png`. Invalid options are dropped.
+- `crafty.srcset(media, widths, options?)` → `"<url> 400w, <url> 800w"`, or `""` when the image cannot be transformed.
+- Pick `width` from the rendered size (about 2x for retina on small images); use `fit: "cover"` with both `width` and `height` for fixed-ratio cards and thumbnails.
+- Transforms only apply to **public** raster images when the Crafty server has Cloudflare Image Transformations enabled (the media then carries `image_transform_base`). Otherwise `image()` returns the original `url` and `srcset()` returns `""`, so the same code always works. Upload images to a public repository (`manage_media_collection` with `is_public: true`) when the site needs permanent, resizable URLs.
+- Use `og:image` with `crafty.image(media, { width: 1200, height: 630, fit: "cover", format: "jpeg" })`: social scrapers do not support AVIF/WebP negotiation.
+- Do not hand-build `/cdn-cgi/image/...` URLs or append `?w=` query parameters.
+
 Prefer modelling lists as `repeater` / `stringList` fields on a block type over collections or `json` fields; see the `crafty-cms` skill.
 
+### Generated types (`crafty types`)
+
+Do not guess field keys or shapes: generate them from the site's real content models with the CLI.
+
+```bash
+npx @craftware/crafty-cli types                       # CRAFTY_API_URL + CRAFTY_API_KEY from .env
+npx @craftware/crafty-cli types --api-key=$KEY --url=https://<tenant>.crafty.do --out=src/crafty.types.ts
+```
+
+It reads `GET /api/v1/schema` (JSON Schema of every collection and block type of the API key's environment, versioned by `format_version`) and writes `crafty.types.ts`:
+
+- `<Slug>Entry` per collection (entry metadata + fields), `<Slug>BlockData` and `<Slug>Block` per block type, the `CraftyPageBlock` union (discriminated by `type`), the `CraftyCollectionTypes` / `CraftyBlockDataTypes` slug maps, and `CraftyEntryReference` / `CraftyMediaSummary`.
+- `select` → union of option values, `stringList` → `string[]`, `repeater` → array of item objects, `json` → `unknown`; optional fields are `| null`.
+
+```ts
+import type { CarsEntry, CraftyPageBlock } from "./crafty.types";
+
+const cars = (await crafty.entries.list("cars")).data as unknown as CarsEntry[];
+const page = await crafty.pages.get("home");
+for (const block of page.blocks as unknown as CraftyPageBlock[]) {
+  if (block.type === "hero") block.data.heading; // HeroBlockData
+}
+```
+
+Types depend on the environment (generate with the key of the environment the code targets) and go stale when a collection or block type changes — re-run the command after `create_block_type`, `update_block_type`, `create_collection` or `update_collection`.
+
 ### `forms`
 
 ```ts
 crafty.forms.list(options?)                  // => { data: CraftyForm[] }            (requires apiKey)
 crafty.forms.get(slug, options?)             // => { data: CraftyForm }              (requires apiKey)
-crafty.forms.submit(formSlug, data, options?) // => { id, form_id, submitted_at }   (public, no apiKey)
+crafty.forms.submit(formSlug, data, options?) // => { id, form_id, submitted_at }   (public; apiKey optional, picks the environment)
+crafty.forms.captcha(form, container)         // => CraftyFormCaptcha | null           (browser; renders the form's captcha widget)
 ```
 
-`forms.submit()` uses a **public** endpoint: it sends no `X-API-Key`, but it **requires `siteSlug` in the client config** — calling it without one throws a synchronous `CraftyError` with code `BAD_REQUEST`.
+`forms.submit()` uses a **public** endpoint: the `X-API-Key`, when configured, only selects the environment (a staging key submits to staging, no key submits to production), but it **requires `siteSlug` in the client config** — calling it without one throws a synchronous `CraftyError` with code `BAD_REQUEST`.
 
 ```ts
 const crafty = createCraftyClient({
@@ -154,6 +206,17 @@ const result = await crafty.forms.submit("contact", {
 // => { id, form_id, submitted_at }
 ```
 
+Forms protected by a captcha return `captcha: { provider, site_key, token_field }` (absent otherwise), and their submissions are rejected with 422 without the widget token. In the browser, render the widget next to the form and pass it to `submit()`:
+
+```ts
+const { data: form } = await crafty.forms.get("contact");
+const captcha = await crafty.forms.captcha(form, document.querySelector("#captcha")!); // null when not needed
+
+await crafty.forms.submit("contact", values, { captcha }); // adds the token, then resets the widget
+```
+
+Turnstile runs invisibly and only shows a challenge to suspicious visitors. Without the SDK, load the provider script yourself and post the token in `captcha.token_field`.
+
 > Note the asymmetry: `collections.get()` returns the bare object, while `forms.get()` and `entries.get()` are wrapped in `{ data }`.
 
 ### `mediaCollections`
@@ -170,7 +233,7 @@ crafty.mediaCollections.list(query?, options?)  // => { data: CraftyMediaCollect
 crafty.mediaFiles.list(query?, options?)  // => { data: CraftyMediaFile[], links, meta: { ...pagination, ttl_minutes } }
 ```
 
-`query`: `collection`, `directory_id`, `ttl_minutes` (signed-URL lifetime), `per_page`, `page`.
+`query`: `collection`, `directory_id`, `ttl_minutes` (signed-URL lifetime), `per_page`, `page`. Each file has `url`, `is_public`, `expires_at` and `image_transform_base`; pass the file to `crafty.image()` to render it.
 
 ## `llms.txt`
 
@@ -230,6 +293,19 @@ crafty.analytics.load(options?)  // browser only => "loaded" | "already-loaded"
 
 Never hard-code GTM / GA4 / pixel snippets in the site, and never add GA4 both here and inside GTM (page views are counted twice).
 
+## Structured data
+
+The public API serves schema.org JSON-LD in `structured_data`: on the home page (`pages.get(homeSlug)`, the business set with `configure_structured_data`), on `crafty.site.get()`, and on each published entry of a collection with a structured data mapping (`structured_data` on `create_collection` / `update_collection`). It is `null` when nothing is configured or a required property is empty.
+
+```ts
+crafty.site.get(options?)                 // => { name, slug, environment, default_locale, locales, structured_data }
+crafty.structuredData(...sources)         // => '<script type="application/ld+json">…</script>' tags, "" when none
+crafty.jsonLd(...sources)                 // => the JSON-LD objects, for useHead / <Head>
+crafty.faqPage([{ question, answer }])    // => FAQPage JSON-LD for a FAQ block, or null
+```
+
+Sources can be pages, entries, their API responses, list responses, the site or JSON-LD objects; FAQPage objects are merged into one per page. The script content escapes `<`, so it is safe to inject as raw HTML (`set:html`, `v-html`, `dangerouslySetInnerHTML`). Validate the result at https://search.google.com/test/rich-results.
+
 ## Error handling
 
 The SDK throws `CraftyError` for HTTP, timeout, abort, network, and config failures.
@@ -284,6 +360,7 @@ try {
 
 - `attrs(target, field, { label? })` / `crafty.attrs(...)` → `{ "data-crafty-block" | "data-crafty-entry", "data-crafty-field", "data-crafty-label"? }` to spread on the element that renders the value; `{}` when the target has no valid id. `field` is a field key or a path into a list or JSON value (`sections[3].title`, `items[2].title` for a block-type `repeater`, `tags[1]` for a `stringList`, `items[0].tags[1]` for a stringList inside a repeater item). The index is the item's position in the stored data.
 - `attrsHtml(target, field, { label? })` → the same attributes as an escaped HTML string.
+- `image(media, options?)` / `crafty.image(...)` and `srcset(media, widths, options?)` / `crafty.srcset(...)` → resized image URLs; see "Images: always go through `crafty.image()`".
 - `previewFromRequest(req)` → preview token of an incoming request (URL string, `URL`, Web `Request`, Node `req.url`, Express `req.query`) or `null`.
 - `readPreviewToken()` → token in the browser, or `null`.
 - `enableVisualEditing(options)` from `@craftware/crafty-sdk/visual-editing` → connects the page to the editor; no-op outside the admin iframe. Options: `onRefresh`, `adminOrigins`, `page`, `entries`, `touchHighlightMs`.