@contentrain/skills 0.1.1 → 0.2.0

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.

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

@@ -0,0 +1,229 @@
+---
+name: seo
+description: "SEO optimization rules for content fields, meta tags, and structured data"
+---
+
+# SEO Rules
+
+These rules govern search engine optimization for all content managed through Contentrain.
+Apply these rules to every content entry that produces a public-facing page.
+
+---
+
+## 1. Page Titles
+
+### 1.1 Length and Format
+
+- Length: 50-60 characters including spaces. Google truncates titles beyond ~60 characters.
+- Measure character count before saving. Truncated titles harm click-through rates.
+- No ALL CAPS titles. Use sentence case or title case per project convention.
+- No excessive punctuation: no `!!!`, no `???`, no `...` in titles.
+- No emoji in titles unless explicitly configured in `context.json`.
+
+### 1.2 Keyword Placement
+
+- Place the primary keyword within the first 30 characters.
+- Structure: `Primary Keyword Phrase | Brand Name` or `Primary Keyword Phrase -- Brand Name`.
+- Acceptable separators: ` | `, ` -- `, ` - `. Pick one and use it consistently across all entries.
+- The keyword must read naturally -- no keyword stuffing.
+  - GOOD: "Deploy Node.js to Production | Acme Docs"
+  - BAD: "Node.js Deploy Node Production Deployment | Acme"
+
+### 1.3 Uniqueness
+
+- Every entry in a collection MUST have a unique title.
+- Before saving, query existing entries and confirm no title collision.
+- Titles across collections should also be unique when they produce public pages.
+
+---
+
+## 2. Meta Descriptions
+
+### 2.1 Length and Format
+
+- Length: 120-155 characters including spaces.
+- Must be a complete sentence or two short sentences.
+- End with a period.
+- No keyword stuffing -- write for humans, not crawlers.
+
+### 2.2 Content Requirements
+
+- Include a clear value proposition or call-to-action.
+  - GOOD: "Learn how to set up CI/CD for your Node.js project in 10 minutes. Step-by-step guide with examples."
+  - BAD: "CI/CD Node.js setup guide tutorial deployment continuous integration."
+- Must differ from the page title -- do not repeat the title as the description.
+- Must be unique per entry. No two entries may share the same meta description.
+
+### 2.3 What to Avoid
+
+- No quotes or special characters that break HTML meta tags: avoid `"`, `<`, `>`.
+- No "Click here to learn more" -- search engines ignore generic CTAs.
+- No date references that will become stale (prefer "latest" over "2024").
+
+---
+
+## 3. Slugs
+
+### 3.1 Format
+
+- Lowercase only. No uppercase characters.
+- Words separated by hyphens (`-`). No underscores, no spaces, no dots.
+- No special characters: only `a-z`, `0-9`, and `-`.
+- No consecutive hyphens (`--`). No leading or trailing hyphens.
+
+### 3.2 Length and Content
+
+- Optimal: 3-5 words.
+- Maximum: 60 characters.
+- Remove stop words (`the`, `a`, `an`, `is`, `of`, `and`, `or`, `in`, `to`) unless removing them changes meaning.
+  - "how-to-deploy-node" -> "deploy-node" is acceptable.
+  - "state-of-the-art" -> keep as-is because meaning changes if shortened.
+
+### 3.3 Stability
+
+- NEVER change a slug on a published entry. Changing slugs breaks existing links, bookmarks, and search engine indexing.
+- If a slug must change, the human must set up a redirect. The agent must not change published slugs without explicit human instruction.
+- Draft entries may have their slugs changed freely before first publication.
+
+### 3.4 Locale Consistency
+
+- Use the same slug value across all locales for the same entry.
+- Do NOT translate slugs. Slugs are identifiers, not content.
+- Example: the slug `deploy-node` remains `deploy-node` in `en`, `tr`, `de`, and all other locales.
+
+---
+
+## 4. Heading Structure
+
+### 4.1 H1 Rule
+
+- Exactly one H1 per page. The H1 is the entry title or the primary heading.
+- The H1 should contain the primary keyword naturally.
+- Do not duplicate the H1 text elsewhere on the page.
+
+### 4.2 Subheading Keywords
+
+- Include relevant keywords in H2 and H3 headings where natural.
+- Do not force keywords into every heading. Clarity takes priority over keyword density.
+- Use question-format headings for FAQ-style content: "How do I reset my password?"
+
+### 4.3 Hierarchy Reflects Content
+
+- Heading levels must reflect the logical structure of the content.
+- Do not use H3 because it renders smaller -- use CSS for styling, headings for structure.
+- Every heading must have content beneath it. No empty sections.
+- Do not place two headings consecutively without content between them.
+
+---
+
+## 5. Images and Alt Text
+
+### 5.1 Alt Text Requirements
+
+- Every `image` field that displays on a public page MUST have corresponding alt text.
+- Describe the image content and its context: "Dashboard showing monthly revenue chart with 15% growth indicator."
+- Maximum length: 125 characters.
+- Do not start with "Image of", "Photo of", "Picture of" -- describe directly.
+
+### 5.2 Decorative Images
+
+- If an image is purely decorative (visual separator, background pattern), set alt text to an empty string (`""`).
+- Do not omit the alt field entirely -- explicitly set it to empty.
+
+### 5.3 Keywords in Alt Text
+
+- Include relevant keywords naturally when they describe the image.
+- Do not stuff keywords: "Node.js Node deployment Node server Node production" is forbidden.
+- The alt text must accurately describe what is in the image.
+
+### 5.4 Image File Names
+
+- When the agent controls the image file name, use descriptive, hyphenated names.
+  - GOOD: `revenue-dashboard-chart.png`
+  - BAD: `IMG_2847.png`, `screenshot.png`, `image1.png`
+
+---
+
+## 6. Open Graph and Social Media
+
+### 6.1 Open Graph Tags
+
+When OG fields exist in the model, populate them:
+
+| Field | Max Length | Requirement |
+|---|---|---|
+| `og:title` | 60 characters | Concise version of the page title |
+| `og:description` | 200 characters | Slightly longer than meta description, conversational |
+| `og:image` | -- | 1200x630 pixels recommended, must be absolute URL |
+| `og:type` | -- | `article` for blog/docs, `website` for landing pages |
+
+### 6.2 Twitter Card
+
+- Use `summary_large_image` for content with strong visual elements.
+- Use `summary` for text-focused content.
+- Twitter title and description may differ from OG -- optimize for each platform.
+
+### 6.3 Fallback
+
+- If OG-specific fields are absent, the system uses the standard title and description.
+- Ensure the standard title and description are suitable for social sharing.
+
+---
+
+## 7. Internal Linking
+
+### 7.1 Relation Fields
+
+- Use Contentrain `relation` and `relations` model fields for cross-references between entries.
+- Prefer structured relations over hardcoded links in body content.
+- Structured relations are maintainable -- if a slug changes, relations still resolve.
+
+### 7.2 Bidirectional Relations
+
+- When Entry A references Entry B, check if Entry B should reference Entry A.
+- Example: if a blog post links to a product, the product's "related articles" should include that blog post.
+- The agent should suggest bidirectional relations but not create them without confirmation.
+
+### 7.3 Manual Links in Body Content
+
+- If the model does not have relation fields and links must be in body text, use relative paths.
+- Verify that linked entries exist before saving.
+- Do not link to draft or archived entries from published content.
+
+---
+
+## 8. URL and Canonical Rules
+
+### 8.1 Slug Patterns
+
+- All entries in a collection must follow the same slug pattern.
+- If existing entries use `verb-noun` format (e.g., `deploy-app`, `configure-server`), new entries must follow the same pattern.
+- Check existing entries before generating a slug for a new entry.
+
+### 8.2 Multi-Locale URLs
+
+- Same slug across all locales (see Section 3.4).
+- Locale prefix is handled by the frontend routing, not by the content slug.
+- Example: `/en/deploy-node` and `/tr/deploy-node` share the slug `deploy-node`.
+
+### 8.3 Trailing Slashes
+
+- The agent does not control trailing slash behavior -- this is a frontend routing concern.
+- Ensure slug values do not include leading or trailing slashes.
+
+---
+
+## Validation Checklist
+
+Before committing any content with SEO impact, verify:
+
+- [ ] Title is 50-60 characters, primary keyword near start, unique
+- [ ] Meta description is 120-155 characters, complete sentence, unique
+- [ ] Slug is lowercase, hyphenated, 3-5 words, no special characters
+- [ ] Published slugs have not been changed
+- [ ] Slugs are identical across all locales for the same entry
+- [ ] One H1 per page, sequential heading hierarchy
+- [ ] All images have descriptive alt text (max 125 chars) or empty string for decorative
+- [ ] OG fields populated if model supports them
+- [ ] Relation fields used for internal cross-references
+- [ ] No keyword stuffing in titles, descriptions, headings, or alt text