@typeroll/mcp-server 0.7.5 → 0.7.8

package/skills/tr-blog.md

@@ -0,0 +1,171 @@
+---
+name: tr-blog
+description: Use when the user wants to set up a blog, news section, podcast feed, or any time-ordered article-style content on a Typeroll site. Triggers on "add a blog", "set up news", "article section", "create posts", "podcast", "inlägg", "nyheter", "avsnitt", or any feed-of-dated-entries pattern.
+---
+
+# Set up a blog / news section
+
+A blog in Typeroll is a **collection with `item_template_html` + `route_template`**. Every published item materialises as its own static page at build time — there is **no need to call `create_page` per article**. The detail design lives once in `item_template_html`; the listing lives once in a page with a `<!-- typeroll:listing -->` marker that `regenerate_collection_listing` refreshes.
+
+If you find yourself about to create 20 pages for 20 articles, stop — you're using the old pattern. The recipe below is the right one.
+
+## Preconditions
+
+- Site exists with working header/footer.
+- Collection name picked (`blog`, `news`, `artiklar`, `podcast`, `avsnitt`).
+- URL structure picked: `/blog/{slug}`, `/news/{slug}`, `/podd/{slug}`. Changing later renames every URL.
+
+## Recipe
+
+### 1. Create the collection with detail template baked in
+
+```
+create_collection {
+  "name": "blog",
+  "label_singular": "Artikel",
+  "label_plural": "Artiklar",
+  "icon": "📝",
+  "slug_field": "slug",
+  "sort_field": "date",
+  "sort_dir": "desc",
+  "route_template": "/blog/{slug}",
+  "item_template_html": "<article class=\"post\">\n  <header class=\"post__header\">\n    <time>{{date}}</time>\n    <h1>{{title}}</h1>\n    {{#author}}<p class=\"byline\">av {{author}}</p>{{/author}}\n  </header>\n  {{#image}}<img class=\"post__hero\" src=\"{{image}}\" alt=\"{{title}}\" />{{/image}}\n  <div class=\"post__body\">{{{body}}}</div>\n</article>\n<style>\n.post{max-width:42rem;margin:3rem auto;padding:0 1rem}\n.post__header time{color:var(--color-text-light);font-size:0.85rem}\n.post__header h1{font-family:var(--font-heading);font-size:2.25rem;margin:0.25rem 0}\n.byline{color:var(--color-text-light);font-size:0.9rem}\n.post__hero{width:100%;aspect-ratio:16/9;object-fit:cover;border-radius:0.5rem;margin:2rem 0}\n.post__body{font-size:1.05rem;line-height:1.7}\n.post__body h2{font-family:var(--font-heading);margin-top:2rem}\n.post__body p{margin-bottom:1.25rem}\n</style>",
+  "fields": [
+    {"name": "title",   "type": "text",     "label": "Rubrik",    "required": true},
+    {"name": "slug",    "type": "text",     "label": "URL-slug",  "required": true},
+    {"name": "date",    "type": "date",     "label": "Datum",     "required": true},
+    {"name": "author",  "type": "text",     "label": "Författare"},
+    {"name": "excerpt", "type": "textarea", "label": "Ingress"},
+    {"name": "body",    "type": "richtext", "label": "Brödtext"},
+    {"name": "image",   "type": "image",    "label": "Omslagsbild"}
+  ]
+}
+```
+
+**About `item_template_html`:**
+- `{{field}}` HTML-escapes the value (use for plain text).
+- `{{{field}}}` leaves it raw (use for `body` and any richtext).
+- `{{#field}}...{{/field}}` is a conditional — render the block only if the field is truthy. Useful for optional images, authors, etc.
+- **No loops, no nested conditionals.** If you need either, pre-render the HTML in a field on the item itself (see tr-collection-template for patterns).
+
+**Field name rule:** ASCII only, lowercase, `[a-z][a-z0-9_-]*`. `ä→a`, `ö→o`, `å→a` for the `name`; the `label` can be anything.
+
+### 2. Seed with real content
+
+```
+create_collection_item collection="blog" status="published" fields={
+  "title":   "Vår designfilosofi",
+  "slug":    "var-designfilosofi",
+  "date":    "2025-05-15",
+  "author":  "Anna Lindström",
+  "excerpt": "Vi tror på enkelhet med syfte — varje beslut ska kunna motiveras.",
+  "body":    "<p>Lång brödtext här...</p><h2>En underrubrik</h2><p>Mer text...</p>",
+  "image":   "https://cdn.typeroll.com/..."
+}
+```
+
+If `image` is a URL from elsewhere, upload it first via `upload_media_from_url` and use the returned CDN URL.
+
+Each published item with this collection's `route_template` automatically becomes `/blog/{slug}` at deploy time — you do **not** need to call `create_page`.
+
+### 3. Build the listing page (once)
+
+Create a single page that hosts the listing. The HTML between the `typeroll:listing` markers gets regenerated whenever the collection changes:
+
+```
+create_page title="Artiklar" slug="blog" status="published" content_mode="html"
+  html_content="<section class=\"blog-listing\">
+  <div class=\"container\">
+    <h1 class=\"section-title\">Artiklar</h1>
+    <!-- typeroll:listing:blog -->
+    <!-- /typeroll:listing:blog -->
+  </div>
+</section>
+<style>
+.blog-listing{padding:4rem 0}
+.blog-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(300px,1fr));gap:2rem;margin-top:2rem}
+.blog-card{border:1px solid var(--color-surface);border-radius:0.5rem;overflow:hidden}
+.blog-card a{text-decoration:none;display:block;color:var(--color-text)}
+.blog-card img{width:100%;aspect-ratio:16/9;object-fit:cover}
+.blog-card__body{padding:1.5rem}
+.blog-card__date{font-size:0.8rem;color:var(--color-text-light);display:block;margin-bottom:0.5rem}
+.blog-card__title{font-family:var(--font-heading);font-size:1.25rem;margin-bottom:0.5rem}
+.blog-card__excerpt{color:var(--color-text-light);font-size:0.9rem;margin-bottom:1rem}
+.blog-card__cta{color:var(--color-accent);font-size:0.85rem;font-weight:600}
+</style>"
+```
+
+### 4. Populate the listing (and re-run after every change)
+
+```
+regenerate_collection_listing
+  collection="blog"
+  page_id="blog"
+  item_template="<article class=\"blog-card\">
+    <a href=\"{{url}}\">
+      {{#image}}<img src=\"{{image}}\" alt=\"{{title}}\">{{/image}}
+      <div class=\"blog-card__body\">
+        <time class=\"blog-card__date\">{{date}}</time>
+        <h2 class=\"blog-card__title\">{{title}}</h2>
+        <p class=\"blog-card__excerpt\">{{excerpt}}</p>
+        <span class=\"blog-card__cta\">Läs mer →</span>
+      </div>
+    </a>
+  </article>"
+  wrap_open="<div class=\"blog-grid\">"
+  wrap_close="</div>"
+```
+
+`{{url}}` resolves through the collection's `route_template`. Only the content between the markers is replaced; everything else on the page stays put. Re-run this whenever items are added, edited, or unpublished.
+
+### 5. Update the header partial to link to the listing
+
+```
+read_partial partial_id="header"
+replace_partial partial_id="header" html_content="<updated with /blog link>"
+```
+
+### 6. Preview a single article
+
+```
+get_preview_link collection_name="blog" item_id="<id>"
+```
+
+The returned URL renders the item through `item_template_html` exactly as it'll appear in production.
+
+### 7. Deploy
+
+```
+trigger_deploy
+get_deploy_status job_id=<id>
+```
+
+The build produces one HTML file per published article at `/blog/<slug>` plus the listing at `/blog`, and includes them all in `sitemap.xml`.
+
+## Adding a new article later
+
+```
+create_collection_item collection="blog" status="published" fields={ ... }
+regenerate_collection_listing collection="blog" page_id="blog" item_template="..." wrap_open="..." wrap_close="..."
+trigger_deploy
+```
+
+Three calls. No per-article `create_page`. No HTML diffing by hand.
+
+## Pitfalls
+
+- **Don't fall back to "one page per article".** That was the pre-`item_template_html` pattern. It works but it's strictly worse: design changes mean editing N pages, you lose `{{url}}` resolution in listings, sitemap doesn't include items, and previews can't surface a per-item URL. If you find yourself writing `create_page` with `slug: "blog/foo"`, stop and reconsider — the only legitimate reason is a one-off "about the editorial team" page that isn't an article.
+- **Slugs must be unique within the collection.** `regenerate_collection_listing` will silently drop items where `slug` is missing; the listing count will be lower than the item count.
+- **Don't use non-ASCII field names.** `datum` not `Datum`; `forfattare` not `författare` in the `name`. The `label` is free-form.
+- **Listing goes stale if you forget step 4.** Every item change needs `regenerate_collection_listing`. Add it to your mental checklist after every `create/update_collection_item`.
+- **`{{#field}}...{{/field}}` only checks truthiness.** Empty string and the field being absent both count as falsy. If you need "render this block when `published_at` is later than today", do it in the data step — set a flag field.
+- **Template too clever.** Mustache substitution has no loops or arithmetic. For an article with chapter timestamps, multiple authors, a guest with nested links — pre-render the HTML into a single field at `create_collection_item` time. See `tr-collection-template` for concrete patterns.
+
+## When you want a page that ISN'T a collection item
+
+A normal `create_page` is still right for:
+- The blog's about/contact pages.
+- Editorial standalone features.
+- Anything that doesn't fit the "list of dated entries" mould.
+
+Just don't use `create_page` *for the entries themselves*.

package/skills/tr-brand.md

@@ -0,0 +1,169 @@
+---
+name: tr-brand
+description: Use when the user asks to create a brand identity, design system, or visual style for a site. Triggers on "create a brand", "design the look", "choose colors", "pick fonts", "make it look like [reference]", or "rebrand the site". Produces a cohesive palette, typography scale, and CSS custom properties applied to an existing site.
+---
+
+# Design a brand identity for a Typeroll site
+
+This skill turns a brief (or a reference URL/screenshot) into a complete
+visual design system applied to the site's settings and partials.
+
+## Preconditions
+
+- Site exists and MCP is configured.
+- You have at least one of: industry, mood words, reference URL, existing
+  logo colors, or competitor sites to contrast with.
+
+## Step 1 — Gather context
+
+Ask (or infer from the brief):
+
+1. **Industry + audience.** Law firm → formal, trust. Café → warm, approachable.
+   Tech startup → clean, modern. Interior design → refined, editorial.
+2. **Mood words.** 3–5 adjectives the brand should feel: "minimal, Nordic,
+   calm" or "bold, energetic, playful".
+3. **Reference.** A URL, a screenshot, or a competitor they like (and what
+   they want to be different from it).
+4. **Must-keep.** Existing logo color? Legal industry color conventions?
+
+If the user provided a URL, fetch it and note the dominant colors,
+typeface categories, and layout density.
+
+## Step 2 — Build the palette
+
+A Typeroll site uses 7 color tokens:
+
+| Token | Role | Design rule |
+|---|---|---|
+| `primary` | Brand identity. CTA buttons, active nav, links. | High contrast on `background`. |
+| `secondary` | Header, footer, darker sections. | Darker or more neutral than primary. |
+| `accent` | Highlights, price tags, badges, hover states. | High-energy complement. |
+| `background` | Page background. | Near-white for light themes, near-black for dark. |
+| `surface` | Cards, input boxes, code blocks. | Slightly off from `background`. |
+| `text` | Body copy. | ≥4.5:1 contrast ratio on `background`. |
+| `text_light` | Secondary labels, captions, placeholders. | ≥3:1 on `background`. |
+
+**Palette recipes by mood:**
+
+*Nordic / minimal:*
+```
+primary: #1f2a30   secondary: #142027   accent: #c9b89a
+background: #faf8f4  surface: #f2ede5  text: #1f2a30  text_light: #7a7265
+```
+
+*Warm / artisan:*
+```
+primary: #3d2b1f   secondary: #2a1d14   accent: #c8860a
+background: #fdf6ee  surface: #f7ede0  text: #1a1008  text_light: #8a7060
+```
+
+*Modern / tech:*
+```
+primary: #2563eb   secondary: #1e293b   accent: #f59e0b
+background: #ffffff  surface: #f8fafc  text: #0f172a  text_light: #64748b
+```
+
+*Editorial / dark:*
+```
+primary: #e2c08d   secondary: #0f0f0f   accent: #e2c08d
+background: #0f0f0f  surface: #1a1a1a  text: #f5f5f0  text_light: #a0a090
+```
+
+Check WCAG contrast ratios mentally: text on background must be ≥4.5:1.
+The online tool `https://webaim.org/resources/contrastchecker/` is useful
+but not accessible during a tool call — reason about perceived contrast
+instead (light grey on white = bad; dark grey on white = fine).
+
+## Step 3 — Choose typefaces
+
+Pick from high-quality Google Fonts pairings:
+
+| Heading | Body | Mood |
+|---|---|---|
+| Cormorant Garamond | Raleway | Luxury, editorial |
+| Playfair Display | Source Sans 3 | Classic, readable |
+| DM Serif Display | DM Sans | Contemporary, clean |
+| Fraunces | Mulish | Artisan, craft |
+| Syne | Inter | Bold, modern |
+| Plus Jakarta Sans | Plus Jakarta Sans | Clean, versatile |
+| Libre Baskerville | Libre Franklin | Traditional, trustworthy |
+
+Same font for heading and body is fine if it has enough weight variation
+(Inter at 700 + 400 works well).
+
+`size_base` should be 16 for most sites; 17–18 for text-heavy editorial
+sites; 15 for dense dashboards.
+
+## Step 4 — Apply to the site
+
+One call sets everything:
+
+```
+update_site_settings {
+  "colors": { ...all 7 tokens },
+  "fonts":  { "heading": "...", "body": "...", "size_base": 16 },
+  "custom_css": "/* optional: utility classes or @keyframes */"
+}
+```
+
+Read back to confirm: `read_site_settings`.
+
+## Step 5 — Update partials to use the new palette
+
+Partials that hardcoded hex colors need updating. Fetch the header:
+
+```
+read_partial partial_id="header"
+```
+
+If it has hardcoded colors, replace them with CSS variable references
+(`var(--color-primary)`) and call `replace_partial`:
+
+```
+replace_partial partial_id="header" html_content="<updated HTML>"
+```
+
+Same for footer.
+
+## Step 6 — Custom CSS for advanced tokens (optional)
+
+If the brand needs things beyond the 7 base tokens — e.g. a gradient,
+a special border radius, or a branded highlight color — add them via
+`custom_css`:
+
+```css
+:root {
+  --brand-gradient: linear-gradient(135deg, var(--color-primary), var(--color-accent));
+  --radius-brand: 2px;                    /* sharp corners for formal brands */
+  --letter-spacing-display: -0.03em;     /* tight tracking for display headings */
+}
+```
+
+Then reference `var(--brand-gradient)` etc. in page HTML and partials.
+
+## Step 7 — Preview
+
+```
+get_preview_link
+```
+
+Open in browser. Check:
+- Colors render as intended (not "undefined" or missing)
+- Fonts load (Google Fonts link is in `<head>`)
+- Nav text is readable against header background
+- Body text has sufficient contrast
+
+## Pitfalls
+
+- **Don't set colors without checking the header contrast.** If `primary`
+  is light, white nav text becomes unreadable. Either darken `primary` or
+  make the header use `secondary`.
+- **Custom_css is global.** Rules here apply to every page. Keep it to
+  `:root {}` token additions and truly global utilities. Page-specific
+  styles go in the page's HTML `<style>` block.
+- **Google Fonts load time.** Two different font families is fine; three
+  adds measurable LCP impact. Stick to two families with variable-font
+  versions when possible.
+- **Dark themes need dark surface too.** Setting `background: #0f0f0f`
+  but leaving `surface: #f8fafc` (white) breaks every card/input. Always
+  update all 7 tokens as a set.

package/skills/tr-collection-template.md

@@ -0,0 +1,262 @@
+---
+name: tr-collection-template
+description: Use when building a rich per-item detail page for a Typeroll collection — podcast episodes with audio players and chapter timestamps, case studies with guest cards and metric tiles, products with image galleries and spec tables, anything where the detail template would normally want loops or nested data. Covers the "pre-render into a field" pattern that gets you past the template's no-loops-no-conditionals limit.
+---
+
+# Rich detail templates for collections
+
+`item_template_html` uses lightweight Mustache substitution:
+
+- `{{field}}` — HTML-escaped value
+- `{{{field}}}` — raw value (for richtext / pre-rendered HTML)
+- `{{#field}}…{{/field}}` — conditional, render block when field is truthy
+- `{{url}}` — only meaningful in `regenerate_collection_listing`'s `item_template` (resolves through `route_template`)
+
+**No loops, no nested field access, no arithmetic.** `{{chapters[0].title}}` doesn't work. `{{#chapters}}{{title}}{{/chapters}}` doesn't either — the section syntax is truthiness-only, not iteration.
+
+The pattern that gets you everywhere: **pre-render the HTML into a single string field on the item itself.** The agent (you) does the loop in JavaScript/Python during data prep, then writes the resulting HTML into a richtext field like `chapters_html` or `gallery_html`. The template renders it raw with `{{{chapters_html}}}`.
+
+This skill catalogues the patterns we hit most often, with copy-paste recipes.
+
+## Pattern 1 — Audio player + chapter list (podcast episodes)
+
+**Data shape going in:**
+
+```json
+{
+  "title": "Avsnitt 17 — Designsystem på riktigt",
+  "slug": "17-designsystem-pa-riktigt",
+  "date": "2025-05-15",
+  "audio_url": "https://cdn.example.com/avsnitt-17.mp3",
+  "duration_min": 42,
+  "chapters": [
+    { "time_seconds": 0,    "title": "Intro" },
+    { "time_seconds": 132,  "title": "Vad är ett designsystem?" },
+    { "time_seconds": 845,  "title": "Tokens vs. komponenter" },
+    { "time_seconds": 1820, "title": "Vanliga fällor" }
+  ]
+}
+```
+
+**Pre-render `chapters_html` before calling `create_collection_item`:**
+
+```js
+const formatTime = (s) =>
+  s < 3600
+    ? `${Math.floor(s/60)}:${String(s%60).padStart(2,'0')}`
+    : `${Math.floor(s/3600)}:${String(Math.floor(s%3600/60)).padStart(2,'0')}:${String(s%60).padStart(2,'0')}`;
+
+const chaptersHtml = `
+<ol class="chapters">
+  ${item.chapters.map(c => `
+    <li>
+      <button type="button" data-jump-to="${c.time_seconds}">
+        <span class="chapters__time">${formatTime(c.time_seconds)}</span>
+        <span class="chapters__title">${escapeHtml(c.title)}</span>
+      </button>
+    </li>
+  `).join('')}
+</ol>`;
+```
+
+**Schema (note `chapters_html: richtext` — it carries HTML):**
+
+```
+create_collection {
+  "name": "avsnitt",
+  "label_singular": "Avsnitt",
+  "label_plural": "Avsnitt",
+  "slug_field": "slug",
+  "sort_field": "date",
+  "sort_dir": "desc",
+  "route_template": "/podd/{slug}",
+  "fields": [
+    {"name":"title",         "type":"text",     "required":true},
+    {"name":"slug",          "type":"text",     "required":true},
+    {"name":"date",          "type":"date",     "required":true},
+    {"name":"audio_url",     "type":"text",     "required":true},
+    {"name":"duration_min",  "type":"number"},
+    {"name":"excerpt",       "type":"textarea"},
+    {"name":"body",          "type":"richtext"},
+    {"name":"chapters_html", "type":"richtext", "label":"Kapitellista (genereras)"}
+  ],
+  "item_template_html": "<article class=\"episode\">\n  <header class=\"episode__hero\">\n    <p class=\"episode__date\">{{date}} · {{duration_min}} min</p>\n    <h1>{{title}}</h1>\n    <p class=\"episode__excerpt\">{{excerpt}}</p>\n  </header>\n  <div class=\"episode__player\">\n    <audio controls preload=\"metadata\" src=\"{{audio_url}}\"></audio>\n  </div>\n  {{#chapters_html}}<section class=\"episode__chapters\"><h2>Kapitel</h2>{{{chapters_html}}}</section>{{/chapters_html}}\n  <section class=\"episode__notes\">{{{body}}}</section>\n  <script>\n    document.querySelectorAll('[data-jump-to]').forEach(b => {\n      b.addEventListener('click', () => {\n        const a = document.querySelector('audio');\n        if (a) { a.currentTime = Number(b.dataset.jumpTo); a.play(); }\n      });\n    });\n  </script>\n  <style>\n    .episode{max-width:42rem;margin:3rem auto;padding:0 1rem}\n    .episode__hero{background:linear-gradient(135deg,var(--color-primary),var(--color-accent));color:#fff;padding:3rem 2rem;border-radius:1rem;margin-bottom:2rem}\n    .episode__date{opacity:0.85;font-size:0.85rem}\n    .episode__hero h1{font-family:var(--font-heading);font-size:2rem;margin:0.5rem 0}\n    .episode__player audio{width:100%}\n    .chapters{list-style:none;padding:0;margin:1.5rem 0}\n    .chapters li{margin:0.25rem 0}\n    .chapters button{display:flex;gap:1rem;width:100%;background:transparent;border:0;padding:0.5rem 0.75rem;cursor:pointer;text-align:left;border-radius:0.375rem;font:inherit;color:inherit}\n    .chapters button:hover{background:var(--color-surface)}\n    .chapters__time{font-variant-numeric:tabular-nums;color:var(--color-text-light);min-width:4ch}\n  </style>\n</article>"
+}
+```
+
+**Create the item with both raw chapters AND the pre-rendered HTML:**
+
+```
+create_collection_item collection="avsnitt" status="published" fields={
+  "title":         "Avsnitt 17 — Designsystem på riktigt",
+  "slug":          "17-designsystem-pa-riktigt",
+  "date":          "2025-05-15",
+  "audio_url":     "https://cdn.example.com/avsnitt-17.mp3",
+  "duration_min":  42,
+  "excerpt":       "Vi pratar med...",
+  "body":          "<p>...</p>",
+  "chapters_html": "<ol class=\"chapters\">...</ol>"
+}
+```
+
+The raw `chapters` array doesn't need to be stored unless you have a use for it (e.g. regenerating the HTML later from a structured source). If you do want it for round-trip editing, add a `chapters_json: textarea` field and stringify the array into it.
+
+## Pattern 2 — Guest card with nested fields
+
+Each episode features a guest with a name, role, photo, and external links. Mustache can't reach into nested objects, so flatten OR pre-render.
+
+**Option A: Flatten into prefixed fields (preferable when there's ≤1 guest):**
+
+```
+fields: [
+  ...,
+  {"name":"guest_name",  "type":"text"},
+  {"name":"guest_role",  "type":"text"},
+  {"name":"guest_photo", "type":"image"},
+  {"name":"guest_bio",   "type":"textarea"},
+  {"name":"guest_linkedin", "type":"text"},
+  {"name":"guest_website",  "type":"text"}
+]
+```
+
+In the template:
+
+```html
+{{#guest_name}}
+<aside class="guest">
+  {{#guest_photo}}<img src="{{guest_photo}}" alt="{{guest_name}}">{{/guest_photo}}
+  <div>
+    <h3>{{guest_name}}</h3>
+    <p class="guest__role">{{guest_role}}</p>
+    <p>{{guest_bio}}</p>
+    <p class="guest__links">
+      {{#guest_linkedin}}<a href="{{guest_linkedin}}">LinkedIn</a>{{/guest_linkedin}}
+      {{#guest_website}}<a href="{{guest_website}}">Webbplats</a>{{/guest_website}}
+    </p>
+  </div>
+</aside>
+{{/guest_name}}
+```
+
+**Option B: Pre-render `guest_html` (when there are multiple guests or arbitrary depth):**
+
+```js
+const guestHtml = item.guests.map(g => `
+  <article class="guest">
+    ${g.photo ? `<img src="${escapeHtml(g.photo)}" alt="${escapeHtml(g.name)}">` : ''}
+    <div>
+      <h3>${escapeHtml(g.name)}</h3>
+      <p class="guest__role">${escapeHtml(g.role)}</p>
+      ${g.links.map(l => `<a href="${escapeHtml(l.url)}">${escapeHtml(l.label)}</a>`).join(' · ')}
+    </div>
+  </article>
+`).join('');
+```
+
+Then `{{{guests_html}}}` in the template.
+
+## Pattern 3 — Gradient hero with computed colours
+
+The hero needs a colour pair derived from a single brand colour the user picked per item. The template can't compute — pre-compute and pass as fields:
+
+```js
+function shade(hex, amount) { /* lighten/darken */ }
+
+const item = {
+  ...,
+  hero_from: rawColor,
+  hero_to:   shade(rawColor, -0.2),
+};
+```
+
+Template:
+
+```html
+<header class="hero" style="background:linear-gradient(135deg, {{hero_from}}, {{hero_to}})">
+  <h1>{{title}}</h1>
+</header>
+```
+
+Inline style with two substituted hex strings — works because the `{{}}` substitutions sit inside a CSS value, not as a CSS variable name. (Don't do this with user-supplied colours that haven't been validated — a malicious item could break out of the style attribute. For agent-curated colours this is fine.)
+
+## Pattern 4 — Image gallery with thumbnails
+
+Same drill. The agent renders the gallery HTML when shaping the item:
+
+```js
+const galleryHtml = `
+<div class="gallery">
+  ${item.images.map((img, i) => `
+    <a href="${escapeHtml(img.full)}" class="gallery__item">
+      <img src="${escapeHtml(img.thumb)}" alt="${escapeHtml(img.alt || `Bild ${i+1}`)}" loading="lazy">
+    </a>
+  `).join('')}
+</div>`;
+```
+
+Schema gains `gallery_html: richtext`. Template renders `{{{gallery_html}}}`.
+
+For a lightbox you can either inline a tiny vanilla JS handler in the item_template_html (works once per page load) or `tr-images` the gallery into a reusable partial.
+
+## Pattern 5 — Spec table (for products, services, etc.)
+
+For a fixed set of spec fields (price, dimensions, in-stock, lead time), just add the fields explicitly:
+
+```
+fields: [
+  ...,
+  {"name":"price_sek",  "type":"number"},
+  {"name":"weight_g",   "type":"number"},
+  {"name":"in_stock",   "type":"boolean"},
+  {"name":"lead_days",  "type":"number"}
+]
+```
+
+```html
+<dl class="specs">
+  {{#price_sek}}<dt>Pris</dt><dd>{{price_sek}} kr</dd>{{/price_sek}}
+  {{#weight_g}}<dt>Vikt</dt><dd>{{weight_g}} g</dd>{{/weight_g}}
+  <dt>Lagerstatus</dt><dd>{{#in_stock}}I lager{{/in_stock}}{{^in_stock}}Slut{{/in_stock}}</dd>
+  {{#lead_days}}<dt>Leveranstid</dt><dd>{{lead_days}} dagar</dd>{{/lead_days}}
+</dl>
+```
+
+(`{{^field}}…{{/field}}` is the inverse of `{{#field}}` — render when falsy.)
+
+For variable specs (different products have different attributes), fall back to a pre-rendered `specs_html` field.
+
+## Pre-rendering helpers — minimum viable
+
+Every pre-render needs `escapeHtml`. Put this at the top of your data-prep script:
+
+```js
+const escapeHtml = (s) =>
+  String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+```
+
+Skip it only when you're certain the value can't carry user-supplied content (your own constants are fine; anything from a scrape, the user, or a model output goes through `escapeHtml`).
+
+## When to flatten vs pre-render
+
+Rough guideline:
+
+| Situation | Approach |
+|---|---|
+| 1–N optional related fields, fixed shape | Flatten into prefixed fields (`guest_name`, `guest_role`, …) and use `{{#field}}` conditionals |
+| List of items with internal structure (chapters, gallery, related-links) | Pre-render to a single `*_html` field |
+| Computed values (formatted dates, derived colours, totals) | Pre-compute as a sibling field, substitute with `{{}}` |
+| Conditional sections based on multiple fields ("show this when status=published AND has_video") | Pre-compute a boolean field; conditional in the template |
+| Genuinely dynamic content that changes per visitor | Doesn't fit — the static template renders once at build. Move to client-side JS in the template body, or rethink the page. |
+
+## Pitfalls
+
+- **Forgetting `{{{ }}}` for pre-rendered HTML.** `{{chapters_html}}` (double braces) HTML-escapes the angle brackets and shows source code. Must be triple braces.
+- **Mutating a published item's schema.** Removing or renaming a field that the template references silently produces empty sections. Keep templates in sync with schema changes.
+- **Pre-rendered HTML drifts when you change the visual design.** The HTML for `chapters_html` was generated against the design as it was on import day. If you redo the look later, you need to re-prep + re-write every item's pre-rendered field, not just the template. Consider keeping the raw data (`chapters_json: textarea` with the original array stringified) so you can regenerate.
+- **Inline `<script>` in `item_template_html` runs once per page.** That's fine for self-contained per-page widgets (the audio chapter-jumper above). If two collections need the same widget, factor it into a partial that both `item_template_html`s `<x-include>`.
+- **Don't put credentials in pre-rendered HTML.** API keys, signed tokens — they go into the build output and end up on the public web. Run any prep step you wouldn't paste into a public Gist with that in mind.