@contentrain/skills 0.1.2 → 0.2.1

package/skills/contentrain-quality/references/accessibility.md

@@ -0,0 +1,160 @@
+---
+name: accessibility
+description: "Accessibility rules for content: alt text, ARIA, color contrast, reading level"
+---
+
+# Accessibility Rules
+
+These rules are MANDATORY for all AI agents creating or editing content in Contentrain projects.
+Violations will be flagged during validation. No exceptions unless explicitly overridden by `context.json` configuration.
+
+---
+
+## Image Accessibility
+
+1. Every `image` type field MUST have a corresponding alt text value. If the model defines an `image_alt` field, populate it. If not, include alt text guidance in the image field's `description` metadata.
+
+2. Alt text MUST describe the image's **content and function**, not its appearance.
+   - GOOD: `"CEO Jane Doe speaking at the 2024 product launch"`
+   - BAD: `"A photo with blue tones and a person on stage"`
+
+3. Decorative images (visual separators, background textures) MUST have alt text set to an empty string `""`. Never leave alt text undefined or null -- explicitly set it to `""`.
+
+4. Complex images (charts, infographics, diagrams) MUST have a short alt text summarizing the conclusion, plus a detailed description in an adjacent text field or in the body content.
+   - Example alt: `"Bar chart showing Q3 revenue grew 22% year-over-year"`
+   - Example adjacent text: full data table or written summary
+
+5. Alt text MUST NOT exceed **125 characters**. Screen readers may truncate longer text.
+
+6. Icon images used as interactive elements MUST have alt text describing the **action**, not the icon.
+   - GOOD: `"Search"`, `"Close menu"`, `"Open settings"`
+   - BAD: `"Magnifying glass icon"`, `"X icon"`
+
+7. Do not begin alt text with "Image of" or "Photo of" -- the screen reader already announces it as an image.
+
+---
+
+## Language & Readability
+
+1. Target a **grade 8-10 reading level** (Flesch-Kincaid) for general content.
+
+2. Target **grade 6-8** for public-facing critical content: legal notices, safety information, error messages, onboarding flows.
+
+3. Use plain language. Prefer common words over formal synonyms:
+   - "use" not "utilize"
+   - "start" not "commence"
+   - "help" not "facilitate"
+   - "buy" not "purchase"
+   - "end" not "terminate"
+
+4. Define every acronym and abbreviation on first use: `"Content Management System (CMS)"`. After the first definition, use the acronym freely.
+
+5. Do not use jargon unless the content targets a technical audience. Check `context.json > tone` to determine the audience. When `tone` is `"technical"`, domain-specific terms are acceptable without definitions.
+
+6. Keep sentences short: **15-20 words average**. Break long sentences at natural clause boundaries.
+
+7. Keep paragraphs short: **3-5 sentences maximum**. Use line breaks between paragraphs.
+
+8. Use active voice. Passive voice is acceptable only when the actor is unknown or irrelevant.
+   - GOOD: `"The system saves your changes automatically."`
+   - BAD: `"Your changes are saved automatically by the system."`
+
+---
+
+## Link Text
+
+1. Link text MUST be descriptive and self-explanatory. It must make sense **out of context** because screen readers present links in an isolated list.
+   - GOOD: `"Download the 2024 Annual Report"`
+   - BAD: `"Click here"`
+
+2. NEVER use these as standalone link text: `"click here"`, `"read more"`, `"learn more"`, `"here"`, `"link"`, `"this"`.
+
+3. For file downloads, include the file type and size in the link text:
+   - `"Download the Q3 Budget (PDF, 2.4 MB)"`
+
+4. Do not use the raw URL as link text unless the content is specifically listing URLs.
+
+5. Keep link text concise -- describe the destination or action in 2-8 words.
+
+---
+
+## Heading Semantics
+
+1. Headings MUST describe the content of their section. Never use headings purely for visual styling (font size, bold).
+
+2. Heading levels MUST reflect **document hierarchy**:
+   - `h2` for top-level sections within the page
+   - `h3` for subsections of an `h2`
+   - `h4` for subsections of an `h3`
+   - Never skip levels (e.g., `h2` directly to `h4`)
+
+3. Every distinct content section SHOULD have a heading.
+
+4. Headings MUST NOT be empty or contain only whitespace.
+
+5. Do not duplicate heading text within the same page unless sections are genuinely distinct (e.g., "Overview" under two different parent headings is acceptable).
+
+---
+
+## Content Structure
+
+1. Use **semantic markup** appropriate to the content type:
+   - Unordered lists (`ul`) for items without sequence
+   - Ordered lists (`ol`) for steps or ranked items
+   - Headings for section titles
+   - Paragraphs for body text
+   - Blockquotes for quoted material
+
+2. Tables MUST include a header row or header column. Keep table structure simple -- avoid merged cells and nested tables.
+
+3. Provide a text alternative for every piece of non-text content (images, charts, embedded media).
+
+4. Sequential content (steps, instructions, timelines) MUST follow logical reading order. Do not rely on CSS or layout to reorder content.
+
+5. Lists MUST have at least two items. A single-item list should be rewritten as a paragraph or inline text.
+
+---
+
+## Color & Visual References
+
+1. NEVER use color alone to convey meaning.
+   - BAD: `"Required fields are highlighted in red."`
+   - GOOD: `"Required fields are marked with an asterisk (*)."`
+
+2. Do not reference visual position in content text.
+   - BAD: `"Click the button on the right."`
+   - GOOD: `"Click the Submit button."`
+
+3. Ensure all text content is meaningful without any visual context. Content must be understandable when read aloud or rendered in plain text.
+
+---
+
+## Error Messages & Forms
+
+1. Error messages MUST identify **which field** has the error.
+
+2. Error messages MUST describe **what the error is** and how to fix it.
+   - GOOD: `"Enter a valid email address (e.g., name@example.com)."`
+   - BAD: `"Invalid input."`
+
+3. Use **positive framing** -- tell the user what to do, not what they did wrong.
+   - GOOD: `"Enter a date in YYYY-MM-DD format."`
+   - BAD: `"Wrong date format."`
+
+4. Group related form fields with descriptive labels. Every input field MUST have a label.
+
+5. Do not use placeholder text as a substitute for labels.
+
+---
+
+## Multimedia
+
+1. Video content MUST reference a transcript -- either as inline content, a URL, or a relation to a document entry.
+
+2. Audio content MUST have a text transcript available.
+
+3. If content auto-plays, note this in metadata so the frontend can provide pause/stop controls. Auto-playing media with audio is strongly discouraged.
+
+4. Time-based media (video, audio, animations) MUST include duration information when the model supports it.
+
+5. Animated content (GIFs, auto-playing videos) should be flagged if longer than 5 seconds -- provide a mechanism to pause.

package/skills/contentrain-quality/references/content-quality.md

@@ -0,0 +1,299 @@
+---
+name: content-quality
+description: "Detailed content writing rules: structure, tone, content type patterns, lifecycle"
+---
+
+# Content Quality Rules
+
+These rules govern how AI agents create and edit content in Contentrain projects.
+Every rule is mandatory. Violations must be fixed before committing.
+
+---
+
+## 1. Writing Structure
+
+### 1.1 Heading Hierarchy
+
+- Use exactly ONE H1 per page. The H1 is the page/entry title.
+- Follow sequential order: H1 -> H2 -> H3 -> H4 -> H5 -> H6.
+- NEVER skip levels. An H4 must be preceded by an H3 in the same section.
+- Do not use headings for visual styling. A heading implies a content section.
+
+### 1.2 Titles
+
+- Length: 50-60 characters. Measure before committing.
+- Place the primary keyword within the first 30 characters.
+- Use action-oriented phrasing: "Build a REST API" not "REST API Overview".
+- No clickbait: "You Won't Believe..." is forbidden.
+- No ALL CAPS titles. Use sentence case or title case per project convention.
+- Every title must be unique within its collection.
+
+### 1.3 Excerpts and Descriptions
+
+- Length: 120-160 characters. Must be a complete sentence.
+- Summarize the VALUE the reader gets, not the process of writing.
+  - GOOD: "Learn how to deploy a Node.js app to production in under 5 minutes."
+  - BAD: "This article discusses deployment."
+- End with a period. No trailing ellipsis.
+- Must differ from the title -- do not repeat the title verbatim.
+
+### 1.4 Body Content
+
+- Prefer active voice. Passive voice is acceptable only when the actor is unknown or irrelevant.
+- Target reading grade 8-10 (Flesch-Kincaid). Avoid unnecessarily complex sentences.
+- Paragraphs: 3-5 sentences each. Break longer paragraphs.
+- Use transition sentences between sections to maintain flow.
+- Front-load key information -- most important point first in each paragraph.
+- One idea per paragraph. Do not combine unrelated points.
+
+### 1.5 Lists
+
+- Use parallel grammatical structure across all items.
+  - GOOD: "Install dependencies", "Configure the server", "Run the tests"
+  - BAD: "Install dependencies", "Server configuration", "You should run tests"
+- Punctuation: if items are complete sentences, end each with a period. If fragments, no terminal punctuation. Be consistent within a single list.
+- Ordered lists for sequential steps. Unordered lists for non-sequential items.
+- Minimum 2 items in any list. A single-item list is not a list.
+
+### 1.6 No Placeholder Text
+
+Reject and replace any of the following immediately:
+
+- "Lorem ipsum" or any Latin filler text
+- "TODO", "TBD", "FIXME", "XXX" in content fields
+- "[insert here]", "[your text]", "[placeholder]"
+- "Sample text", "Example content", "Test entry"
+- Empty strings in required fields
+
+If the agent cannot produce real content, it must leave the entry in `draft` status and flag the field explicitly. Never commit placeholder text.
+
+### 1.7 No Duplicate Content
+
+- The same text block must not appear in multiple entries within a collection.
+- Titles must be unique across all entries in the same collection.
+- Descriptions/excerpts must be unique across all entries in the same collection.
+- If content is shared across entries, extract it to a referenced entry and use a `relation` field.
+- Before writing, query existing entries to confirm no duplication.
+
+---
+
+## 2. Tone and Voice
+
+### 2.1 Project Tone Configuration
+
+- Read `.contentrain/context.json` -> `conventions.tone` before writing any content.
+- If the field exists, match the specified tone exactly.
+- If `context.json` does not exist or `conventions.tone` is absent, default to **neutral professional** tone.
+- Never override or ignore the configured tone.
+
+### 2.2 Vocabulary Compliance
+
+- Read `.contentrain/vocabulary.json` before writing content.
+- Use canonical terms exactly as defined. Never invent synonyms for canonical terms.
+  - If vocabulary defines "Sign up", do not write "Register", "Create account", or "Join".
+- Respect `brand_terms`: use exact casing and spacing as defined.
+  - If brand defines "GitHub", never write "Github", "github", or "GH".
+- Respect `forbidden_terms`: never use any term on this list.
+- If `vocabulary.json` does not exist, proceed without term constraints but maintain internal consistency -- pick one term and use it everywhere.
+
+### 2.3 Content Type Voice Mapping
+
+Match voice to content type:
+
+| Content Type | Voice | Characteristics |
+|---|---|---|
+| Marketing / Landing pages | Persuasive | Benefit-focused, confident, action-oriented, second person ("you") |
+| Documentation / Guides | Instructional | Step-by-step, precise, imperative mood ("Run the command"), third person for concepts |
+| Error messages | Empathetic | Solution-oriented, no blame, explain what happened and what to do next |
+| UI labels | Concise | Consistent terminology, sentence case, no articles unless needed for clarity |
+| Blog posts | Conversational-professional | Engaging, informative, first person plural ("we") acceptable |
+| Changelogs | Factual | Past tense, specific, version-referenced, no marketing language |
+
+### 2.4 Consistency Within an Entry
+
+- Do not shift tone mid-entry. If the opening is formal, maintain formality throughout.
+- Do not mix second person ("you") and third person ("the user") within the same entry.
+- Maintain consistent use of contractions: either use them throughout or not at all per project tone.
+
+---
+
+## 3. Content Type Patterns
+
+### 3.1 Blog Post (document kind)
+
+Required structure:
+
+1. **Hook opening** (1-2 sentences): State the problem, ask a question, or present a surprising fact.
+2. **Context** (1 paragraph): Why this topic matters now.
+3. **Scannable body**: Use H2/H3 subheadings every 2-4 paragraphs. Each section is self-contained.
+4. **Conclusion** (1 paragraph): Summarize key takeaways.
+5. **Call-to-action**: Direct the reader to a next step (related post, product, signup).
+
+Do not start with "In this article, we will discuss..." -- start with value.
+
+### 3.2 Landing Page (singleton kind)
+
+Required sections in order:
+
+1. **Hero statement**: One sentence, max 10 words. State the core value proposition.
+2. **Problem**: 2-3 sentences describing the pain point.
+3. **Solution**: How the product/service solves it. Benefit-focused, not feature-focused.
+4. **Features**: 3-6 features, each with a heading and 1-2 sentence description.
+5. **Social proof**: Testimonials, logos, statistics. Must reference real data.
+6. **CTA**: Clear, single action. Use action verbs: "Start free trial", "Get started", "Book a demo".
+
+### 3.3 Documentation (document kind)
+
+Required structure:
+
+1. **Prerequisites callout**: List what the reader needs before starting (tools, accounts, knowledge).
+2. **Overview** (1-2 sentences): What the reader will accomplish.
+3. **Step-by-step instructions**: Numbered steps, one action per step, code blocks where applicable.
+4. **Expected result**: What the reader should see/have after completing the steps.
+5. **Troubleshooting**: Common errors and their solutions. Minimum 2 items.
+
+Use imperative mood: "Run the command" not "You should run the command".
+
+### 3.4 Error Messages (dictionary kind)
+
+Structure each error message with three parts:
+
+1. **What happened**: State the error clearly. "Your session has expired."
+2. **Why**: Brief explanation. "Sessions expire after 30 minutes of inactivity."
+3. **How to fix**: Actionable next step. "Sign in again to continue."
+
+Rules:
+- No blame language: "Invalid input" not "You entered invalid input".
+- No technical jargon in user-facing errors.
+- No naked error codes: always pair codes with human-readable text.
+
+### 3.5 Form Labels (dictionary kind)
+
+- Use noun or noun phrase: "Email address", "Password", "Company name".
+- Sentence case consistently: "Email address" not "Email Address".
+- No colons at the end of labels.
+- Helper text: one sentence explaining what to enter or format requirements.
+- Consistent phrasing across all forms in the project.
+
+### 3.6 Navigation Items (dictionary kind)
+
+- 1-2 words maximum.
+- Use verbs for actions: "Sign in", "Download", "Contact".
+- Use nouns for destinations: "Dashboard", "Settings", "Pricing".
+- No abbreviations unless universally understood.
+- Consistent capitalization: match the project convention.
+
+### 3.7 Notifications (dictionary kind)
+
+- Start with what happened: "Your file has been uploaded."
+- Include timestamp context when relevant: "2 minutes ago".
+- End with next action if applicable: "View file" or "Dismiss".
+- Keep under 100 characters for mobile readability.
+
+---
+
+## 4. Content Lifecycle
+
+### 4.1 Draft Status
+
+- Focus on completeness over polish.
+- ALL required fields must have real values -- no placeholders.
+- Optional fields may be empty but should be populated when possible.
+- Drafts do not need final copy-editing but must be factually correct.
+- Flag any fields the agent could not confidently populate.
+
+### 4.2 Review Status
+
+- Vocabulary compliance: every term matches `vocabulary.json`.
+- Tone consistency: matches `context.json` -> `conventions.tone` throughout.
+- Factual accuracy: all claims, statistics, and references are verifiable.
+- Cross-locale coverage: if entry exists in source locale, all target locales must have corresponding entries.
+- Field constraint compliance: all values within min/max length, pattern, and type constraints.
+
+### 4.3 Published Status
+
+ALL of the following must be true:
+
+- Every required field is populated with final content.
+- Every supported locale has a complete translation.
+- Zero placeholder text anywhere in the entry.
+- All relation fields reference existing, published entries.
+- SEO fields (title, description, slug) are populated and valid.
+- Content passes tone and vocabulary checks.
+
+### 4.4 Archive Criteria
+
+Move content to archived status when:
+
+- It references deprecated features, APIs, or products.
+- Dates or events referenced are more than 12 months past.
+- The content has been superseded by a newer entry.
+- Statistics or data points are outdated and cannot be updated.
+
+Never delete content. Archive it. Deletion is a manual human decision.
+
+---
+
+## 5. Contentrain-Specific Rules
+
+### 5.1 System-Managed Fields
+
+NEVER write to these fields -- they are managed by the system:
+
+- `id` -- auto-generated unique identifier
+- `createdAt` -- set on creation
+- `updatedAt` -- set on every save
+- `status` -- managed through workflow transitions
+- `order` -- managed through UI reordering
+
+If a write payload includes any system field, remove it before saving.
+
+### 5.2 Metadata Directory
+
+- NEVER write to `.contentrain/meta/` -- all metadata files are system-managed.
+- NEVER modify `.contentrain/models/` directly -- use MCP tools.
+- Read these directories for context, but treat them as read-only.
+
+### 5.3 Vocabulary Usage
+
+- Load `vocabulary.json` at the start of every content operation.
+- Cross-reference every noun, verb, and technical term against the vocabulary.
+- If a term is not in the vocabulary but should be, flag it for human review -- do not add it.
+- Vocabulary applies across ALL entries, ALL collections, ALL locales.
+
+### 5.4 Model Field Constraints
+
+Before writing any field value:
+
+1. Read the model definition from `.contentrain/models/`.
+2. Check `required` -- required fields must have non-empty values.
+3. Check `min` / `max` -- string length must be within bounds.
+4. Check `pattern` -- value must match regex if defined.
+5. Check `unique` -- value must not duplicate any existing entry in the collection.
+6. Check `options` -- if the field is an enum/select, value must be from the defined list.
+
+Constraint violations must be fixed before saving. Never save invalid data.
+
+### 5.5 Collection Entry Consistency
+
+- All entries within a collection must follow the same structural pattern.
+- If existing entries use a specific content structure (e.g., all blog posts start with a hook), new entries must follow the same pattern.
+- Before creating a new entry, read 2-3 existing entries to understand the established pattern.
+- If no existing entries exist, follow the content type pattern defined in Section 3.
+
+---
+
+## Validation Checklist
+
+Before committing any content, verify:
+
+- [ ] Heading hierarchy is sequential (H1 -> H2 -> H3, no skips)
+- [ ] Title is 50-60 characters, keyword-rich, unique
+- [ ] Description is 120-160 characters, complete sentence, unique
+- [ ] No placeholder text anywhere
+- [ ] No duplicate content across entries
+- [ ] Tone matches `context.json` configuration
+- [ ] All terms match `vocabulary.json`
+- [ ] All field constraints (length, pattern, required) are satisfied
+- [ ] Content follows the correct content type pattern
+- [ ] System fields are not included in write payload

package/skills/contentrain-quality/references/media.md

@@ -0,0 +1,170 @@
+---
+name: media
+description: "Media asset rules: image optimization, video handling, file naming conventions"
+---
+
+# Media Rules
+
+These rules are MANDATORY for all AI agents creating or editing content in Contentrain projects.
+Follow these guidelines when populating image, video, or file fields in any content model.
+
+---
+
+## Image Dimensions (Recommended)
+
+1. Use these standard dimensions unless the project's `context.json` specifies overrides:
+
+   | Purpose | Width | Height | Aspect Ratio |
+   |---|---|---|---|
+   | Hero / Banner | 1200px | 630px | ~1.91:1 |
+   | Thumbnail / Card | 400px | 300px | 4:3 |
+   | Avatar / Profile | 200px | 200px | 1:1 (square) |
+   | Icon | 64px or 128px | 64px or 128px | 1:1 (square) |
+   | Full-width content | 1200px | proportional | varies |
+   | Social share (og:image) | 1200px | 630px | 1.91:1 |
+
+2. Hero/banner dimensions (1200x630) double as optimal `og:image` dimensions for social sharing.
+
+3. All images MUST be usable at mobile widths. Minimum renderable width: **320px**. Do not provide images narrower than this.
+
+4. When a model defines `width` and `height` fields alongside an image field, populate them with the actual image dimensions to prevent layout shift.
+
+---
+
+## File Formats
+
+1. **WebP** is the preferred format for all web images. Use it as the default unless a specific reason requires another format.
+
+2. **PNG**: use only when transparency is required and SVG is not suitable.
+
+3. **JPEG/JPG**: acceptable for photographs when WebP is not available. Use quality 75-85 for a good compression/quality balance.
+
+4. **SVG**: REQUIRED for logos, icons, and any vector graphics. Do not rasterize vector content.
+
+5. **AVIF**: acceptable as a progressive enhancement for browsers that support it. Always provide a WebP or JPEG fallback.
+
+6. **GIF**: do NOT use for animations. Use MP4 video instead for better compression and performance. Static GIFs are acceptable but WebP is preferred.
+
+7. **Never use** these formats for web content: BMP, TIFF, RAW, PSD, AI, EPS. Convert to a web-safe format before storing.
+
+---
+
+## File Size Limits
+
+1. Enforce these maximum file sizes:
+
+   | Asset Type | Max Size |
+   |---|---|
+   | Hero / Banner image | 200 KB |
+   | Thumbnail | 50 KB |
+   | Avatar / Icon | 30 KB |
+   | Content image | 150 KB |
+   | SVG file | 50 KB |
+   | Video poster image | 100 KB |
+
+2. **Total images per page**: aim for under **1 MB combined**. Flag content entries that reference more than 1 MB of images.
+
+3. If an image exceeds the size limit, instruct the user to compress or resize it before storing. Do not silently accept oversized files.
+
+4. SVG files SHOULD be optimized (e.g., with SVGO) to remove editor metadata, comments, and unnecessary attributes.
+
+---
+
+## File Naming Convention
+
+1. Use **kebab-case** for all media file names: lowercase, words separated by hyphens.
+
+2. File names MUST be **descriptive** — include context and subject:
+   - GOOD: `homepage-hero-banner.webp`, `blog-author-jane-doe.jpg`, `product-dashboard-preview.webp`
+   - BAD: `IMG_4523.jpg`, `photo1.png`, `untitled.webp`, `Screenshot 2024-01-15.png`, `image.jpg`
+
+3. When providing multiple sizes of the same image, include dimensions in the filename:
+   - `hero-1200x630.webp`, `hero-600x315.webp`
+   - Or use size suffixes: `hero-lg.webp`, `hero-md.webp`, `hero-sm.webp`
+
+4. Allowed characters in file names: lowercase letters (`a-z`), digits (`0-9`), hyphens (`-`), and a single dot before the extension. No spaces, underscores, or special characters.
+
+5. File extensions MUST be lowercase: `.webp` not `.WebP`, `.jpg` not `.JPG`.
+
+---
+
+## Alt Text Pairing
+
+1. Every content model with an `image` field SHOULD define a companion `image_alt` field (type: `string`). If the model does not have one, request that it be added.
+
+2. When both `image` and `image_alt` fields exist, ALWAYS populate both. Never leave `image_alt` empty unless the image is decorative (set to `""`).
+
+3. If no dedicated alt text field exists, include alt text guidance in the image field's `description` metadata so future content editors know to provide it.
+
+4. In document/markdown models, always use the full image syntax with alt text: `![descriptive alt text](path/to/image.webp)`. Never use `![](path)`.
+
+5. See `accessibility-rules.md` for detailed alt text writing guidelines.
+
+---
+
+## Video Guidelines
+
+1. **Format**: MP4 with H.264 codec for maximum browser compatibility. WebM (VP9) is acceptable as a secondary format.
+
+2. Every video MUST have a **poster/thumbnail image**. If the model has a `poster` or `thumbnail` field, populate it. The poster image follows the same format and size rules as other images.
+
+3. If the model defines a `duration` field, populate it in seconds (integer). This helps the frontend display duration badges and improves accessibility.
+
+4. Every video MUST reference a transcript or caption:
+   - A `transcript_url` field pointing to a text/VTT file
+   - A relation to a document entry containing the transcript
+   - Or inline transcript in an adjacent richtext/markdown field
+
+5. **Max file size** for self-hosted embedded video: **50 MB**. For larger videos, use external hosting.
+
+6. Prefer **external hosting** (YouTube, Vimeo, or CDN) for videos over 50 MB. Store the external URL in a `url` type field, not the video binary.
+
+7. Do not auto-play videos with audio. If the model has an `autoplay` field, set it to `false` by default.
+
+---
+
+## Asset Organization
+
+1. All media MUST be stored under the path defined in `config.json > assets_path`. The default is `.contentrain/assets/`.
+
+2. Organize assets using ONE of these conventions per project (check existing structure first):
+
+   **By domain:**
+   ```
+   assets/blog/
+   assets/team/
+   assets/products/
+   assets/marketing/
+   ```
+
+   **By type:**
+   ```
+   assets/images/
+   assets/videos/
+   assets/documents/
+   ```
+
+3. Check the existing asset directory structure before adding new files. Follow the established convention. Do not mix conventions within a project.
+
+4. Reference all media with **relative paths from the project root**:
+   - GOOD: `.contentrain/assets/blog/post-hero.webp`
+   - BAD: `/Users/jane/project/.contentrain/assets/blog/post-hero.webp`
+
+5. Do not create deeply nested directories (max 3 levels under `assets/`). Deep nesting makes paths fragile and hard to manage.
+
+---
+
+## Responsive Images
+
+1. When the content model supports multiple image sizes, provide variants for:
+   - **Small** (mobile): 320-768px wide
+   - **Medium** (tablet): 768-1024px wide
+   - **Large** (desktop): 1024px+ wide
+
+2. Use descriptive size suffixes in filenames: `-sm`, `-md`, `-lg` or explicit dimensions (`-400w`, `-800w`, `-1200w`).
+
+3. Always provide at least the **largest size**. Smaller sizes are recommended but optional — CDN or image optimization services can generate them from the original.
+
+4. If the model has a single `image` field (no responsive variants), provide the largest recommended size. The frontend is responsible for responsive rendering.
+
+5. Store the original/largest image. Never store only a downscaled version — you lose the ability to generate other sizes later.