@sleekcms/sync 1.7.0 → 2.1.0

package/dist/AGENT.md

@@ -1,107 +1,123 @@
-# SleekCMS — Site Builder Reference
+# SleekCMS Site Builder — Agent Guide
 
-Cloud-based headless CMS with an integrated static site builder. Files sync automatically — every save triggers a rebuild and deploy. No Git, no servers, no manual builds.
+## 1. Mental Model
 
----
+SleekCMS is a headless CMS plus static site generator. There are no servers, no git repos, nothing to compile locally. You build a site by editing three kinds of files, which sync automatically to the platform:
+
+| You edit | What it is | Where |
+|---|---|---|
+| **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/` |
 
-## How It Works
+A page's HTML = **layout** wrapping ( **page view** rendering **page content** validated by **page model** ).
 
-Each page = **model** (schema) + **template** (EJS) + optional **layout** (EJS wrapper).
+Three model kinds:
 
-The **file name** (key) links a model to its template and determines the URL path.
+- **Page** — routable; has a URL. Lives in `models/pages/`.
+- **Entry** — shared data with no URL (nav, footer, authors, testimonials). Lives in `models/entries/`.
+- **Block** — a reusable field *schema + view*, embedded inside pages/entries. Lives in `models/blocks/`. Blocks never have their own content files.
 
-Sync/build errors are written to `sync-errors.log` in the workspace root. If a save does not render or deploy as expected, check that file first.
+Pages and entries are either **single** (one record) or a **collection** (many records). A collection is marked by a `+` suffix on the key, e.g. `blog+`.
 
----
+## 2. The Edit → Sync → Verify Loop
 
-## File Naming Convention
+1. **Edit/create files** in the workspace under `src/`.
+2. The `@sleekcms/sync` utility runs in the background and pushes every save automatically. There is no build or deploy command to run.
+3. **Verify by reading `sync-errors.log`** in the workspace root after a batch of edits:
+   - A failed sync **adds a line** describing the error for that file.
+   - When the file is fixed and re-synced, **its line is removed**.
+   - Empty file (or no new lines) = everything synced successfully.
+4. Previews are online only; the user views the result in the SleekCMS preview, not locally.
 
-Keys are lowercase, dash-separated. For pages, `_` in the key maps to `/` in the URL. A `+` suffix marks a collection.
+Never guess at why something isn't rendering — read `sync-errors.log` first.
 
-| File key | URL |
+## 3. File Naming Rules (applies to models, views, and content)
+
+1. Keys are **lowercase**, words separated by `-` (dash). Example: `getting-started`.
+2. In **page** keys, `_` (underscore) maps to `/` in the URL. Example: key `docs_getting-started` → URL `/docs/getting-started`. Underscore is **only** for path nesting — never use it as a word separator.
+3. `_index` is the key for the **home page (`/`) only**. An index page for a section uses the plain section key: the page at `/docs` has key `docs`.
+4. A `+` suffix marks a **collection**. The `+` is part of the key and appears on the model, the view, and the content file/folder names. Example: `blog+`.
+5. A key may contain a file extension, e.g. `rss.xml` → URL `/rss.xml`. The dot is kept as-is, the file is served with the matching content type, and **the layout is skipped automatically** for such pages.
+6. `blog` and `blog+` are two different keys and may coexist: `blog` is a single page at `/blog` (e.g. the post listing), while `blog+` is the collection that generates `/blog/<slug>` (one page per post).
+
+| Page key | URL |
 |---|---|
-| `_index` | `/` (home) |
+| `_index` | `/` |
 | `about` | `/about` |
-| `blog+` | `/blog/<slug>` (one page per entry) |
+| `blog` | `/blog` (single page) |
+| `blog+` | `/blog/<slug>` (one page per content file) |
 | `docs_getting-started` | `/docs/getting-started` |
+| `docs_guides+` | `/docs/guides/<slug>` |
+| `rss.xml` | `/rss.xml` (no layout) |
 
-The keys for model, template, and content file are the same — if the model is a **collection**, the `+` suffix is part of the key and must appear on **every** related file.
+For collection pages, the `<slug>` is the content file's name: `content/pages/blog+/my-post.json` → `/blog/my-post`. Renaming the file renames the URL.
 
-Examples:
-- Collection page `blog`: `models/pages/blog+.model`, `pages/blog+.ejs`, `content/pages/blog+/<slug>.json`
-- Collection entry `testimonials`: `models/entries/testimonials+.model`, `entries/testimonials+.ejs`, `content/entries/testimonials+.json`
-- Single page `about`: `models/pages/about.model`, `pages/about.ejs`, `content/pages/about.json` (no `+`)
+## 4. Folder Structure (under `src/`)
 
----
+```
+models/pages/<key>.model        Page models
+models/entries/<key>.model      Entry models
+models/blocks/<key>.model       Block models
 
-## Folder Structure within src/
+pages/<key>.ejs                 Page views
+entries/<key>.ejs               Entry views (only needed if you render() the entry)
+blocks/<key>.ejs                Block views (required for every block)
+layouts/common.ejs              The single site layout (see §8)
 
-```
-/models/pages/<key>.model      Page content models
-/models/entries/<key>.model    Entry content models
-/models/blocks/<key>.model     Block component models
-
-/pages/<key>.ejs               Page templates
-/entries/<key>.ejs             Entry templates
-/blocks/<key>.ejs              Block templates
-/layouts/<name>.ejs            Layout wrappers (default is common.ejs)
-
-/css/<name>.css                Stylesheets (require head injection)
-/css/tailwind.css              Tailwind CSS (auto-compiled, auto-injected)
-/js/<name>.js                  Scripts (require head injection)
-
-/content/pages/<key>.json          Content for a single (non-list) page
-/content/pages/<key>/<slug>.json   Content for one item of a collection page (<key> ends with +)
-/content/pages/<key>/<slug>.md     Same as above, but as Markdown with YAML frontmatter — used when the model qualifies (see "Markdown content files" below)
-/content/entries/<key>.json        Content for a single entry (object)
-/content/entries/<key+>.json       Content for a collection entry (array of objects; <key>+ matches the model filename)
-
-/content/images.json                       Site-level reusable images (handle → shortcut)
-/content/videos.json                       Site-level videos (handle → embed_url) — READ-ONLY, populated by UI uploads
+css/<name>.css                  Stylesheets — must be included via link()
+css/tailwind.css                Tailwind (auto-compiled, auto-injected — never link() it)
+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/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/images.json             Site-level reusable images: handle → shortcut (§7)
+content/videos.json             Site-level videos: handle → embed_url. READ-ONLY (§7)
 ```
 
-> **Tailwind**: Creating `/css/tailwind.css` enables Tailwind. It is compiled and injected automatically — do NOT add it via `link()`.
-> All other CSS/JS files must be included via `link()` or `script()`.
+## 5. Common Tasks
 
----
+### Create a single page (e.g. `/about`)
 
-## Content Models
+1. `models/pages/about.model` — define the fields.
+2. `content/pages/about.json` — fill in values (keys must match the model).
+3. `pages/about.ejs` — render `item.<field>`.
+4. Check `sync-errors.log`.
 
-### Model Types
+### Create a collection (e.g. a blog at `/blog/<slug>`)
 
-| Type | Purpose | Has URL | File path |
-|---|---|---|---|
-| **Page** | Routable content | Yes | `models/pages/<key>.model` |
-| **Entry** | Shared/reusable data (nav, footer, authors) | No | `models/entries/<key>.model` |
-| **Block** | Reusable component schema embedded in pages/entries | No | `models/blocks/<key>.model` |
+1. `models/pages/blog+.model`
+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.
 
-Pages and entries can be **single** (one record) or **collection** (many records, key ends with `+`). Blocks are embedded component definitions; they do not have their own top-level content records.
+### Change what a page says
 
-### .model File Format
+Edit the matching file under `content/` — **do not** hard-code editable copy into `.ejs` views. Views define structure; content files hold values. Exception: trivial fixed strings the user will never edit (e.g. a "Read more" label) may live in the view. Decide what is genuinely content.
 
-JSON structure without quotes on keys or string values. Scalar values are the field type name.
+### Add a field to a page
 
-```
-{
-    title: text,
-    image: image,
-    content: markdown
-}
-```
+1. Add the field to the `.model` **first**.
+2. Then add the value to the content JSON. Content keys that don't exist in the model will not sync.
+3. Then use it in the view.
 
-**Groups** — Nest fields in an object:
-```
-{
-    hero: {
-        heading: text,
-        background: image
-    }
-}
-```
+All fields are optional — a missing value simply renders as `undefined`, so guard with `<% if (item.field) { %>` where it matters.
+
+## 6. Models
+
+### `.model` file format
+
+Like JSON but with **no quotes**; each value is a field type name:
 
-**Collections** (repeatable lists) — Wrap a group in `[]`:
 ```
 {
+    title: text,
+    hero: block(hero),
     features: [
         {
             title: text,
@@ -111,250 +127,127 @@ JSON structure without quotes on keys or string values. Scalar values are the fi
 }
 ```
 
-**Block field** — Use `block(key)` to embed one reusable block schema, or `[block(key)]` for a repeatable list of the same block:
-```
-{
-    cta: block(cta),
-    ctas: [block(cta)]
-}
-```
-
-### Blocks
-
-Blocks are reusable components made from two files:
-
-- `models/blocks/<key>.model` defines the fields editors can fill in.
-- `blocks/<key>.ejs` defines how that block renders.
-
-A block does **not** own content. There is never a `content/blocks/...` file. Instead, each page or entry that declares `block(key)` or `[block(key)]` stores its own copy of that block's field values inside its own content JSON. The reusable part is the schema and template; the content is local to the page or entry using it.
-
-Use blocks when a group of fields also needs a reusable view, such as SEO metadata, cards, or calls to action that should render the same way across multiple pages. If the structure is only used on one page, a group (`{ ... }`) or repeating group (`[{ ... }]`) is usually simpler. Shared content like testimonials, authors, team members, categories, or reusable navigation data should generally be entries referenced with `entry(key)` or `[entry(key)]`, not blocks.
-
-Example block model:
+- **Group** — nest an object `{ ... }` for one-off structure.
+- **Collection** — wrap a group in `[ ... ]` for a repeatable list.
+- **Block field** — `block(key)` for one block, `[block(key)]` for a repeatable list of the same block.
+- **Stack** — bare `stack` (no parentheses, no `[]`) for a list where each item can be a *different* block.
+- **Entry reference** — `entry(key+)` for one, `[entry(key+)]` for many. The referenced entry must be a collection, so the key inside the parentheses **always includes the `+`**: `entry(authors+)`.
 
-**`models/blocks/hero.model`**
-```
-{
-    heading: text,
-    subheading: paragraph,
-    background: image,
-    cta_label: text,
-    cta_link: link
-}
-```
+### Field types
 
-Use that block in a page model:
+| Model type | Content JSON value (what templates receive) |
+|---|---|
+| `text`, `paragraph`, `code`, `color`, `link` | String |
+| `richtext` | String of **HTML** — output with `<%- %>` |
+| `markdown` | String of **raw markdown** — convert with `<%- marked(item.x) %>` |
+| `number` | Number |
+| `boolean` | `true` / `false` |
+| `emoji` | One emoji character string, e.g. `"😀"` (not free text) |
+| `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` |
+| `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 |
+| `block(key)` | Object matching that block's model, stored inline in the parent's content |
+| `[block(key)]` | Array of such objects |
+| `stack` | Array of mixed block objects, each `{ "_block": "<block_key>", ...fields }` — see below |
+| `entry(key+)` / `[entry(key+)]` | Reference string (or array of them) — see below |
+| Group `{ ... }` | Nested object |
+| Collection `[{ ... }]` | Array of nested objects |
 
-**`models/pages/about.model`**
-```
-{
-    title: text,
-    hero: block(hero)
-}
-```
+### Entry references in content
 
-Store that page's block data inline:
+The value is the **0-based index** of the target record in `content/entries/<key>+.json`, written as a string:
 
-**`content/pages/about.json`**
 ```json
-{
-    "title": "About us",
-    "hero": {
-        "heading": "Care that feels personal",
-        "subheading": "A small team focused on long-term relationships.",
-        "background": "pexels:doctor",
-        "cta_label": "Book a visit",
-        "cta_link": "/contact"
-    }
-}
-```
-
-Render it from the page template with `render()`. The `block(hero)` declaration tells the renderer to use `blocks/hero.ejs`:
-
-**`pages/about.ejs`**
-```ejs
-<h1><%= item.title %></h1>
-<%- render(item.hero) %>
+{ "author": "0", "tags": ["0", "2"] }
 ```
 
-**`blocks/hero.ejs`**
-```ejs
-<section class="hero" style="background-image: url('<%- src(item.background, '1600x700') %>')">
-  <h2><%= item.heading %></h2>
-  <p><%= item.subheading %></p>
-  <a href="<%= item.cta_link %>"><%= item.cta_label %></a>
-</section>
-```
+You may optionally append `|` plus the verbatim opening characters of that entry's content as a human-readable hint: `"0|Engineering"`. The index is what binds; an exact index is not critical for building — the user can re-point references in the CMS UI. Just make sure the field exists.
 
-Block models cannot contain other blocks. Use groups (`{ ... }`) or collections (`[{ ... }]`) inside a block when you need nested structure, and use `entry(key)` when a block needs shared reusable data.
+### Choosing the right structure
 
-Repeatable blocks use the same collection syntax as groups and entries: `[block(cta)]`. Use this sparingly, only when each repeated item should use the same reusable block template. For simple one-page repeated content, prefer a repeating group (`[{ ... }]`). For reusable content selected across pages, prefer a collection entry plus `[entry(key)]`.
+- One-off shape used on a single page → **group** `{ ... }` or repeating group `[{ ... }]`.
+- Reusable shape **and** reusable view (SEO, cards, CTAs rendered identically on many pages) → **block**.
+- A section where the editor mixes different blocks in any order → **stack** (any block in the library may appear; there is no per-field allow-list).
+- Shared *content* referenced from many pages (testimonials, authors, people, tags, nav, footer) → **entry**, referenced with `entry(key+)` / `[entry(key+)]`. Use entries, not blocks, for this.
 
-### Stacks
+Nesting limits: block models cannot contain `block(...)` or `stack` fields. Stack items may contain groups, collections, and entry references — but not other stacks or blocks. Inside a block, use groups/collections for structure and `entry(key+)` for shared data.
 
-A **stack** is a heterogeneous list of blocks: each item picks its own block schema. Use a stack when a page section can contain a mix of different reusable components in an editor-chosen order. If every item would use the same block, prefer `[block(key)]` instead — stacks are for "section A could be a hero, a CTA, a quote, or a gallery."
+### Blocks in detail
 
-**Model syntax** — bare `stack`, no parentheses and no `[]`. Stacks are always multiple by definition:
+A block = two files: `models/blocks/<key>.model` (fields) + `blocks/<key>.ejs` (view). A block **never** owns content — there is no `content/blocks/...`. Each page/entry that declares `block(key)` stores its own copy of the block's values inline in its own content file.
 
 ```
-{
-    title: text,
-    sections: stack
-}
+models/blocks/hero.model         pages model: { ..., hero: block(hero) }
+blocks/hero.ejs                  page view:   <%- render(item.hero) %>
 ```
 
-Any block defined in `models/blocks/` may appear in any stack — the allowed set is the full block library, not a per-field allow-list.
+### Stacks in detail
 
-**Content shape** — an array of objects. Each item is shaped like the block model it uses, plus a `_block` marker naming that block by key (as a plain string):
+Model: `sections: stack`. Content is an array where each item names its block via `_block` (the block **key** as a plain string — never a numeric id; the CMS resolves keys server-side):
 
-**`content/pages/about.json`**
 ```json
 {
-    "title": "About us",
     "sections": [
-        {
-            "_block": "hero",
-            "heading": "Care that feels personal",
-            "subheading": "A small team focused on long-term relationships.",
-            "background": "pexels:doctor"
-        },
-        {
-            "_block": "cta",
-            "label": "Book a visit",
-            "link": "/contact"
-        }
+        { "_block": "hero", "heading": "Care that feels personal", "background": "pexels:doctor" },
+        { "_block": "cta", "label": "Book a visit", "link": "/contact" }
     ]
 }
 ```
 
-The `_block` value is the block's key (e.g., `"hero"`, `"cta"`) — never a numeric id. The CMS resolves it server-side on save.
-
-**Rendering** — each item flows through its own `blocks/<key>.ejs` template. Pass the whole array to `render()` and it dispatches per `_block`:
-
-**`pages/about.ejs`**
-```ejs
-<h1><%= item.title %></h1>
-<%- render(item.sections) %>
-```
+Render the whole array: `<%- render(item.sections) %>` — each item dispatches to its own `blocks/<key>.ejs`.
 
-**Stack vs block vs collection** — same decision tree as blocks, with one extra rung:
+## 7. Content Files
 
-- One-off shape used on one page → group `{ ... }` or `[{ ... }]`.
-- Reusable shape, always the same per item → `block(key)` or `[block(key)]`.
-- Reusable shape, but items can be different blocks chosen by the editor → `stack`.
-- Shared content referenced from many pages → `entry(key)` / `[entry(key)]`.
+Content files hold the values for model fields. Keys must match the model. Saving a content file triggers the same sync loop as any other file.
 
-Like blocks, stacks cannot be nested inside block models. Stack items themselves may contain groups, collections, and entry references, but not other stacks or blocks.
-
-If the Blocks are only used in one page, simply structure the model as nested fields. Do not use Block or Stack fields in those cases.
-
-**Entry reference** — Use `entry(key)` for one, `[entry(key)]` for many:
-```
-{
-    author: entry(authors+),
-    testimonials: [entry(testimonials+)],
-    tags: [entry(tags+)]
-}
-```
-
-### Field Types and Serialization
-
-Model fields declare both the editor type and the shape expected in content JSON. Templates receive those same values, except image shortcuts are resolved to full image objects and entry references are resolved to entry object(s).
-
-| Model type | Content JSON value / template value |
-|---|---|
-| `text`, `paragraph`, `richtext`, `markdown`, `code`, `color`, `link` | String |
-| `number` | Number |
-| `boolean` | `true` / `false` |
-| `emoji` | Single Unicode emoji character string, e.g. `"😀"` or `"👋🏽"` (one emoji per record; not free text) |
-| `date` | `"YYYY-MM-DD"` string |
-| `datetime` | ISO 8601 string |
-| `time` | `"HH:mm"` string |
-| `image` | Either a resolved `{ "url": "...", "alt": "..." }` object, **or** a shortcut string `"<source>:<search>"` (e.g., `"pexels:doctor"`, `"url:https://picsum.photos/200.jpg"`, `"cms:logo"`). Supported sources: `unsplash`, `pexels`, `pixabay`, `iconify`, `url`, `cms` (reuses an image declared in `/images.json` by handle). Append `\|<alt text>` to set the image's alt, e.g. `"pexels:doctor\|Smiling doctor with stethoscope"`. On save, the sync engine resolves the shortcut/link to a full image object automatically. |
-| `video` | Object of shape `{ "source": "BUNNY", "video_id": "...", "embed_url": "...", "title": "..." }`. **Do not write or invent this value.** Video uploads are user-driven in the CMS UI — the user uploads to Bunny.net and the sync engine stores the resolved object. In templates, always render videos with the `embed()` helper (e.g. `<%- embed(item.intro_video, { size: '1280x720' }) %>`), never by hand-rolling an iframe. The site's available video handles are exposed read-only at `/content/videos.json` (`handle → embed_url`) — look them up in templates with `getVideo('<handle>')`. |
-| `file` | Object of shape `{ "name": "...", "url": "...", "size": 0, "type": "...", "ext": "..." }` describing a downloadable document (PDF, CSV, DOC/DOCX, XLS/XLSX, PPT/PPTX, TSV, TXT — max 10 MB). **Do not write or invent this value.** File uploads are user-driven in the CMS UI — the user attaches the file via the editor and the sync engine stores the resolved object. In templates, render a link with `item.file.url` (download URL on `files.sleekcms.com`) and `item.file.name` (display name), e.g. `<a href="<%= item.brochure.url %>" download><%= item.brochure.name %></a>`. |
-| `json` | Object or array |
-| `sheet` | Array of arrays |
-| `location` | `{ "markers": [{ "lat": n, "lng": n }], "img": "..." }`; `img` is a Google Maps Static Image URL that already includes the markers and can include formatting parameters such as `size`, `zoom`, `scale`, `maptype`, and styling |
-| `block(key)` | Object matching that block's model; stored inline in the parent page/entry content and rendered with `blocks/<key>.ejs` |
-| `[block(key)]` | Array of block objects; each item matches the block model and renders with `blocks/<key>.ejs` |
-| `stack` | Array of heterogeneous block-shaped objects. Each item is `{ "_block": "<block_key>", ...fields_of_that_block }`. `_block` is the target block's key as a plain string; the remaining keys must match that block's model. Different items in the same stack may use different blocks. Stored inline; each item renders through its own `blocks/<key>.ejs`. The CMS resolves block keys to ids server-side — never write numeric ids. |
-| `entry(key)` / `[entry(key)]` | Reference token `"<index>\|<text>"` (or an array of them) in content JSON; entry object / array of entry objects in templates. `index` is the 0-based position of the target entry in its `content/entries/<key>+.json` list — that is what binds. `\|<text>` is optional: the **opening characters of that entry's content, copied verbatim** (matched as a substring — not a description you compose), used only to relocate the entry if the list shifted. You may write just the index (`"2"` or `2`). |
-| Group `{ ... }` | Nested object |
-| Collection `[{ ... }]` | Array of nested objects |
-
-`richtext` returns HTML; output it with `<%- %>`. `markdown` returns raw markdown; convert it with `marked()` before output. Inside markdown, use the same image shortcut convention in standard image syntax: `![alt](pexels:doctor)`. Append `\|<alt>` to set alt text, and include a `<width>x<height>` token to set URL `w`/`h` params (defaults to `600x400`), e.g. `![doctor](pexels:doctor\|Smiling doctor 800x600)`.
-
----
-
-## Content Records
-
-Content files are JSON records under `/content/` that hold the actual values for the fields declared in each `.model`. Editing a content file and saving it triggers the same sync-build-deploy loop as editing a template — you can view and edit content directly from this workspace.
+| Model | File | Top-level shape |
+|---|---|---|
+| Single page `about` | `content/pages/about.json` | Object |
+| Collection page `blog+` | `content/pages/blog+/<slug>.json` — one file per record | Object |
+| Qualifying collection page (below) | `content/pages/blog+/<slug>.md` | Frontmatter + markdown body |
+| Single entry `header` | `content/entries/header.json` | Object |
+| Collection entry `authors+` | `content/entries/authors+.json` | **Array** of objects |
 
-**Blocks never have top-level content files.** Block data is always embedded inside the page or entry that declares the block field.
+### Images — shortcut strings
 
-### File layout
+When writing an `image` value, prefer the shortcut form `"<source>:<search>"`. Sources: `unsplash`, `pexels`, `pixabay`, `iconify`, `url` (direct URL), `cms` (reusable handle, below).
 
-| Model shape | File path | Top-level shape |
-|---|---|---|
-| Single page (e.g., `about`) | `content/pages/about.json` | Object |
-| Collection page (e.g., `blog+`) | `content/pages/blog+/<slug>.json` (the `+` is part of the key, not an extra suffix) | Object; one file per slug |
-| Collection page with one markdown body (see below) | `content/pages/blog+/<slug>.md` | YAML frontmatter + markdown body |
-| Single entry (e.g., `header`) | `content/entries/header.json` | Object |
-| Collection entry (e.g., `authors`) | `content/entries/authors+.json` (the `+` is part of the key — same as the model filename) | Array of objects |
+- `"pexels:doctor"` — stock search
+- `"url:https://example.com/photo.jpg"` — specific asset
+- `"iconify:mdi:apple"` — icon
+- Append `|<alt>` to set alt text: `"pexels:doctor|Smiling doctor with stethoscope"`
 
-### Example
+On save, the sync engine resolves each shortcut to a real `{ "url", "alt" }` object.
 
-Given a model:
-
-```
-{ title: text, image: image, hero: block(hero), tags: [entry(tags+)] }
-```
+**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.
 
-The content file at `content/pages/about.json`:
+**Reusable images:** for images used in multiple places (logo, recurring icons), declare them once in `content/images.json` as `handle → shortcut`:
 
 ```json
-{
-    "title": "About us",
-    "image": "pexels:team meeting",
-    "hero": {
-        "heading": "Hello",
-        "subheading": "Welcome",
-        "background": "pexels:doctor",
-        "cta_label": "Contact us",
-        "cta_link": "/contact"
-    },
-    "tags": ["0|Engineering", "2|Design"]
-}
+{ "logo": "url:https://cdn.example.com/logo.svg", "hero": "pexels:mountain sunrise" }
 ```
 
-Here `hero` is embedded block data stored directly in the page content file. `image` and `hero.background` use the shortcut form — on save, the sync engine replaces each shortcut with a real image object (`{ "url": "...", "alt": "..." }`). Write the object form directly when you have a specific asset URL. `tags` references entries by position — `"0|Engineering"` points at the first entry in `content/entries/tags+.json`, where `Engineering` is just the start of that entry's content copied verbatim (a substring check, not a description you write). The index is what binds on save; the text only helps relocate the entry if the list shifted, and a bare index (`"0"`) is also accepted.
+then reference with `"cms:logo"` in any image field, or fetch in templates via `getImage('logo')`.
 
-### Markdown content files
+**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.
 
-For a **collection page** whose model is shaped like "metadata + one long-form body", the sync engine stores each record as a **Markdown file with JSON frontmatter** (`.md`) instead of `.json`. The body is plain Markdown; the metadata is a JSON object between `---` markers.
+### Videos — read-only
 
-A model qualifies when **all** of the following hold:
+`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>`.
 
-1. It is a **page** model (lives in `models/pages/`).
-2. It is a **collection** (key ends with `+`, so each record is its own file).
-3. It has **exactly one** top-level field of type `markdown`.
-4. It has **no** `richtext` or `stack` fields anywhere (top-level or nested).
+### Markdown content files (`.md`)
 
-When the model qualifies, content lives at `content/pages/<key+>/<slug>.md`. All non-markdown fields go into the JSON frontmatter; the single `markdown` field's value becomes the body.
+A collection-page record is stored as Markdown with frontmatter instead of JSON when its model meets **all** of:
 
-Example — given the model `models/pages/blog+.model`:
-
-```
-{
-    title: text,
-    date: date,
-    summary: paragraph,
-    body: markdown
-}
-```
+1. Page model, 2. collection (`+` key), 3. **exactly one** top-level `markdown` field, 4. **no** `richtext` or `stack` anywhere.
 
-The record `content/pages/blog+/welcome-post.md` looks like:
+Then write `content/pages/<key+>/<slug>.md`: all non-markdown fields go in the frontmatter between `---` markers; the single markdown field's value is the body (its key never appears in frontmatter).
 
 ```markdown
 ---
@@ -366,177 +259,108 @@ The record `content/pages/blog+/welcome-post.md` looks like:
 ---
 # Hello
 
-This is the **first** post.
-
-- one
-- two
-```
-
-Notes:
-- The body field's handle (`body` above) is whatever the single `markdown` field is called in the model — its key never appears in the frontmatter; its value is the markdown content.
-- Image shortcut conventions still apply inside the markdown body (`![alt](pexels:doctor)`) and inside frontmatter image fields (`"pexels:doctor"`).
-- If the model doesn't qualify (e.g., it has two markdown fields, or a `stack`), the content stays JSON at `content/pages/<key+>/<slug>.json` — no change.
-- The server still accepts `.json` for qualifying models — sending `.md` is preferred but not required. The next pull will re-emit the canonical `.md` form.
-
-**YAML frontmatter is also accepted as input.** The server detects whichever shape you write between the `---` markers and parses it correctly. The canonical form emitted by the server is JSON — on the next pull, YAML frontmatter is rewritten to JSON.
-
-```markdown
----
-title: Welcome to the blog
-date: '2026-05-19'
-summary: A short post.
----
-# Hello
-
 This is the **first** post.
 ```
 
-JSON5 features (trailing commas, `//` or `/* */` comments, unquoted keys) are accepted in JSON frontmatter. Choose JSON for programmatic generation (and to match canonical output); YAML is fine for hand-edits.
+Frontmatter may be JSON (canonical — prefer it when generating), JSON5, or YAML; all parse correctly. The server also still accepts plain `.json` for qualifying models. Image shortcuts work in both frontmatter and body.
 
-### Reusable images (`/images.json`)
+## 8. Views (EJS)
 
-For images used in more than one place (logos, recurring icons, hero art), declare them once in `/images.json` as a flat map of `handle → shortcut` using the same shortcut convention as `image` fields:
-
-```json
-{
-    "logo": "url:https://cdn.example.com/logo.svg",
-    "hero": "pexels:mountain sunrise",
-    "apple-icon": "iconify:mdi:apple"
-}
-```
-
-Then reference any of them from any content `image` field with `"cms:<handle>"` (e.g., `"cms:logo"`). The sync engine resolves it to the full image object on save. Templates can also fetch the resolved object directly via `getImage('<handle>')`.
-
-### Site videos (`/videos.json`) — READ-ONLY
-
-`/content/videos.json` is a flat map of `handle → embed_url` describing every video the user has uploaded to this site via the CMS UI (Bunny.net):
-
-```json
-{
-    "intro": "https://iframe.mediadelivery.net/embed/<lib>/<guid>",
-    "testimonial-jane": "https://iframe.mediadelivery.net/embed/<lib>/<guid>"
-}
-```
-
-**Do not edit `/content/videos.json`.** It is regenerated from the user's uploads — local edits will not sync and will be overwritten on the next pull. Use it only to discover which video handles are available, then fetch the resolved video object inside templates with `getVideo('<handle>')` and render it via `embed()`:
-
-```ejs
-<%- embed(getVideo('intro'), { size: '1280x720' }) %>
-```
-
----
-
-## EJS Templates
-
-### Syntax
+### Tags
 
 | Tag | Purpose |
 |---|---|
-| `<%= expr %>` | Output with HTML escaping (text content) |
-| `<%- expr %>` | Output raw HTML (blocks, images, rich text, helpers) |
-| `<% code %>` | Execute JS (loops, conditionals, variables) |
+| `<%= expr %>` | Output, HTML-escaped (plain text) |
+| `<%- expr %>` | Output raw HTML (`render()`, `img()`, `marked()`, richtext) |
+| `<% code %>` | Run JS (loops, conditionals) |
 
-### Template Context
+### Context variables (every view)
 
-Every template receives these variables:
-
-| Variable | Type | Description |
-|---|---|---|
-| `item` | Object | Current page, block, or entry being rendered |
-| `pages` | Array | All page records (each has `_path`, `_slug`, fields) |
-| `entries` | Object | All entries keyed by model handle |
-| `main` | String | Rendered page template output (**layout only**) |
+| Variable | Description |
+|---|---|
+| `item` | The current record: the page in a page view, the block instance in a block view, the entry in an entry view |
+| `pages` | All page records (each has `_path`, `_slug`, fields) |
+| `entries` | All entries keyed by handle |
+| `main` | Rendered page HTML — **layout only** |
 
-`item` always refers to the current record. In a page template, `item` is the page. In a block template, `item` is the block instance. In an entry template, `item` is the entry.
+Page records also expose `item._path`, `item._slug` (collections), and `item._meta.updated_at` (ISO timestamp).
 
-Page records include: `item._path`, `item._slug` (collections), `item._meta.updated_at`.
+### Layout
 
----
+There is exactly **one** layout: `layouts/common.ejs`. It wraps every page automatically — pages cannot select a different layout or opt out. It contains `<html>`, `<head>`, `<body>`, and injects the page output via `<%- main %>`. The only exception: page keys with a file extension (e.g. `rss.xml`) are emitted raw, with no layout.
 
-## Helper Functions
+```ejs
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body>
+  <header><%- render(getEntry('header')) %></header>
+  <main><%- main %></main>
+  <footer><%- render(getEntry('footer')) %></footer>
+</body>
+</html>
+```
 
-### Content Access
+### Helpers — content access
 
-| Function | Returns | Description |
+| Function | Returns | Notes |
 |---|---|---|
-| `getPage(path)` | Object \| undefined | Page by exact path |
-| `getPages(path, opts?)` | Array | Pages where path starts with prefix. `{ collection: true }` for collection pages only |
-| `getEntry(handle)` | Object \| Array | Entry by handle. Single → object, collection → array |
+| `getPage(path)` | Object \| undefined | Page by exact URL path |
+| `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(name)` | Object \| undefined | Site-level image by handle |
-| `getVideo(name)` | Object \| undefined | Site-level video by handle (handles listed in `/content/videos.json`, read-only) |
-| `getOptions(name)` | Array \| undefined | Option set as `[{ label, value }]` |
-| `getContent(query?)` | Any | Full content payload, or filter with JMESPath |
+| `getImage(handle)` | Object \| undefined | Resolved image from `images.json` |
+| `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 |
-| `url(pathOrPage?)` | String | Site origin (e.g. `https://example.com`). Pass a path string to get a full URL (`url('/blog')` → `https://example.com/blog`), or pass a page object to resolve its path into a full URL. |
+| `url(pathOrPage?)` | String | Site origin; pass a path or page object for a full absolute URL |
 
-### Rendering
+### Helpers — rendering
 
-| Function | Returns | Description |
-|---|---|---|
-| `render(val, separator?)` | HTML string | Render a block/entry (or array of them) through its template |
-| `marked(md)` | HTML string | Convert a markdown string to HTML |
-
-### Images
-
-| Function | Returns | Description |
-|---|---|---|
-| `src(image, attr)` | URL string | Optimized image URL |
-| `img(image, attr)` | HTML string | `<img>` element |
-| `picture(image, attr)` | HTML string | `<picture>` with dark/light variants |
-| `svg(image, attr?)` | HTML string | Inline SVG with optional attributes |
-
-`attr` can be `"WxH"` string or `{ w, h, size, fit, type, class, style }` object.
-
-### Location
-
-`location` fields can be passed to image helpers for static maps, embedded maps, or marker data.
+| Function | Notes |
+|---|---|
+| `render(val, separator?)` | Render a block, entry, or array of them through its `blocks/<key>.ejs` / `entries/<key>.ejs` view. An `entries/<key>.ejs` view is only needed if you call `render()` on that entry — otherwise just use its data directly |
+| `marked(md)` | Markdown string → HTML string |
 
-| Function | Returns | Description |
-|---|---|---|
-| `src(loc, attr)` | URL string | Static map URL |
-| `img(loc, attr)` | HTML string | Static map `<img>` |
-| `embed(loc, attr?)` | HTML string | Google Maps `<iframe>` |
-| `markers(loc)` | `{ lat, lng }[]` | Marker coordinates |
+### Helpers — images & maps
 
-`attr` can be `"WxH"` or `{ w, h, size, zoom, maptype, scale, class, style }`.
+| Function | Returns |
+|---|---|
+| `src(image, attr)` | Optimized image URL |
+| `img(image, attr)` | `<img>` element |
+| `picture(image, attr)` | `<picture>` with dark/light variants |
+| `svg(image, attr?)` | Inline SVG |
 
-### Video
+`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`).
 
-`video` field content is created by the user via the CMS UI (uploading to Bunny.net). **The agent must never write a value into a `video` field, build an `<iframe>` tag by hand, or guess a `video_id` / `embed_url`.** Always render a video by passing the field object to the `embed()` helper.
+### Helpers — video
 
-| Function | Returns | Description |
-|---|---|---|
-| `embed(video, attr?)` | HTML string | Provider-aware `<iframe>` for the 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.
 
-`attr` is `"WxH"` or `{ w, h, size, autoplay, muted, loop, preload, t, class, style }`.
-
-```ejs
-<%- embed(item.intro_video) %>
-<%- embed(item.intro_video, '1280x720') %>
-<%- embed(item.intro_video, { autoplay: true, muted: true, loop: true }) %>
-<%- embed(item.intro_video, { size: '800x450', class: 'video', style: 'border-radius:8px' }) %>
-```
+### Helpers — bookings
 
-Most browsers block autoplay unless `muted: true` is also set. `autoplay` is added to the iframe's `allow` attribute only when the caller opts in.
+`bookings(name, options?)` renders the appointment-booking widget mount div (see §11). `options` is `{ accent, class, style }`.
 
-### Head Injection
+### Helpers — head injection
 
-Call from **any template** (page, block, entry, or layout). Deduplicated automatically.
+Callable from **any** view (page, block, entry, layout); duplicates are removed automatically.
 
 | Function | Description |
 |---|---|
-| `title(text)` | Set page `<title>` |
-| `meta(attrs)` | Add `<meta>` tag |
-| `link(value, order?)` | Add `<link>` tag (string URL auto-detects type, or pass object) |
-| `style(css, order?)` | Add `<style>` block |
-| `script(value, order?)` | Add `<script>` (`.js` URL → external, otherwise inline) |
+| `title(text)` | Set `<title>` |
+| `meta(attrs)` | Add `<meta>` |
+| `link(value, order?)` | Add `<link>` — a string URL auto-detects type, or pass an object |
+| `style(css, order?)` | Add `<style>` |
+| `script(value, order?)` | Add `<script>` — `.js` URL → external, otherwise inline |
 
----
+**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.
 
-## SEO
+## 9. SEO
 
-Create a **block model** (e.g., `seo.model`) and add SEO tags manually in its template:
+Make every site strongly SEO- and sharing-friendly. The standard pattern is a reusable SEO block:
 
 **`models/blocks/seo.model`**
 ```
@@ -551,18 +375,14 @@ Create a **block model** (e.g., `seo.model`) and add SEO tags manually in its te
 ```ejs
 <% if (item.title) title(item.title) %>
 <% if (item.description) meta({ name: 'description', content: item.description }) %>
-<% if (item.image) { %>
-  <% meta({ property: 'og:image', content: src(item.image, '1200x630') }) %>
-<% } %>
+<% if (item.image) meta({ property: 'og:image', content: src(item.image, '1200x630') }) %>
 ```
 
-Then include `seo: block(seo)` in any page model and render it: `<%- render(item.seo) %>`
-
----
+Add `seo: block(seo)` to page models and `<%- render(item.seo) %>` in page views.
 
-## Forms
+## 10. Forms
 
-Any `<form>` with a `data-sleekcms="<name>"` attribute works automatically — submissions are captured, stored, and viewable in the CMS dashboard. No backend setup, no action URL, no JS required.
+Any `<form>` with `data-sleekcms="<name>"` works automatically — submissions are captured and shown in the CMS dashboard. No backend, no action URL, no JS.
 
 ```html
 <form data-sleekcms="contact">
@@ -573,13 +393,23 @@ Any `<form>` with a `data-sleekcms="<name>"` attribute works automatically — s
 </form>
 ```
 
-The `<name>` value (e.g., `contact`, `newsletter`, `quote-request`) groups submissions by form. Use standard `name` attributes on inputs — each field is stored as-is.
+The `data-sleekcms` value groups submissions by form; each input's `name` is stored as-is.
 
----
+## 11. Bookings
 
-## RSS Feeds
+Drop an appointment-booking widget on any page with the `bookings()` helper. Visitors pick a time slot and book right on the page; email confirmation, calendar invites, and cancel/reschedule are handled by the CMS — no backend, no JS.
+
+```ejs
+<%- bookings('consultation') %>
+
+<%- bookings('consultation', { accent: '#8c672a', class: 'mx-auto', style: 'max-width: 420px' }) %>
+```
 
-Create an RSS feed by adding a page with the key `rss.xml` — this maps to the URL `/rss.xml`. Because the extension is `.xml`, the static server serves it with the correct content type automatically. The template outputs raw XML and must **not** use a layout.
+Renders `<div data-sleekcms-booking="consultation"></div>` (a literal div with that attribute works too); the widget script is injected automatically at publish. A calendar named `consultation` is **auto-created on sync** with default settings: 30-minute slots, one booking at a time, Mon–Fri 9 AM–5 PM in America/New_York, email confirmation on. The defaults are guesses — tell the user to review the timezone and open hours under **Customers › Bookings › Calendars**. Reusing the same name across pages shares one calendar.
+
+## 12. RSS Feeds
+
+Always create an RSS feed for blogs. Use the page key `rss.xml` — because the key has an extension, it is served as XML with **no layout**, automatically.
 
 **`models/pages/rss.xml.model`**
 ```
@@ -591,10 +421,7 @@ Create an RSS feed by adding a page with the key `rss.xml` — this maps to the
 
 **`content/pages/rss.xml.json`**
 ```json
-{
-    "title": "My Blog",
-    "description": "Latest posts from My Blog"
-}
+{ "title": "My Blog", "description": "Latest posts from My Blog" }
 ```
 
 **`pages/rss.xml.ejs`**
@@ -609,7 +436,7 @@ Create an RSS feed by adding a page with the key `rss.xml` — this maps to the
     <item>
       <title><%= post.title %></title>
       <link><%= url(post) %></link>
-      <description><%= post.description %></description>
+      <description><%= post.summary %></description>
       <pubDate><%= new Date(post._meta.updated_at).toUTCString() %></pubDate>
       <guid><%= url(post) %></guid>
     </item>
@@ -618,118 +445,18 @@ Create an RSS feed by adding a page with the key `rss.xml` — this maps to the
 </rss>
 ```
 
-Notes:
-- The key `rss.xml` follows the standard naming convention — the dot is part of the key as-is.
-- `getPages('/blog', { collection: true })` fetches all blog collection pages; adjust the path to match your collection key.
-- `url(post)` resolves the page object to a full absolute URL (e.g. `https://example.com/blog/my-post`) — no need to store the site URL in content.
-- `post._meta.updated_at` is an ISO 8601 timestamp; `.toUTCString()` converts it to RFC 822 format required by RSS.
-- Use a dedicated `description` or `summary` field in your blog model for feed excerpts; fall back to any short-text field if one doesn't exist.
-- To autodiscover the feed, add `<% link({ rel: 'alternate', type: 'application/rss+xml', title: 'RSS', href: '/rss.xml' }) %>` in your layout or page templates.
-
----
-
-## Examples
+Make it discoverable from the layout: `<% link({ rel: 'alternate', type: 'application/rss+xml', title: 'RSS', href: '/rss.xml' }) %>`
 
-### Layout
-
-```ejs
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-</head>
-<body>
-  <% const header = getEntry('header'); %>
-  <header>
-    <%- render(header) %>
-  </header>
-
-  <main><%- main %></main>
-
-  <% const footer = getEntry('footer'); %>
-  <footer>
-    <%- render(footer) %>
-  </footer>
-</body>
-</html>
-```
-
-### Page template
-
-```ejs
-<% title(item.title + ' | My Site') %>
-<% link('/css/styles.css') %>
-<% script('/js/app.js') %>
-
-<h1><%= item.title %></h1>
-<%- img(item.image, '1200x600') %>
-<div><%- item.content %></div>
-```
-
-### Block template
-
-```ejs
-<section class="hero" style="background-image: url('<%- src(item.background, '1920x800') %>')">
-  <h2><%= item.heading %></h2>
-  <p><%= item.subheading %></p>
-  <a href="<%= item.cta_link %>" class="btn"><%= item.cta_label %></a>
-</section>
-```
-
-### List collection pages
-
-```ejs
-<% for (const post of getPages('/blog', { collection: true })) { %>
-  <a href="<%- path(post) %>">
-    <%- img(post.image, '400x250') %>
-    <h3><%= post.title %></h3>
-  </a>
-<% } %>
-```
-
-### Render blocks and entry references
-
-Given a model:
-```
-{
-    hero: block(hero),
-    ctas: [block(cta)],
-    team: [entry(people+)]
-}
-```
-
-Template:
-```ejs
-<%- render(item.hero) %>
-<%- render(item.ctas) %>
-
-<% for (const person of item.team) { %>
-  <%- render(person) %>
-<% } %>
-```
-
----
+## 13. Critical Rules Checklist
 
-## Rules for AI
-
-1. Include CSS/JS files via **`link()`** and **`script()`** — never raw `<link>` or `<script>` tags in templates.
-2. Exception: `/css/tailwind.css` is auto-injected — do **not** add it via `link()`.
-3. `richtext` returns **HTML** — use `<%- %>` (unescaped) to output it. `markdown` returns **raw markdown** — convert with `marked()` first: `<%- marked(item.content) %>`.
-4. Use modern design with tailwind unless design details are specified.
-5. If sync, build, render, image resolution, or deploy behavior fails, check `sync-errors.log` in the workspace root before guessing.
-6. To change what appears on a page or in shared data, edit the matching JSON under `/content/` — do **not** hard-code content into `.ejs` templates. Templates define structure; content files hold the values.
-7. Fields in a content JSON file must match the keys defined in the corresponding `.model`. Adding a new field requires updating the `.model` first.
-8. Collection page items each live in their own file under `content/pages/<key>/<slug>.json` — the collection key already includes `+` (e.g., `content/pages/blog+/my-post.json`). The `<slug>` filename is the URL segment; renaming the file renames the URL.
-9. **Collection key suffix `+` is mandatory and must appear on every related file.** For a collection model (pages or entries — e.g., `blog`, `testimonials`, `authors`), the key `<name>+` is part of the filename on the model, template, **and** content JSON: `models/entries/testimonials+.model`, `entries/testimonials+.ejs`, `content/entries/testimonials+.json` (array). Same rule for collection pages: `models/pages/blog+.model`, `pages/blog+.ejs`, and one file per slug under `content/pages/blog+/<slug>.json`. Never drop the `+` — files without it are treated as singles and will not resolve.
-10. Blocks are reusable component schemas/templates only. Never create `content/blocks/...`; store block values inline in the page or entry JSON that declares `block(key)` or `[block(key)]`.
-11. Use blocks only when a group of fields also benefits from a reusable template. For one-off page-only structure, prefer groups (`{ ... }`) or repeating groups (`[{ ... }]`).
-12. Use entries, not blocks, for shared reusable content such as testimonials, authors, people, categories, tags, navigation, or footer data.
-13. Block models cannot contain `block(...)` fields. Use groups, collections, or `entry(key)` references instead.
-14. For `image` fields in content JSON, prefer the shortcut form `"<source>:<search>"` (sources: `unsplash`, `pexels`, `pixabay`, `iconify`) — e.g., `"pexels:doctor"`. Add alt text by appending `|<alt>` to the shortcut: `"pexels:doctor|Smiling doctor with stethoscope"`. The sync engine resolves it to a full `{ url, alt }` object on save. When the same image is reused across pages (logos, shared icons, recurring art), declare it once in `/images.json` and reference it via `"cms:<handle>"`.
-15. Inside `markdown` fields, embed images with `![alt](<source>:<search>)` — same sources as image fields. Append `|<alt>` to store alt on the image record (e.g. `![doctor](pexels:doctor|Friendly family doctor)`). Including a `<W>x<H>` token in the description (e.g. `|hero shot 1200x600`) sets the rendered URL's `w` and `h` query params; otherwise the default is `600x400`. On save, refs are rewritten to actual CDN URLs and the underlying image record is created automatically.
-16. **Collection pages whose model qualifies as "markdown content" — page model, collection (key ends with `+`), exactly one top-level `markdown` field, no `richtext` or `stack` anywhere — are stored as `.md` files with JSON frontmatter at `content/pages/<key+>/<slug>.md` (not `.json`).** All non-markdown fields go into the JSON frontmatter object between the `---` markers; the single `markdown` field's value is the body. When creating or editing such a record, prefer `.md`; the server also accepts `.json` for the same model. Inside the `.md` file, frontmatter may be written as JSON (canonical), JSON5 (trailing commas, `//` or `/* */` comments, unquoted keys), or YAML — all three are parsed correctly on save. Pulls always re-emit JSON as the canonical form.
-17. Always create RSS feed for blogs and link them in meta so it is discoverable. Use "rss.xml" as the key.
-18. Make the sites extremely SEO friendly and sharing friendly.
-19. When naming files for models, use - (dash) as word separator. Don't use _ (underscore) as it is mapped to / (slash) in path
-20. Not all content details need to be modeled. If there is content which is not meant to be updated, such as button labels, links etc. you can inline that in the EJS view instead of adding fields to model and using from there. Decide what is relevant.
+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`.