@sleekcms/sync 2.7.2 → 2.9.0

package/README.md

@@ -201,9 +201,11 @@ No manual deploy. No waiting. SleekCMS rebuilds on every sync and the preview re
     │   ├── entries/<key>[].json          # Collection entry content (array)
     │   └── images.json                   # Reusable site-level images (handle → shortcut)
     │
-    └── public/
-        ├── css/<name>.css                # Stylesheets
-        └── js/<name>.js                  # Scripts
+    ├── public/
+    │   ├── css/<name>.css                # Stylesheets
+    │   └── js/<name>.js                  # Scripts
+    │
+    └── setup.json                        # Site setup: default page title, Tailwind on/off, sitemap on/off
 ```
 
 ### File naming
@@ -410,6 +412,20 @@ Any form with `data-sleekcms="<name>"` captures and stores submissions in the CM
 
 Content lives in `src/content/` as plain JSON. Edit any content file and save — it syncs like any other file.
 
+## Site setup (`src/setup.json`)
+
+Site-wide decisions made once — the default page title, whether Tailwind is compiled, and whether a sitemap is published — live in `src/setup.json`, mirrored from **Settings → Website** in the CMS. The file is JSON with a comment above each key explaining it:
+
+```json5
+{
+  title: "Acme Dental",     // default <title> for pages without their own; null = the site name
+  tw_enabled: true,         // compile src/public/css/tailwind.css and inject it into every page
+  sitemap_enabled: false,   // publish sitemap.xml + robots.txt on every build
+}
+```
+
+Edit the values and save — it syncs like any other file. Keys you leave out keep their current value. Which pages are excluded from the sitemap is managed in the CMS UI, not in this file.
+
 ## Images
 
 Images are part of content, not a separate asset pipeline. Drop a shortcut string into any `image` field and the sync engine resolves it to a full `{ url, alt }` object on save:

package/dist/AGENT.md

@@ -9,6 +9,7 @@ SleekCMS is a headless CMS plus static site generator. There are no servers, no
 | **Model** (`.model`) | The shape of the content (field names + types) | `src/models/...` |
 | **Content** (`.json` / `.md`) | The actual values for those fields | `src/content/...` |
 | **View** (`.ejs`) | The HTML template that renders the content | `src/pages/`, `src/entries/`, `src/blocks/`, `src/layouts/` |
+| **Assets** (`.css` / `.js`) | Stylesheets and scripts | `src/css/`, `src/js/` |
 
 A page's HTML = **layout** wrapping ( **page view** rendering **page content** validated by **page model** ).
 
@@ -75,19 +76,39 @@ blocks/<key>.ejs                Block views (required for every block)
 layouts/common.ejs              The single site layout (see §8)
 
 css/<name>.css                  Stylesheets — must be included via link()
-css/tailwind.css                Tailwind (auto-compiled, auto-injected — never link() it)
+css/tailwind.css                Tailwind v4 input CSS (auto-compiled, auto-injected — never link() it; @theme design tokens + the /* DESIGN */ header live here)
 js/<name>.js                    Scripts — must be included via script()
 
 content/pages/<key>.json        Content for a single page (object)
-content/pages/<key>/<slug>.json Content for one record of a collection page (<key> ends with +)
-content/pages/<key>/<slug>.md   Same record as Markdown + frontmatter, when the model qualifies (§7)
+content/pages/<key>+/<slug>.json  Content for ONE record of a collection page — one file per slug
+content/pages/<key>+/<slug>.md    Same record as Markdown + frontmatter, when the model qualifies (§7)
 content/entries/<key>.json      Content for a single entry (object)
-content/entries/<key>.json      Collection entry: <key> ends with +, file holds an array of objects
-
+content/entries/<key>+.json     Collection entry — ONE file holding a JSON array of all items
 content/images.json             Site-level reusable images: handle → shortcut (§7)
-content/videos.json             Site-level videos: handle → embed_url. READ-ONLY (§7)
+content/videos.json             Site-level videos: handle → pexels:/pixabay: ref (user uploads show as embed_url) (§7)
+
+setup.json                      Site setup (JSON, comments allowed): default page title, Tailwind on/off, sitemap on/off — edit values in place, never delete
 ```
 
+**Collection storage differs by kind — do not confuse them:**
+- **Pages collection** (`blog+`) → a *folder* of per-slug files: `content/pages/blog+/post-1.json`, `post-2.json`, … Each item has its own URL.
+- **Entries collection** (`testimonials+`) → a *single file* containing a JSON array: `content/entries/testimonials+.json` holds `[{...}, {...}]`. Items are shared data with no URLs.
+
+**Path spaces** — three different things use `/`-style paths; don't confuse them:
+- **Workspace file path** (what you edit under `src/`): `pages/about.ejs`, `css/styles.css`.
+- **Public URL** (what `link()`/`script()` and HTML `href`/`src` take): `/css/styles.css`, `/js/app.js`.
+- **Page route** (what visitors see): `/about`, `/blog/<slug>`. Computed from the page key.
+
+**Site setup (`setup.json`)** — the set-once site decisions, mirrored from Settings > Website in the CMS. Each key is explained by the comment above it in the file:
+
+| Key | Value | Effect |
+|---|---|---|
+| `title` | string or `null` | Default `<title>` for pages that don't set their own (via `title()` or the SEO block). `null` = the site name. |
+| `tw_enabled` | boolean | `true` compiles `css/tailwind.css` and injects it into every page — required for any site styled with Tailwind utilities. |
+| `sitemap_enabled` | boolean | `true` publishes `sitemap.xml` + `robots.txt` on every build. Turn it on for public sites and SEO work. |
+
+Edit values in place and keep the keys. Keys you omit keep their stored values; unknown keys are ignored. Which pages are excluded from the sitemap is a CMS UI setting, not a key in this file. Never delete the file.
+
 ## 5. Common Tasks
 
 ### Create a single page (e.g. `/about`)
@@ -103,7 +124,7 @@ content/videos.json             Site-level videos: handle → embed_url. READ-ON
 2. `pages/blog+.ejs` — renders **one** post; `item` is that post's content.
 3. One content file per post: `content/pages/blog+/<slug>.json` (or `.md` when the model qualifies, §7).
 4. Optionally create a listing page with key `blog` (single page) that loops with `getPages('/blog', { collection: true })`.
-5. For blogs, also create an RSS feed (§11) and link it for autodiscovery.
+5. For blogs, also create an RSS feed (§12) and link it for autodiscovery.
 
 ### Change what a page says
 
@@ -130,7 +151,7 @@ Like JSON but with **no quotes**; each value is a field type name:
     features: [
         {
             title: text,
-            icon: image
+            icon: icon
         }
     ]
 }
@@ -155,9 +176,10 @@ Like JSON but with **no quotes**; each value is a field type name:
 | `date` | `"YYYY-MM-DD"` string |
 | `datetime` | ISO 8601 string |
 | `time` | `"HH:mm"` string |
-| `image` | Shortcut string (preferred when writing) or resolved `{ "url", "alt" }` object — see §7. Use `image` for **anything visual, including icons** (`"iconify:..."`). Shortcuts only resolve in `image` fields — in a `text` field the string stays literal text |
-| `video` | Object. **Never write or invent this value** — uploads are user-driven in the CMS UI. Render with `embed()` only |
-| `file` | Object `{ name, url, size, type, ext }`. **Never write or invent this value** — uploads are user-driven. Render a link with `item.x.url` / `item.x.name` |
+| `image` | Shortcut string (preferred when writing) or resolved `{ "url", "alt" }` object — see §7. Shortcuts only resolve in `image`/`icon` fields — in a `text` field the string stays literal text |
+| `icon` | Svg icon. Use for icons the user is expected to edit/swap in the CMS (e.g. features/services). Fill with placeholder `"iconify:<prefix:name or search>"` (or `"cms:<handle>"` pointing at an svg); render with `svg(item.icon)`. Fixed UI icons don't need fields — call `svg('iconify:...')` directly in templates |
+| `video` | Ref string (preferred when writing) or the resolved object you read back. Write `"cms:<handle>"` to reuse a video from `content/videos.json` (or a user upload by its handle), or `"pexels:<search>\|<title>"` / `"pixabay:<search>\|<title>"` for a one-off — resolved server-side (see §7). **Never invent** `video_id`/`embed_url` objects; render with `embed()` only |
+| `file` | Write a plain file name, e.g. `"brochure.pdf"` (pdf, docx, xlsx, pptx, csv, tsv, txt, md — no path, no URL, never an object). On save the CMS attaches the site file with that name, or creates a small placeholder file the user replaces in the CMS UI; reads back as the file name. Render a link with `item.x.url` / `item.x.name` |
 | `json` | Any JSON |
 | `sheet` | Array of arrays |
 | `location` | `{ "markers": [{ "lat", "lng" }], "img": "<google static map url>" }` — `img` supports Google Static Maps params; markers are already part of the URL |
@@ -168,6 +190,8 @@ Like JSON but with **no quotes**; each value is a field type name:
 | Group `{ ... }` | Nested object |
 | Collection `[{ ... }]` | Array of nested objects |
 
+> **Images need an `image` field and icons an `icon` field — never `text`.** A shortcut string (`unsplash:`/`pexels:`/`pixabay:`/`iconify:`/`url:`/`cms:`) resolves to a real image **only** when its model field is typed `image` or `icon`, or inside a `markdown` body via `![alt](…)`. In any other field — `text`, `paragraph`, `richtext`, `code`, `link` — the shortcut is stored and rendered **verbatim**. Symptom: a raw `iconify:…`/`pexels:…` string showing up on the page means the field was mis-typed — change it to `image`/`icon` in the `.model` and the existing value resolves on the next save.
+
 ### Entry references in content
 
 The value is the **0-based index** of the target record in `content/entries/<key>+.json`, written as a string:
@@ -225,7 +249,7 @@ Content files hold the values for model fields. Keys must match the model. Savin
 
 ### Images — shortcut strings
 
-When writing an `image` value, prefer the shortcut form `"<source>:<search>"`. Sources: `unsplash`, `pexels`, `pixabay`, `iconify`, `url` (direct URL), `cms` (reusable handle, below).
+When writing an `image` value, prefer the shortcut form `"<source>:<search>"`. Sources — this is the complete set: `unsplash`, `pexels`, `pixabay`, `iconify`, `url` (direct URL), `cms` (reusable handle, below).
 
 - `"pexels:doctor"` — stock search
 - `"url:https://example.com/photo.jpg"` — specific asset
@@ -234,21 +258,33 @@ When writing an `image` value, prefer the shortcut form `"<source>:<search>"`. S
 
 On save, the sync engine resolves each shortcut to a real `{ "url", "alt" }` object.
 
-**Shortcuts only work in `image` fields.** A common mistake: declaring a visual field as `text` (e.g. `icon: text`) and then writing `"iconify:lucide:clock"` as its value. Nothing errors — the string simply stays literal text and never resolves to an image. Any field that will hold an icon, logo, photo, or illustration must be declared `icon: image` in the model. If a shortcut isn't resolving, check the field's type in the `.model` first.
+Give **every** image field a resolvable shortcut from the sources above — including slots the user will eventually fill with their own photos (personal galleries, headshots, family pages, "I'll add my pictures later"): write a stock search whose subject and alt describe the photo that belongs there, e.g. `"pexels:friends laughing golden hour|Ghazia with her girlies"`. The site ships with a real photo in every slot, and the user swaps any image for their own in the CMS UI whenever they're ready.
 
-**Reusable images:** for images used in multiple places (logo, recurring icons), declare them once in `content/images.json` as `handle → shortcut`:
+**Shortcuts only resolve in `image` and `icon` fields.** A common mistake: declaring a visual field as `text` (e.g. `icon: text`) and then writing `"iconify:lucide:clock"` as its value. Nothing errors — the string simply stays literal text and never resolves. Any field that will hold a photo or illustration must be typed `image`, and any CMS-editable icon must be typed `icon`. If a shortcut isn't resolving, check the field's type in the `.model` first.
+
+**Reusable images and customizable site icons:** for site-wide images or icons the user is expected to change in the CMS (e.g. site logo), declare them once in `content/images.json` as `handle → shortcut` with a placeholder shortcut:
 
 ```json
-{ "logo": "url:https://cdn.example.com/logo.svg", "hero": "pexels:mountain sunrise" }
+{ "logo": "iconify:lucide:sparkles", "hero": "pexels:mountain sunrise" }
 ```
 
-then reference with `"cms:logo"` in any image field, or fetch in templates via `getImage('logo')`.
+then reference with `"cms:logo"` in any `image`/`icon` field, or render directly in templates — `svg('cms:logo', { class: 'h-8 w-auto' })` for SVGs/icons, `img('cms:hero', '1920x600')` for photos. (`getImage('logo')` returns the resolved image object for a bare handle — rarely needed; the helpers take the value or `cms:` ref directly.)
 
 **Images inside markdown:** use the same shortcuts in standard syntax: `![alt](pexels:doctor)`. Append `|<alt>` for alt text and an optional `<W>x<H>` token to set rendered size (default `600x400`): `![doctor](pexels:doctor|Friendly doctor 800x600)`. Refs are rewritten to CDN URLs on save.
 
-### Videos — read-only
+### Videos
+
+`content/videos.json` maps `handle → ref` for site-level videos. To add a stock video, declare a handle with a `pexels:<search>` or `pixabay:<search>` ref (their free stock **video** catalogs) — optional `_` (landscape) / `/` (portrait) marker, optional `|<title>`:
+
+```json
+{ "hero-loop": "pexels:_ocean waves|Hero background loop" }
+```
 
-`content/videos.json` maps `handle → embed_url` for every video the user uploaded via the CMS UI. **Never edit this file** — it is regenerated and local edits are overwritten. Use it only to discover handles, then in templates: `<%- embed(getVideo('intro'), { size: '1280x720' }) %>`. Never write `video` field values or hand-roll an `<iframe>`.
+On save the platform searches the provider, picks a clip, and ingests it into the site's video library; processing is asynchronous (the embed shows a processing screen until transcoding finishes — no action needed). Writes MERGE by handle: handles you omit are preserved. Re-saving the same ref is a no-op; changing a ref replaces the video. Entries whose value is an **embed URL** are videos the user uploaded in the CMS UI — echo or omit them, never modify or re-point them; deletion is CMS-UI-only.
+
+Render in templates: `<%- embed(getVideo('hero-loop'), { size: '1280x720' }) %>`. Never hand-roll an `<iframe>`.
+
+Content `video` fields accept the same refs: `"cms:<handle>"` reuses a declared (or user-uploaded) video by handle — preferred when the same video appears in more than one place — while a direct `"pexels:<search>|<title>"` / `"pixabay:<search>|<title>"` creates a record-local video. Stock videos read back as refs; user-uploaded videos read back as objects — echo those untouched.
 
 ### Markdown content files (`.md`)
 
@@ -304,6 +340,7 @@ There is exactly **one** layout: `layouts/common.ejs`. It wraps every page autom
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <% if (item.seo) { %><%- render(item.seo) %><% } %>
 </head>
 <body>
   <header><%- render(getEntry('header')) %></header>
@@ -321,7 +358,7 @@ There is exactly **one** layout: `layouts/common.ejs`. It wraps every page autom
 | `getPages(path, opts?)` | Array | Pages whose path starts with the prefix. **Always a URL path, never a key.** `{ collection: true }` → collection pages only |
 | `getEntry(handle)` | Object \| Array | Entry by key. The `+` is optional — `getEntry('authors')` and `getEntry('authors+')` are equivalent. Single → object, collection → array |
 | `getSlugs(path)` | string[] | Slugs under a collection path |
-| `getImage(handle)` | Object \| undefined | Resolved image from `images.json` |
+| `getImage(handle)` | Object \| undefined | Resolved image from `images.json` (bare handle, no `cms:` prefix) |
 | `getVideo(handle)` | Object \| undefined | Video from `videos.json` |
 | `getContent(query?)` | Any | Full content payload, optionally filtered with JMESPath |
 | `path(page)` | String | URL path of a page object |
@@ -345,6 +382,12 @@ There is exactly **one** layout: `layouts/common.ejs`. It wraps every page autom
 
 `attr` is `"WxH"` or `{ w, h, size, fit, type, class, style }`. `location` values can be passed to `src()`/`img()` for static maps, to `embed(loc, attr?)` for a Google Maps iframe, or to `markers(loc)` for raw coordinates (`attr` adds `zoom`, `maptype`, `scale`).
 
+Render `icon` fields or direct icon shortcuts with `svg()` — it inlines the svg markup at build time, so the icon scales cleanly and can be styled with CSS (e.g. `svg(item.icon, { class: 'w-6 h-6' })` or directly `svg('iconify:lucide:arrow-right', { class: 'w-4 h-4' })`).
+
+> **Direct UI Icons vs. CMS-Editable Icons:**
+> - **Static UI icons** (chevrons, arrows, badges, buttons, decorative bullet checks): render directly in `.ejs` with `svg('iconify:<family>:<name>', { class: '...' })` — no model field or `images.json` entry required.
+> - **User-editable icons** (site logo, service/feature icons): when the user is expected to customize/swap the icon in the CMS, expose it via `content/images.json` (for site handles like `"logo"`) or an `icon: icon` model field, providing a placeholder `"iconify:..."` in content so the site ships visually complete. Render with `svg('cms:logo')` or `svg(item.icon)`.
+
 ### Helpers — video
 
 `embed(video, attr?)` returns a provider-aware `<iframe>`. `attr` is `"WxH"` or `{ w, h, size, autoplay, muted, loop, preload, t, class, style }`. Browsers block autoplay unless `muted: true` is also set.
@@ -371,7 +414,7 @@ Callable from **any** view (page, block, entry, layout); duplicates are removed
 <section data-aos="fade-up" data-aos-delay="150">...</section>
 ```
 
-**CSS/JS rules:** include assets only via `link()` / `script()` — never raw `<link>`/`<script>` tags in views. Exception: creating `css/tailwind.css` enables Tailwind, which is compiled and injected automatically — never `link()` it. Default to a modern Tailwind design unless the user specifies otherwise.
+**CSS/JS rules:** include assets only via `link()` / `script()` — never raw `<link>`/`<script>` tags in views. Exception: creating `css/tailwind.css` enables Tailwind v4 — the file is the Tailwind *input CSS*, compiled against the rendered HTML and injected automatically; never `link()` it. Whenever you write it, keep `@import "tailwindcss";` as its first statement (plus the two `@plugin` lines: `@plugin "@tailwindcss/typography";` and `@plugin "@tailwindcss/forms";`) — dropping the import silently removes all Tailwind styling. Define the site's fonts/colors/radii as `@theme` tokens there (giving utilities like `font-display` / `bg-brand-600`) with a `/* DESIGN */` header comment recording the design direction. v4, not v3: custom utilities go in `@utility name { … }`, never `@layer utilities { .name { … } }` (a v3 pattern that yields "Cannot apply unknown utility class"); config is CSS-first — there is no `tailwind.config.js`. Default to a polished Tailwind design with a deliberate design direction.
 
 ## 9. SEO
 
@@ -393,11 +436,13 @@ Make every site strongly SEO- and sharing-friendly. The standard pattern is a re
 <% if (item.image) meta({ property: 'og:image', content: src(item.image, '1200x630') }) %>
 ```
 
-Add `seo: block(seo)` to page models and `<%- render(item.seo) %>` in page views.
+Add `seo: block(seo)` to page models and render it **once from the layout head**: `<% if (item.seo) { %><%- render(item.seo) %><% } %>` in `layouts/common.ejs` (as in the layout example above) — not per page view.
+
+Two site-level SEO switches live in `setup.json` (§4), not in views: `sitemap_enabled: true` publishes `sitemap.xml` + `robots.txt` on every build, and `title` is the site's default `<title>` for pages whose SEO block leaves the title empty (`null` = the site name). Sitemap page exclusions are chosen in the CMS UI — there is no file setting for them.
 
 ## 10. Forms
 
-Any `<form>` with `data-sleekcms="<name>"` works automatically — submissions are captured and shown in the CMS dashboard. No backend, no action URL, no JS.
+Any `<form>` with `data-sleekcms="<hardcoded name>"` works automatically — submissions are captured and shown in the CMS dashboard. No backend, no action URL, no JS.
 
 ```html
 <form data-sleekcms="contact">
@@ -470,16 +515,48 @@ Always create an RSS feed for blogs. Use the page key `rss.xml` — because the
 
 Make it discoverable from the layout: `<% link({ rel: 'alternate', type: 'application/rss+xml', title: 'RSS', href: '/rss.xml' }) %>`
 
-## 13. Critical Rules Checklist
+## 13. Ecommerce (Snipcart)
+
+Snipcart powers stores. Use it when the business **sells products** and the user asks for a store, cart, or buy buttons — or when selling is clearly core to the business. **Never add a store speculatively.** Use Snipcart's default UI (side-modal cart, checkout, customer accounts) as-is; style only the site's own markup (buy buttons, product cards, header controls) with Tailwind.
+
+1. **Settings entry with the API key.** `models/entries/settings.model` → `{ snipcart_key: text }`, value in `content/entries/settings.json`. If the site already has a settings-style entry, add the field there instead of creating a second one. An empty value falls back to a shared test-mode key, so checkout works immediately as a test store.
+2. **One line in the layout.** At the end of `<body>` in `layouts/common.ejs`:
+
+   ```ejs
+   <%- snipcart(getEntry('settings')?.snipcart_key) %>
+   ```
+
+   This is the complete install — the helper loads all of Snipcart's CDN CSS/JS itself and returns the hidden `#snipcart` mount div. Call it exactly once, from the layout body only; everything after this line is pure markup. Optional second argument: `{ currency: 'eur' }`.
+3. **Products collection.** `models/pages/products+.model` with `{ title: text, price: number, image: image, description: paragraph }`, one content file per product, a `/products` listing page, and standard `snipcart-add-item` buy buttons wired to SleekCMS values:
+
+   ```ejs
+   <button class="snipcart-add-item"
+     data-item-id="<%= item._slug %>"
+     data-item-name="<%= item.title %>"
+     data-item-price="<%= Number(item.price).toFixed(2) %>"
+     data-item-url="<%= path(item) %>"
+     data-item-image="<%- src(item.image, '600x600') %>">
+     Add to cart
+   </button>
+   ```
+
+   `data-item-url` is the product's own page path (`path(item)`), and that page must contain the same buy button — Snipcart re-crawls it to validate orders. Repeat the full `data-item-*` set everywhere the product can be added (listing cards too).
+4. **Header controls.** Add both the cart button (`class="snipcart-checkout"` with `snipcart-items-count`) and the customer sign-in link (`class="snipcart-customer-signin"`) to the site header.
+
+## 14. Critical Rules Checklist
 
 1. **`+` is part of the key.** A collection's `+` appears on the model, the view, and the content file/folder: `models/pages/blog+.model`, `pages/blog+.ejs`, `content/pages/blog+/<slug>.json`. A file without the `+` is a *different*, single-type key.
 2. Models first: a content field that isn't in the `.model` won't sync. Update the model, then the content.
 3. Blocks never have content files. Block values live inline in the page/entry JSON that declares them.
-4. Never write `video` or `file` values, and never edit `content/videos.json` — these are user-driven uploads.
-5. `richtext` → `<%- item.x %>`. `markdown` → `<%- marked(item.x) %>`.
-6. CSS/JS via `link()`/`script()` only; `css/tailwind.css` is auto-injected — never `link()` it.
-7. Editable copy belongs in `content/`, not hard-coded in `.ejs`. Fixed micro-labels may stay in views.
-8. In page keys, `-` separates words and `_` means `/`. `_index` is the home page only.
-9. After edits, check `sync-errors.log` in the workspace root. New line = failure for that file; line removed = fixed.
-10. Image values: prefer shortcuts (`"pexels:doctor|alt text"`); use `"cms:<handle>"` + `images.json` for images reused across pages.
-11. Image shortcuts (`"iconify:..."`, `"pexels:..."`, etc.) resolve **only** in `image`-typed fields. Icons are images: declare `icon: image`, never `icon: text`.
+4. `file` field values are plain file names ending in a supported extension (`"brochure.pdf"`) — the CMS attaches or placeholder-creates the file server-side; never write objects or URLs.
+5. Never invent `video_id`/`embed_url` objects — render videos with `embed()` only. Videos are set via refs: `content/videos.json` handles for shared videos, and `cms:<handle>` / provider refs in `video` fields (§7); values that read back as embed URLs or objects are user uploads — leave them untouched.
+6. `richtext` → `<%- item.x %>`. `markdown` → `<%- marked(item.x) %>`.
+7. CSS/JS via `link()`/`script()` only; `css/tailwind.css` is auto-injected — never `link()` it. When writing tailwind.css, `@import "tailwindcss";` must stay as its first statement — dropping it silently removes all Tailwind styling.
+8. Editable copy belongs in `content/`, not hard-coded in `.ejs`. Fixed micro-labels may stay in views.
+9. In page keys, `-` separates words and `_` means `/`. `_index` is the home page only; a section index page uses the plain section key.
+10. After edits, check `sync-errors.log` in the workspace root. New line = failure for that file; line removed = fixed.
+11. Images are content-first: author each image as an `image`-field value (`"pexels:doctor|alt text"` — resolves on save) or as a `content/images.json` handle for images reused across pages; templates pass the value straight to the helper (`img(item.field)`, `img('cms:handle')`).
+12. Image shortcuts (`"iconify:..."`, `"pexels:..."`, etc.) resolve **only** in `image`/`icon`-typed fields. CMS-editable icons are declared `icon: icon`, never `icon: text` — render with `svg(item.icon)`; fixed UI icons need no field: `svg('iconify:...')` directly in the view.
+13. Use entries (`entry(key+)`) for shared content (authors, testimonials, nav, footer) — not blocks. Block models cannot contain `block(...)` or `stack` fields; use blocks only when a group of fields also benefits from a reusable view.
+14. Always create an RSS feed for blogs (`rss.xml` key) and make every site strongly SEO- and sharing-friendly (reusable `seo` block rendered once from the layout head).
+15. Site-wide setup — default page title, Tailwind on/off, sitemap on/off — lives in `setup.json` (§4). Change values there rather than hard-coding a site title into the layout, and never delete the file. Sitemap page exclusions are UI-only.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sleekcms/sync",
-    "version": "2.7.2",
+    "version": "2.9.0",
     "description": "Edit SleekCMS sites locally — models, content, templates, images — with live two-way sync and AI agent support.",
     "keywords": [
         "sleekcms",