docs(agent): meta.agent Anleitungen plus Design-Guide für freie Blöcke

Ohne Repo verständlich: Routen, Lookup-Pfade, Upload-Format src/path, translationKey-Falle, SSR-Cache, Tailwind/Svelte-Regeln.

api/collections/comment.yml

@@ -7,6 +7,13 @@ meta:
   muiIcon: chat
   group: community
   imageUrl: "https://images.unsplash.com/photo-1522096823084-2d1aa8411c13?auto=format&fit=crop&q=80&w=800"
+  agent:
+    purpose: "Page comments counted via aggregate and listed per contentId."
+    instructions: "Required: contentId (content.id), author, message. App loads aggregate commentCount plus list {active:true, contentId}. Only active:true is public."
+    fieldHints:
+      contentId: "content.id the comment belongs to"
+    examples: [{ author: "Demo", message: "Nice page", active: true }]
+    hints: ["mutations invalidate SSR via clear_cache hooks"]
   preview:
     label: author
     secondary: message

api/collections/content.yml

@@ -30,6 +30,16 @@ meta:
     - group: seo
       label: { de: "SEO", en: "SEO" }
   viewHint: cards
+  agent:
+    purpose: "CMS pages rendered by App.svelte + BlockRenderer (hero, features, richtext, accordion, contact-form)."
+    instructions: "Required: name, path, lang. Always set translationKey (unique per lang, avoids null/de collision) and active:true for public. path pattern ^/[a-z0-9-/]*$. Blocks: hero needs headline + heroImage.image (medialib ID); richtext needs text + imagePosition none/left/right + image (medialib ID, only shown when lookup resolves file.src); features needs featureBoxes[{icon,title,text}] with icon in lightning/palette/database/globe/monitor/flask; accordion needs accordionItems[{question,answer,open}]; contact-form needs headline + anchorId. Always request lookup blocks.heroImage.image:medialib,blocks.image:medialib."
+    fieldHints:
+      path: "lowercase, e.g. /ueber-uns; stored without language prefix"
+      translationKey: "required, e.g. home/ueber-uns/kontakt; unique per lang"
+      blocks: "type selects visible fields via dependsOn $parent.type"
+    examples: [{ name: "Startseite", path: "/", lang: "de", translationKey: "home", active: true }]
+    workflows: ["filter before create (path+lang) to stay idempotent; 409 means exists", "after PUT/DELETE verify /de and /api/content?lookup; SSR invalidates via clear_cache hooks"]
+    hints: ["richtext image only renders when _lookup.image.file.src exists", "hero fallback is gradient when no image"]
 
 hooks:
   get:

api/collections/medialib.yml

@@ -40,6 +40,14 @@ meta:
       muiIcon: file_document
       filter:
         file.type_like: ^(?!image/|video/|audio/).+
+  agent:
+    purpose: "Reusable uploads referenced via foreignMedia (blocks.heroImage.image, blocks.image)."
+    instructions: "Upload file as object {src:'data:<mime>;base64,...', path:'name.jpg'} (path optional). Stored as {src:'<field>/name.jpg', path, type}. Never {filename,data}, never file as plain string. Public read URL: /api/medialib/<entryId>/<src> plus ?filter=l-webp for raster images. downscale max 2048px applies on upload."
+    fieldHints:
+      file: "required, widget file, max 50MB"
+      alt: "object {de,en}, used by MedialibImage for accessibility"
+    examples: [{ title: "Demo Hero 1200", file: { src: "data:image/jpeg;base64,...", path: "demo-hero-1200.jpg" } }]
+    hints: ["list with select excluding file.data to avoid context bloat", "verify file.src starts with <field>/ after create"]
 
 permissions:
   public:

api/collections/navigation.yml

@@ -49,6 +49,14 @@ meta:
   sidebar:
     - group: settings
       label: { de: "Einstellungen", en: "Settings" }
+  agent:
+    purpose: "Header/footer trees per language, rendered by App.svelte from elements."
+    instructions: "Singletons: type header/footer x language de/en (unique type+language). elements: {name, page->content.id} internal, {name, external:true, externalUrl} external, optional hash without #. Always request lookup elements.page:content; href = localizedPath(_lookup.page.path) + hash."
+    fieldHints:
+      type: "header or footer"
+      language: "de or en"
+    examples: [{ language: "de", type: "header", elements: [{ name: "Start", page: "<content.id>" }] }]
+    hints: ["page holds content.id, resolve via _lookup.page.path", "never hardcode /de prefix in DB"]
 
 hooks:
   get:

api/collections/tag.yml

@@ -50,6 +50,11 @@ meta:
             return 'background:' + raw + ';color:' + text + ';border:1px solid ' + border
         })()
         //!js
+  agent:
+    purpose: "Managed keywords referenced by medialib.tags."
+    instructions: "No public filter hook by design (no active field); keep names short, group system/kategorie. Mutations invalidate SSR via clear_cache hooks."
+    examples: [{ name: "hero", group: "system" }]
+    hints: ["name is unique"]
 
 permissions:
   public: