@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/localization.md

@@ -1,85 +1,85 @@
----
-title: "Localization"
-description: "Document-per-locale translations (locale, translationOf, translate_entry, delivery translations), URL-prefixed locale copies of imported builds, Layout locale variants, locale-unvarianted, hreflang, and what never to model."
----
-
-# Localization
-
-**Outcome.** A multilingual site keeps every language rendering, each language's copy is
-editable, and nothing invents a locale model the platform does not read.
-
-Two things are called a "language" here, and they are separate:
-
-- **A translation** is its own entry or page row, one per locale: `locale` is its BCP-47 tag (one
-  of the project's locales; null = the default language) and `translationOf` is the SOURCE row's
-  id. Each has its own slug, draft and publish state.
-- **A locale copy of an imported build** is a URL prefix (`/fr`, `/pt-br`) proven by the page's own
-  `<html lang>`. It is how a converted site's languages arrive, before anyone models them.
-
-## 1. What exists
-
-| Piece | How it works |
-|---|---|
-| The project's locales | `localeConfig.locales`: the owner's list (project settings) plus every page language an import finds. A `locale` outside it is refused with 400; an empty list means a single-language project. Tags are stored canonical (`zh-CN` → `zh-cn`) |
-| A page's language | `list_pages` / `get_page` return `language` (its `locale`, else the `<html lang>` its import declared; null = the default) and `path`. Set it with `create_page` / `update_page` `locale` |
-| Address a page | By id or `path` (`/de/construction/safety`). A slug repeats across language folders, so a bare slug works only when one page has it; otherwise the tool refuses with each match's id, path and language. Never guess one |
-| Translate an entry with AI | `translate_entry` { entryId, targetLocale, slug?, fields? } creates the translation as a DRAFT with `locale` and `translationOf` set (AI credits: 402/403 when out or not on the plan). Text and longtext are translated; rich text and documents are copied for you to translate; `meta` lists which. `409 locale_conflict`: that translation exists, so edit it instead |
-| Create one by hand | `create_content_entry` or `create_page` with `locale` and `translationOf` = the source's id, never another translation's. One row per locale per source (a second is `409 locale_conflict`); `update_content_entry` / `update_page` change either, null clears |
-| Find them | `list_content_entries` `where: { locale: 'fr' }`; default-language rows have a null `locale`, so they match `{ locale: { ne: 'fr' } }`, never `eq` |
-| Deliver them | Every delivered entry carries `locale`, `translationOf` and `translations`: `[{ id, locale, slug }]` of its group's other PUBLISHED rows (drafts only when previewing). A delivered page carries `locale` and `translationOf` |
-| Translate one string | `write_content` with `action: "translate"` and `targetLang` returns the text; apply it with `set_page_content` or `update_content_entry` |
-| Locale copy of an imported page | A page whose route opens with a language prefix its own `<html lang>` confirms (`/fr` on a French page). The prefix is proven by the page's language, never by the segment's shape: `/de` is a locale only on a German page |
-| Componentizing a locale copy | `get_componentize_plan` places `/fr` on its default-locale twin's components, band by band, when each pair holds the same prop types in the same order; a mismatched band stays its own section. `componentize_sections` `joinTwins` moves older copies onto their twin's components |
-| Layout locale variants | A Global Layout Section can have a variant per locale (`navigation--fr`). A page renders the variant whose locale is its route's first segment, else the base |
-| `locale-unvarianted` | A `get_binding_report` unmatched reason: the route resolved in a locale, the Section has no variant for it, and the base still renders there. Named, never written |
-
-Import derives deeper locale routes (`/fr/about`) as pages in a URL folder (`fr`), each recording
-the language its `<html lang>` declares, and the Content sidebar files them under Pages › <language>.
-A locale prefix is never a collection, but a collection's localized posts (`/fr/blog/post-1`, its
-`<html lang>` agreeing) are entries of that collection with `locale` set, `translationOf` the post
-their hreflang alternate (else their slug) names, slug `<slug>-<locale>`, served at
-`/<locale>/<collection>/<slug>`; the project's locales gain each language found. An edit to `/about` never reaches `/fr/about`; edit each page or entry.
-
-## 2. Never model
-
-- **No `language`, `locale` or `lang` field** on a model, page or component, and no
-  `translations` reference field between entries. The language is the native `locale`, the link
-  is the native `translationOf`, and delivery derives `translations` from them.
-- **No hreflang, alternate-URL or canonical-per-language field.** SEO is native
-  ([seo.md](seo.md)), and the native columns have no locale slot.
-- **No per-language copy of a field** (`titleFr`, `titleEn`). It doubles every edit and leaves
-  the page's language implicit in a key name.
-
-## 3. Where hreflang comes from
-
-The frontend writes the `<head>` links. For each entry, render `<link rel="alternate" hreflang="…">`
-for itself and for every row in its delivered `translations` (the locale is the tag, the slug
-builds the URL on the site's own route pattern), plus `x-default` for the default-language row.
-Hosted `<head>` output emits none.
-
-The hosted sitemap does emit them. Every listed page or entry in a translation group (the source
-plus its `translationOf` rows) carries `<xhtml:link rel="alternate" hreflang>` for each listed
-sibling, itself included, plus `x-default` for the source. A row with no `locale` takes the
-project's `localeConfig.defaultLanguage`; with neither, it gets no link of its own. Unpublished
-and noindex siblings are not listed, so they get no link either. Check the live `sitemap.xml`.
-
-## 4. Workflow
-
-For a site modelled in the CMS:
-
-1. Confirm the owner has set the project's locales; you cannot.
-2. Per source entry, `translate_entry` into each locale (or create the row by hand), then
-   translate the copied rich text with `write_content` and write it with `update_content_entry`.
-3. Review each draft with the user, publish it (`publish_entries` takes many), and check the
-   source's delivered `translations` lists it.
-4. Emit hreflang from `translations` in the frontend (§3) and fetch each language's URL.
-
-For a multilingual import:
-
-1. List the prefixes the build serves and confirm each page's `<html lang>` matches its prefix.
-2. Componentize the default language first; the plan then places each locale copy on its twin.
-3. Read `get_binding_report` on each prefixed route: `locale-unvarianted` rows are the Layout
-   Sections still showing the default language there. `update_layout` takes no locale, so name
-   those Sections to the user rather than writing translated copy onto the base.
-4. Translate with `write_content`, apply, publish, and fetch each prefixed URL.
-5. Report the routes that stay build-only (the editor setup's `pages` note names any) with their count.
+---
+title: "Localization"
+description: "Document-per-locale translations (locale, translationOf, translate_entry, delivery translations), URL-prefixed locale copies of imported builds, Layout locale variants, locale-unvarianted, hreflang, and what never to model."
+---
+
+# Localization
+
+**Outcome.** A multilingual site keeps every language rendering, each language's copy is
+editable, and nothing invents a locale model the platform does not read.
+
+Two things are called a "language" here, and they are separate:
+
+- **A translation** is its own entry or page row, one per locale: `locale` is its BCP-47 tag (one
+  of the project's locales; null = the default language) and `translationOf` is the SOURCE row's
+  id. Each has its own slug, draft and publish state.
+- **A locale copy of an imported build** is a URL prefix (`/fr`, `/pt-br`) proven by the page's own
+  `<html lang>`. It is how a converted site's languages arrive, before anyone models them.
+
+## 1. What exists
+
+| Piece | How it works |
+|---|---|
+| The project's locales | `localeConfig.locales`: the owner's list (project settings) plus every page language an import finds. A `locale` outside it is refused with 400; an empty list means a single-language project. Tags are stored canonical (`zh-CN` → `zh-cn`) |
+| A page's language | `list_pages` / `get_page` return `language` (its `locale`, else the `<html lang>` its import declared; null = the default) and `path`. Set it with `create_page` / `update_page` `locale` |
+| Address a page | By id or `path` (`/de/construction/safety`). A slug repeats across language folders, so a bare slug works only when one page has it; otherwise the tool refuses with each match's id, path and language. Never guess one |
+| Translate an entry with AI | `translate_entry` { entryId, targetLocale, slug?, fields? } creates the translation as a DRAFT with `locale` and `translationOf` set (AI credits: 402/403 when out or not on the plan). Text and longtext are translated; rich text and documents are copied for you to translate; `meta` lists which. `409 locale_conflict`: that translation exists, so edit it instead |
+| Create one by hand | `create_content_entry` or `create_page` with `locale` and `translationOf` = the source's id, never another translation's. One row per locale per source (a second is `409 locale_conflict`); `update_content_entry` / `update_page` change either, null clears |
+| Find them | `list_content_entries` `where: { locale: 'fr' }`; default-language rows have a null `locale`, so they match `{ locale: { ne: 'fr' } }`, never `eq` |
+| Deliver them | Every delivered entry carries `locale`, `translationOf` and `translations`: `[{ id, locale, slug }]` of its group's other PUBLISHED rows (drafts only when previewing). A delivered page carries `locale` and `translationOf` |
+| Translate one string | `write_content` with `action: "translate"` and `targetLang` returns the text; apply it with `set_page_content` or `update_content_entry` |
+| Locale copy of an imported page | A page whose route opens with a language prefix its own `<html lang>` confirms (`/fr` on a French page). The prefix is proven by the page's language, never by the segment's shape: `/de` is a locale only on a German page |
+| Componentizing a locale copy | `get_componentize_plan` places `/fr` on its default-locale twin's components, band by band, when each pair holds the same prop types in the same order; a mismatched band stays its own section. `componentize_sections` `joinTwins` moves older copies onto their twin's components |
+| Layout locale variants | A Global Layout Section can have a variant per locale (`navigation--fr`). A page renders the variant whose locale is its route's first segment, else the base |
+| `locale-unvarianted` | A `get_binding_report` unmatched reason: the route resolved in a locale, the Section has no variant for it, and the base still renders there. Named, never written |
+
+Import derives deeper locale routes (`/fr/about`) as pages in a URL folder (`fr`), each recording
+the language its `<html lang>` declares, and the Content sidebar files them under Pages › <language>.
+A locale prefix is never a collection, but a collection's localized posts (`/fr/blog/post-1`, its
+`<html lang>` agreeing) are entries of that collection with `locale` set, `translationOf` the post
+their hreflang alternate (else their slug) names, slug `<slug>-<locale>`, served at
+`/<locale>/<collection>/<slug>`; the project's locales gain each language found. An edit to `/about` never reaches `/fr/about`; edit each page or entry.
+
+## 2. Never model
+
+- **No `language`, `locale` or `lang` field** on a model, page or component, and no
+  `translations` reference field between entries. The language is the native `locale`, the link
+  is the native `translationOf`, and delivery derives `translations` from them.
+- **No hreflang, alternate-URL or canonical-per-language field.** SEO is native
+  ([seo.md](seo.md)), and the native columns have no locale slot.
+- **No per-language copy of a field** (`titleFr`, `titleEn`). It doubles every edit and leaves
+  the page's language implicit in a key name.
+
+## 3. Where hreflang comes from
+
+The frontend writes the `<head>` links. For each entry, render `<link rel="alternate" hreflang="…">`
+for itself and for every row in its delivered `translations` (the locale is the tag, the slug
+builds the URL on the site's own route pattern), plus `x-default` for the default-language row.
+Hosted `<head>` output emits none.
+
+The hosted sitemap does emit them. Every listed page or entry in a translation group (the source
+plus its `translationOf` rows) carries `<xhtml:link rel="alternate" hreflang>` for each listed
+sibling, itself included, plus `x-default` for the source. A row with no `locale` takes the
+project's `localeConfig.defaultLanguage`; with neither, it gets no link of its own. Unpublished
+and noindex siblings are not listed, so they get no link either. Check the live `sitemap.xml`.
+
+## 4. Workflow
+
+For a site modelled in the CMS:
+
+1. Confirm the owner has set the project's locales; you cannot.
+2. Per source entry, `translate_entry` into each locale (or create the row by hand), then
+   translate the copied rich text with `write_content` and write it with `update_content_entry`.
+3. Review each draft with the user, publish it (`publish_entries` takes many), and check the
+   source's delivered `translations` lists it.
+4. Emit hreflang from `translations` in the frontend (§3) and fetch each language's URL.
+
+For a multilingual import:
+
+1. List the prefixes the build serves and confirm each page's `<html lang>` matches its prefix.
+2. Componentize the default language first; the plan then places each locale copy on its twin.
+3. Read `get_binding_report` on each prefixed route: `locale-unvarianted` rows are the Layout
+   Sections still showing the default language there. `update_layout` takes no locale, so name
+   those Sections to the user rather than writing translated copy onto the base.
+4. Translate with `write_content`, apply, publish, and fetch each prefixed URL.
+5. Report the routes that stay build-only (the editor setup's `pages` note names any) with their count.

package/dist/skills/bettercms/references/media-and-brand.md

@@ -1,181 +1,181 @@
----
-title: "Brand kit and media"
-description: "Brand tokens, fonts, logo kit, image sizing and focal point, SVG and video rules, and the media host."
----
-
-# Brand kit, section styles and media
-
-**Outcome.** An imported site keeps its appearance, and editors change the intended brand and
-media controls through one coherent system instead of scattered CSS values.
-
-## Audit sources and the rendered design
-
-Inspect CSS variables, the Tailwind or theme config, design-token files, `@font-face`, layout
-components, media directories, responsive assets and computed styles on representative routes.
-Compare desktop and mobile screenshots. Record where each proposed token came from and how often
-it is used. One colour on one button is not a brand identity.
-
-Build a token inventory: role, source value, proposed BetterCMS value, affected components,
-confidence, approval status. Cover colours, type families, weights and scale, spacing, container
-widths, radius, borders, elevation, motion and breakpoints. Group colours into semantic roles
-(primary, accent, background, surface, text, muted, status colours). Keep raw source values as
-evidence, never as every component's editable prop.
-
-## What the brand kit is, and who writes it
-
-- `get_project` returns `brandKit`: colours (`primary`, `accent`, `background`, `surface`,
-  `text`, `muted`), `typography` (`headingFont`, `bodyFont`), `radius` (`sharp`/`rounded`/`pill`),
-  and optional `typeScale`, `spacing`, `elevation`, `motion` and gradients. A project that never
-  saved one still returns the default kit.
-- **Colours and typography are edited in the dashboard**; no MCP tool writes them. Prepare a
-  precise proposal and map the source CSS to it; never say you changed them.
-- **The logo mark and favicon** are written with `set_brand_assets`, by the id of a media asset
-  of this project (upload it first). A slot a person chose is refused unless you pass
-  `replace: true`; ask before passing it.
-- **Gradients** are written with `set_brand_graphics`: a kind, an optional angle and 2-8 stops
-  that name kit colour keys, never a hex or a CSS string.
-- Every brand write is a version a person can restore in the dashboard.
-- The hosted renderer emits the kit as `--bcms-*` and `--brand-*` CSS custom properties, which
-  reach hosted pages only. A self-hosted site owns its tokens: bind its own presentation
-  variables to the approved kit, and declare its presentation in `bcms-presentation.json` at the
-  root of the deployed artifact.
-- `update_project` `presentation` themes the platform's own renderer with the same closed knobs
-  as a release's `bcms-presentation.json`. It does not restyle a deployed build.
-
-## Section styles
-
-Section style props are closed tokens, not free CSS: space is `none|xs|sm|md|lg|xl`, colour is
-`none|white|black|muted|mutedBg|primary|accent`. Never put a hex value from the brand into block
-props: a token follows a brand change, a copied hex does not. Style inspector properties:
-`CM-27`. Expose a curated choice (for example
-`Surface: Light / Dark / Brand`); never ask an editor for a hex, a class name or a font path.
-Say whether a change is brand-wide or one instance, and test that a token change keeps contrast
-and layout intact in every variant. Offer only controls the renderer actually applies; a missing
-style binding is a code or platform task, not a dashboard promise.
-
-## Typography and fonts
-
-Inventory family stacks, weights, styles, variable axes, local files, remote providers and
-where each is used. Match heading and body roles to the rendered code; do not swap a display
-face for the body face because it appears less often. Keep fallbacks and the loading strategy.
-Self-host a font file only when its licence allows it; otherwise keep the provider reference and
-list the dependency. Record licence evidence or "licence unknown".
-
-Keep semantic HTML apart from visual size: an H2 may use a display token without becoming an
-H1. Expose typography variants only where the design allows a real choice.
-
-## Logos, images, icons and video
-
-- **Logo kit.** Roles: primary, reverse, dark, compact mark, wordmark, favicon, where the source
-  proves them; mark the rest unclassified. Keep vector originals and transparency. The navigation
-  logo is a stored image on the layout; replace it there ([components.md](components.md) §4),
-  not in each page.
-- **Images.** A stored image value is an object (`url`, `altText`, asset id), never a bare
-  string; read it as one. Alt text, decorative state and caption belong to the usage. Keep
-  `srcset`/`sizes`, poster, lazy/preload intent and art direction (a publish keeps them too:
-  [bindings.md](bindings.md) Images). Decorative images render an
-  empty `alt`; informative ones need text that fits the context. `update_media` with
-  `decorative: true` marks a library asset decorative, so the audit stops asking for its alt text.
-- **Request the size you render.** Mint resize URLs with `@bettercms-ai/image-url`
-  (`urlFor = imageUrlBuilder({ baseUrl: mediaUrl })`, then `urlFor(asset).size(800, 450).url()`;
-  also `width`, `format`, `quality`, `fit`, `dpr` 1–3) and a
-  `srcset` of the widths the layout actually uses. Why: the original upload is often several
-  thousand pixels wide, and an unresized `url` ships all of it.
-- **Framing lives on the value, never in the model.** An asset carries one focal point (0–1
-  fractions), set with `update_media` `focalX`/`focalY` (null resets to the centre) or in the
-  dashboard; a URL with both dimensions and `fit` cover crops around it automatically. One
-  PLACEMENT can differ: the image value itself may carry `focal: { x, y }` and
-  `crop: { top, right, bottom, left }` (0–1, cut from each edge; the crop must leave a visible
-  window). The value's focal wins over the asset's; absent keys fall back to the asset. Draw a
-  value with `imageValueUrl(value, { w, h })` and `imageValueObjectPosition(value)` from
-  `@bettercms-ai/image-url`, never `.url` alone, or the crop is lost. The dashboard's asset Crop
-  rewrites the stored bytes for every usage. Never add focal or crop FIELDS to a model: they
-  belong on the image value.
-- **Image block width.** An image block's `props.width` is pixels, and every lane caps it at
-  the column (`max-width:100%`, height auto). Leave it unset to fill the column.
-- **Rich-text images.** A `builtin:image` block takes `align` (`full` | `center` | `left` |
-  `right`) and `size` (`small` | `medium` | `large` | `full`) in its fields. Both render on every
-  lane, with inline widths, so no site CSS is needed.
-- **Image facts ride on the delivered value.** Delivery adds `width`, `height`, `thumbHash` (a
-  ThumbHash placeholder) and `focalX`/`focalY` to each image value, read at request time and
-  omitted while unknown (object values only: a bare URL string stays a string). Reserve the box from `width`/`height`, decode `thumbHash` for a blur-up,
-  and fall back to a tiny variant (`width(24)`) when it is absent.
-- **Generate or edit an image.** `generate_image` { prompt, width?, height?, altText } adds an AI
-  image to the Media Library; `transform_image` { mediaId, prompt } saves an edited copy as a NEW
-  asset and keeps the original. Each costs 5 AI credits (free with the workspace's own Together
-  key). Always set `altText`, and use them only where the user wants generated imagery: never to
-  stand in for a real product, person or place.
-- **SVG.** Every SVG upload is sanitised on the way in, and SVGs are served as vectors (no
-  raster variants). Keep safe icons as SVG and expose icon choice, size and colour token.
-  Functional icons need an accessible label or adjacent text. Editing SVG paths is not a CMS
-  feature; the text inside an SVG is not a bindable field ([bindings.md](bindings.md) §2).
-- **Video.** Inventory format, host, poster, captions, autoplay/mute/loop and cost. Do not copy
-  every video into the media library by default; keep a streaming provider reference where the
-  site depends on one.
-
-## Where images hide
-
-Setup makes every picture an image field backed by a library asset, in code, with no step for
-you: the release adopts each media file the build ships (alt text from the markup, its size, and
-a default focal point you can move with `update_media`), derives the fields, and links each
-value to its asset. Check it, never redo it: the binding report's `elementCoverage.image` is
-`editable / total`, and `imageGaps` names what is not a field, misses first.
-
-| Code | The picture | What to do |
-|---|---|---|
-| `IMG_DATA_URI`, `IMG_NO_SOURCE` | An `<img>` inlined as `data:`, or filled in by a script | Ship it as a file with a real `src` |
-| `BG_PSEUDO_ELEMENT` | A background on `::before` / `::after` | Move it onto the element, or render an `<img>` |
-| `BG_ON_TEXT` | A background on an element that is itself a text field, or on a section whose copy sits directly in it. A section that keeps its copy in one wrapper is never listed: the picture is the section's field and the copy the wrapper's | Wrap the text, so the box and the words are two elements |
-| `SVG_TOO_LARGE` | An inline `<svg>` past 64 KB | Ship it as an `.svg` file in an `<img>` |
-| `SVG_SPRITE` | A `<use>` naming a symbol the page does not hold, or a sprite FILE the build does not ship (another host's, a relative path) | Inline the symbol in the page, serve the sprite from the site root, or ship the icon as its own `<svg>` |
-| `IMAGE_NOT_ASSET` | A header or footer picture the Media library holds no asset for | Nothing lost: the rest of the region is the Layout's and this picture stays a field of each page. Setup tries it again on the next build |
-| `SVG_NOT_ICON`, `SVG_DECORATIVE` | An `<svg>` holding a script, an HTML island or a remote image; an `aria-hidden` glyph in the nav or footer, or a nameless one on an older import | Decoration: leave it, or give a logo `role="img"` and an `aria-label` |
-| `BG_SPRITE`, `BG_TINY`, `BG_PATTERN`, `BG_DATA_URI`, `BG_STATE` | A sprite, an icon-sized box, a tile, an inlined texture, a hover image | Decoration: leave it |
-
-The first four rows count against the image coverage; the rest do not. A gap you cannot
-close is reported with its code, never described as done.
-
-An icon a sprite file draws (`<use href="/sprite.svg#shield">`, a same-site `.svg` the build
-ships) is an image field like any inline icon. An icon a FONT draws (`<i class="ph ph-tag">`) is
-a text field holding the class, written to the `class` attribute alone: change the class to
-change the glyph.
-
-`elementGaps` is the same record for everything that is not a picture (`rows` carry a `sample`
-where an image row has a `src`). `EMBED_NOT_VIDEO` (an `<iframe>` that is no video provider's),
-`AUDIO_SOURCE` and `ICON_FONT` (a font icon inside a paragraph that is one rich-text value) are
-shown and editable nowhere, and count against coverage. The rest are declined on purpose and
-never count: `SKIP_LINK`, `FRAMEWORK_UI` (a docs framework's pager, table of contents or
-search), `FRAGMENT_LINK` (an in-page `#` destination under those rules), `ORDINAL_MARKER` (a
-step number the template counts out, on a project imported before step numbers were fields),
-`TEMPLATE_TEXT`, `NOSCRIPT_TEXT` and `HEAD_META_UNMAPPED` (a `<meta>` no native SEO field holds,
-by name).
-
-## Media host
-
-Use `mediaBaseUrl` from `get_project`: media is served from the CDN origin or the API origin of
-the backend that owns the asset ids. `set_media_delivery` is the owner's decision, asked every
-time. If a stored URL 404s, find the owning asset and report it; never re-save content to "move"
-assets. How templates and resize URLs use it: [frameworks.md](frameworks.md) Media host.
-
-## Presentation-mode UX
-
-Show only meaningful controls, and state the scope before a change:
-
-```text
-Brand                    [sitewide, reviewed]
-  Logos · Colors · Typography · Spacing / Radius / Motion
-
-Selected hero image      [this instance]
-  Asset · Alt text / Decorative · Caption
-```
-
-Keep provenance and licence status visible to developers, away from everyday editing.
-
-## Acceptance
-
-- Every local asset resolves from the project's media store; external dependencies are listed.
-- Logo roles and fonts carry evidence and licence status.
-- Colour, type and spacing changes go through tokens and keep contrast and responsive layout.
-- Editing a usage's alt text or caption changes the right rendered image.
-- Icons work in every intended theme and state.
-- Baseline and changed screenshots are compared; material differences are explained.
+---
+title: "Brand kit and media"
+description: "Brand tokens, fonts, logo kit, image sizing and focal point, SVG and video rules, and the media host."
+---
+
+# Brand kit, section styles and media
+
+**Outcome.** An imported site keeps its appearance, and editors change the intended brand and
+media controls through one coherent system instead of scattered CSS values.
+
+## Audit sources and the rendered design
+
+Inspect CSS variables, the Tailwind or theme config, design-token files, `@font-face`, layout
+components, media directories, responsive assets and computed styles on representative routes.
+Compare desktop and mobile screenshots. Record where each proposed token came from and how often
+it is used. One colour on one button is not a brand identity.
+
+Build a token inventory: role, source value, proposed BetterCMS value, affected components,
+confidence, approval status. Cover colours, type families, weights and scale, spacing, container
+widths, radius, borders, elevation, motion and breakpoints. Group colours into semantic roles
+(primary, accent, background, surface, text, muted, status colours). Keep raw source values as
+evidence, never as every component's editable prop.
+
+## What the brand kit is, and who writes it
+
+- `get_project` returns `brandKit`: colours (`primary`, `accent`, `background`, `surface`,
+  `text`, `muted`), `typography` (`headingFont`, `bodyFont`), `radius` (`sharp`/`rounded`/`pill`),
+  and optional `typeScale`, `spacing`, `elevation`, `motion` and gradients. A project that never
+  saved one still returns the default kit.
+- **Colours and typography are edited in the dashboard**; no MCP tool writes them. Prepare a
+  precise proposal and map the source CSS to it; never say you changed them.
+- **The logo mark and favicon** are written with `set_brand_assets`, by the id of a media asset
+  of this project (upload it first). A slot a person chose is refused unless you pass
+  `replace: true`; ask before passing it.
+- **Gradients** are written with `set_brand_graphics`: a kind, an optional angle and 2-8 stops
+  that name kit colour keys, never a hex or a CSS string.
+- Every brand write is a version a person can restore in the dashboard.
+- The hosted renderer emits the kit as `--bcms-*` and `--brand-*` CSS custom properties, which
+  reach hosted pages only. A self-hosted site owns its tokens: bind its own presentation
+  variables to the approved kit, and declare its presentation in `bcms-presentation.json` at the
+  root of the deployed artifact.
+- `update_project` `presentation` themes the platform's own renderer with the same closed knobs
+  as a release's `bcms-presentation.json`. It does not restyle a deployed build.
+
+## Section styles
+
+Section style props are closed tokens, not free CSS: space is `none|xs|sm|md|lg|xl`, colour is
+`none|white|black|muted|mutedBg|primary|accent`. Never put a hex value from the brand into block
+props: a token follows a brand change, a copied hex does not. Style inspector properties:
+`CM-27`. Expose a curated choice (for example
+`Surface: Light / Dark / Brand`); never ask an editor for a hex, a class name or a font path.
+Say whether a change is brand-wide or one instance, and test that a token change keeps contrast
+and layout intact in every variant. Offer only controls the renderer actually applies; a missing
+style binding is a code or platform task, not a dashboard promise.
+
+## Typography and fonts
+
+Inventory family stacks, weights, styles, variable axes, local files, remote providers and
+where each is used. Match heading and body roles to the rendered code; do not swap a display
+face for the body face because it appears less often. Keep fallbacks and the loading strategy.
+Self-host a font file only when its licence allows it; otherwise keep the provider reference and
+list the dependency. Record licence evidence or "licence unknown".
+
+Keep semantic HTML apart from visual size: an H2 may use a display token without becoming an
+H1. Expose typography variants only where the design allows a real choice.
+
+## Logos, images, icons and video
+
+- **Logo kit.** Roles: primary, reverse, dark, compact mark, wordmark, favicon, where the source
+  proves them; mark the rest unclassified. Keep vector originals and transparency. The navigation
+  logo is a stored image on the layout; replace it there ([components.md](components.md) §4),
+  not in each page.
+- **Images.** A stored image value is an object (`url`, `altText`, asset id), never a bare
+  string; read it as one. Alt text, decorative state and caption belong to the usage. Keep
+  `srcset`/`sizes`, poster, lazy/preload intent and art direction (a publish keeps them too:
+  [bindings.md](bindings.md) Images). Decorative images render an
+  empty `alt`; informative ones need text that fits the context. `update_media` with
+  `decorative: true` marks a library asset decorative, so the audit stops asking for its alt text.
+- **Request the size you render.** Mint resize URLs with `@bettercms-ai/image-url`
+  (`urlFor = imageUrlBuilder({ baseUrl: mediaUrl })`, then `urlFor(asset).size(800, 450).url()`;
+  also `width`, `format`, `quality`, `fit`, `dpr` 1–3) and a
+  `srcset` of the widths the layout actually uses. Why: the original upload is often several
+  thousand pixels wide, and an unresized `url` ships all of it.
+- **Framing lives on the value, never in the model.** An asset carries one focal point (0–1
+  fractions), set with `update_media` `focalX`/`focalY` (null resets to the centre) or in the
+  dashboard; a URL with both dimensions and `fit` cover crops around it automatically. One
+  PLACEMENT can differ: the image value itself may carry `focal: { x, y }` and
+  `crop: { top, right, bottom, left }` (0–1, cut from each edge; the crop must leave a visible
+  window). The value's focal wins over the asset's; absent keys fall back to the asset. Draw a
+  value with `imageValueUrl(value, { w, h })` and `imageValueObjectPosition(value)` from
+  `@bettercms-ai/image-url`, never `.url` alone, or the crop is lost. The dashboard's asset Crop
+  rewrites the stored bytes for every usage. Never add focal or crop FIELDS to a model: they
+  belong on the image value.
+- **Image block width.** An image block's `props.width` is pixels, and every lane caps it at
+  the column (`max-width:100%`, height auto). Leave it unset to fill the column.
+- **Rich-text images.** A `builtin:image` block takes `align` (`full` | `center` | `left` |
+  `right`) and `size` (`small` | `medium` | `large` | `full`) in its fields. Both render on every
+  lane, with inline widths, so no site CSS is needed.
+- **Image facts ride on the delivered value.** Delivery adds `width`, `height`, `thumbHash` (a
+  ThumbHash placeholder) and `focalX`/`focalY` to each image value, read at request time and
+  omitted while unknown (object values only: a bare URL string stays a string). Reserve the box from `width`/`height`, decode `thumbHash` for a blur-up,
+  and fall back to a tiny variant (`width(24)`) when it is absent.
+- **Generate or edit an image.** `generate_image` { prompt, width?, height?, altText } adds an AI
+  image to the Media Library; `transform_image` { mediaId, prompt } saves an edited copy as a NEW
+  asset and keeps the original. Each costs 5 AI credits (free with the workspace's own Together
+  key). Always set `altText`, and use them only where the user wants generated imagery: never to
+  stand in for a real product, person or place.
+- **SVG.** Every SVG upload is sanitised on the way in, and SVGs are served as vectors (no
+  raster variants). Keep safe icons as SVG and expose icon choice, size and colour token.
+  Functional icons need an accessible label or adjacent text. Editing SVG paths is not a CMS
+  feature; the text inside an SVG is not a bindable field ([bindings.md](bindings.md) §2).
+- **Video.** Inventory format, host, poster, captions, autoplay/mute/loop and cost. Do not copy
+  every video into the media library by default; keep a streaming provider reference where the
+  site depends on one.
+
+## Where images hide
+
+Setup makes every picture an image field backed by a library asset, in code, with no step for
+you: the release adopts each media file the build ships (alt text from the markup, its size, and
+a default focal point you can move with `update_media`), derives the fields, and links each
+value to its asset. Check it, never redo it: the binding report's `elementCoverage.image` is
+`editable / total`, and `imageGaps` names what is not a field, misses first.
+
+| Code | The picture | What to do |
+|---|---|---|
+| `IMG_DATA_URI`, `IMG_NO_SOURCE` | An `<img>` inlined as `data:`, or filled in by a script | Ship it as a file with a real `src` |
+| `BG_PSEUDO_ELEMENT` | A background on `::before` / `::after` | Move it onto the element, or render an `<img>` |
+| `BG_ON_TEXT` | A background on an element that is itself a text field, or on a section whose copy sits directly in it. A section that keeps its copy in one wrapper is never listed: the picture is the section's field and the copy the wrapper's | Wrap the text, so the box and the words are two elements |
+| `SVG_TOO_LARGE` | An inline `<svg>` past 64 KB | Ship it as an `.svg` file in an `<img>` |
+| `SVG_SPRITE` | A `<use>` naming a symbol the page does not hold, or a sprite FILE the build does not ship (another host's, a relative path) | Inline the symbol in the page, serve the sprite from the site root, or ship the icon as its own `<svg>` |
+| `IMAGE_NOT_ASSET` | A header or footer picture the Media library holds no asset for | Nothing lost: the rest of the region is the Layout's and this picture stays a field of each page. Setup tries it again on the next build |
+| `SVG_NOT_ICON`, `SVG_DECORATIVE` | An `<svg>` holding a script, an HTML island or a remote image; an `aria-hidden` glyph in the nav or footer, or a nameless one on an older import | Decoration: leave it, or give a logo `role="img"` and an `aria-label` |
+| `BG_SPRITE`, `BG_TINY`, `BG_PATTERN`, `BG_DATA_URI`, `BG_STATE` | A sprite, an icon-sized box, a tile, an inlined texture, a hover image | Decoration: leave it |
+
+The first four rows count against the image coverage; the rest do not. A gap you cannot
+close is reported with its code, never described as done.
+
+An icon a sprite file draws (`<use href="/sprite.svg#shield">`, a same-site `.svg` the build
+ships) is an image field like any inline icon. An icon a FONT draws (`<i class="ph ph-tag">`) is
+a text field holding the class, written to the `class` attribute alone: change the class to
+change the glyph.
+
+`elementGaps` is the same record for everything that is not a picture (`rows` carry a `sample`
+where an image row has a `src`). `EMBED_NOT_VIDEO` (an `<iframe>` that is no video provider's),
+`AUDIO_SOURCE` and `ICON_FONT` (a font icon inside a paragraph that is one rich-text value) are
+shown and editable nowhere, and count against coverage. The rest are declined on purpose and
+never count: `SKIP_LINK`, `FRAMEWORK_UI` (a docs framework's pager, table of contents or
+search), `FRAGMENT_LINK` (an in-page `#` destination under those rules), `ORDINAL_MARKER` (a
+step number the template counts out, on a project imported before step numbers were fields),
+`TEMPLATE_TEXT`, `NOSCRIPT_TEXT` and `HEAD_META_UNMAPPED` (a `<meta>` no native SEO field holds,
+by name).
+
+## Media host
+
+Use `mediaBaseUrl` from `get_project`: media is served from the CDN origin or the API origin of
+the backend that owns the asset ids. `set_media_delivery` is the owner's decision, asked every
+time. If a stored URL 404s, find the owning asset and report it; never re-save content to "move"
+assets. How templates and resize URLs use it: [frameworks.md](frameworks.md) Media host.
+
+## Presentation-mode UX
+
+Show only meaningful controls, and state the scope before a change:
+
+```text
+Brand                    [sitewide, reviewed]
+  Logos · Colors · Typography · Spacing / Radius / Motion
+
+Selected hero image      [this instance]
+  Asset · Alt text / Decorative · Caption
+```
+
+Keep provenance and licence status visible to developers, away from everyday editing.
+
+## Acceptance
+
+- Every local asset resolves from the project's media store; external dependencies are listed.
+- Logo roles and fonts carry evidence and licence status.
+- Colour, type and spacing changes go through tokens and keep contrast and responsive layout.
+- Editing a usage's alt text or caption changes the right rendered image.
+- Icons work in every intended theme and state.
+- Baseline and changed screenshots are compared; material differences are explained.