@contentrain/rules 0.1.0 → 0.2.0

package/ide/cursor/rules/contentrain-content-quality.mdc

@@ -0,0 +1,299 @@
+---
+description: Content Quality — Contentrain content governance
+alwaysApply: true
+---
+
+# 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/ide/cursor/rules/contentrain-i18n-quality.mdc

@@ -0,0 +1,298 @@
+---
+description: I18n Quality — Contentrain content governance
+alwaysApply: true
+---
+
+# Internationalization (i18n) Quality Rules
+
+These rules govern translation and localization quality for all content managed through Contentrain.
+Every rule applies whenever the project has more than one locale configured.
+
+---
+
+## 1. Translation Completeness
+
+### 1.1 Coverage Requirement
+
+- Read `.contentrain/config.json` → `locales.supported` to determine the full list of supported locales.
+- EVERY entry that exists in the source locale MUST have a corresponding entry in ALL supported target locales.
+- Missing translations are deployment blockers. Treat a missing locale file as an error, not a warning.
+
+### 1.2 Dictionary Entries
+
+- Every key present in the source locale file MUST exist in every target locale file.
+- No partial dictionaries. If a new key is added, add it for ALL locales in the same operation.
+- If the agent cannot produce a quality translation, insert the source-locale text and set status to `draft` — never leave the key absent.
+
+### 1.3 Document and Singleton Entries
+
+- When creating a new document or singleton entry, create locale files for ALL supported locales.
+- The source locale file is the reference. Target locale files must contain translations of every field.
+- Required fields in the model must be populated in every locale — empty required fields are invalid.
+
+### 1.4 Completeness Verification
+
+Before committing, run this check:
+
+1. List all entry IDs in the source locale directory.
+2. For each target locale, confirm the same set of IDs exists.
+3. For each entry, confirm all required fields have non-empty values.
+4. Report any gaps as errors.
+
+---
+
+## 2. Translation Quality
+
+### 2.1 Idiomatic Translation
+
+- Translate MEANING, not words. Literal word-for-word translation produces unnatural text.
+  - EN: "It's raining cats and dogs" → TR: "Bardaktan bosanircasina yagmur yagiyor" (NOT "Kediler ve kopekler yagiyor")
+- Sentence structure must follow target language grammar, not source language grammar.
+- Read translated text aloud mentally — if it sounds unnatural, rewrite it.
+
+### 2.2 Machine Translation Artifacts
+
+Detect and fix these common machine-translation problems:
+
+- Overly literal translations that ignore idiom.
+- Incorrect gender agreement (common in Romance, Slavic, Turkic languages).
+- Wrong register/formality (e.g., using informal "du" in German business content).
+- Untranslated fragments left in source language mid-sentence.
+- Garbled word order that follows source language syntax.
+
+### 2.3 Tone Preservation
+
+- If the source content is casual, the translation must be casual in the target language.
+- If the source content is formal, the translation must use formal register.
+- Check `context.json` → `conventions.tone` — it applies to ALL locales.
+- Formality mapping varies by language:
+  - German: use "Sie" (formal) for professional content, "du" for casual.
+  - French: use "vous" (formal) by default, "tu" only if explicitly configured.
+  - Turkish: use "siz" (formal) for professional, "sen" for casual.
+  - Japanese: use desu/masu form for professional content.
+
+### 2.4 Technical Terms
+
+- Keep technical terms in their original form if no widely accepted translation exists.
+  - Keep as-is: "API", "webhook", "SSL", "DNS", "SDK", "CLI", "URL".
+  - Translate if established: "database" → "Datenbank" (de), "browser" → "navegador" (es).
+- Check `vocabulary.json` for approved translations of technical terms per locale.
+- If `vocabulary.json` specifies a translation, use it. Do not override with a different translation.
+
+### 2.5 Brand Terms
+
+- Brand terms from `vocabulary.json` → `brand_terms` must be used exactly as specified per locale.
+- Some brand terms are never translated (product names, company names).
+- Some brand terms have locale-specific variants — use the variant defined in vocabulary.
+
+---
+
+## 3. Cultural Adaptation
+
+### 3.1 Date Formats
+
+Reference the target locale convention when writing date examples or references in content:
+
+| Locale | Format | Example |
+|---|---|---|
+| en-US | MM/DD/YYYY | 03/15/2025 |
+| en-GB | DD/MM/YYYY | 15/03/2025 |
+| de, fr, tr, most EU | DD.MM.YYYY or DD/MM/YYYY | 15.03.2025 |
+| ja, zh, ko | YYYY/MM/DD or YYYY年MM月DD日 | 2025/03/15 |
+| ISO 8601 | YYYY-MM-DD | 2025-03-15 |
+
+- Do not hardcode date strings. If content references a date, use locale-appropriate formatting.
+- When in doubt, use ISO 8601 format.
+
+### 3.2 Number Formats
+
+| Convention | Thousands | Decimal | Locales |
+|---|---|---|---|
+| Period-decimal | 1,000.00 | `.` | en, ja, zh, ko |
+| Comma-decimal | 1.000,00 | `,` | de, fr, tr, es, pt, it, nl |
+| Space-thousands | 1 000,00 | `,` | fr (formal), sv, fi, pl |
+
+- Match the target locale convention when writing numbers in content.
+- Currency values: always specify the currency code (USD, EUR, TRY). Never assume currency from locale alone.
+
+### 3.3 Units of Measurement
+
+- en-US: imperial (miles, pounds, Fahrenheit) unless the context is scientific.
+- Most other locales: metric (kilometers, kilograms, Celsius).
+- Match the target locale convention. If content says "5 miles" in en-US, the de translation should say "8 km".
+
+### 3.4 Cultural Sensitivity
+
+- Food, gestures, symbols, and colors carry different meanings across cultures.
+- Do not reference culturally specific holidays as universal (e.g., "Thanksgiving" is US/Canada-specific).
+- When referencing imagery in content, ensure descriptions are culturally appropriate for the target locale.
+- Avoid idioms that do not translate — replace with locale-appropriate equivalents.
+
+---
+
+## 4. String Length Awareness
+
+### 4.1 Expansion Ratios
+
+Expect these approximate expansion ratios from English source text:
+
+| Target Language | Expansion | Notes |
+|---|---|---|
+| German | +30-40% | Compound words, longer sentences |
+| Finnish | +30-40% | Agglutinative morphology |
+| Dutch | +25-35% | Longer compound words |
+| French | +15-25% | Articles, prepositions |
+| Spanish | +15-25% | Longer verb forms |
+| Portuguese | +15-25% | Similar to Spanish |
+| Italian | +10-20% | Moderate expansion |
+| Turkish | +10-20% | Suffixation expands words |
+| Russian | +10-15% | Moderate expansion |
+| Chinese (zh) | -30-50% | Fewer characters, wider glyphs |
+| Japanese (ja) | -20-40% | Mixed scripts, compact |
+| Korean (ko) | -10-20% | Syllable blocks |
+| Arabic (ar) | -10-20% | Compact script, RTL |
+
+### 4.2 Field Constraints
+
+- Check the model's `max` field constraint for every text field.
+- The translated text MUST fit within the `max` character limit.
+- If a translation exceeds the limit, rewrite it shorter. Do NOT truncate mid-word or mid-sentence.
+- Test the longest expected language (usually German or Finnish) against all max constraints.
+
+### 4.3 UI String Considerations
+
+- Button labels, menu items, and form labels have tight space constraints.
+- German button text may need abbreviation or restructuring to fit.
+- Verify that translated UI strings do not break layout assumptions.
+
+---
+
+## 5. Dictionary Key Naming
+
+### 5.1 Naming Convention
+
+- Use semantic, hierarchical, dot-separated keys.
+  - GOOD: `auth.login.button`, `errors.404.title`, `nav.main.dashboard`
+  - BAD: `button1`, `text_3`, `label_top`, `str_47`
+- Key names are always in English regardless of locale.
+- Use lowercase with dots as separators. No spaces, no camelCase, no PascalCase in keys.
+
+### 5.2 Grouping
+
+- Group keys by feature or domain, not by page or visual position.
+  - GOOD: `auth.login.button`, `auth.login.email_label`, `auth.login.error`
+  - BAD: `login_page.top_button`, `login_page.first_input`, `login_page.red_text`
+- Top-level groups: `auth`, `nav`, `errors`, `forms`, `common`, `notifications`, `settings`.
+- Add new groups only when existing groups do not fit.
+
+### 5.3 Consistency
+
+- Similar concepts use similar key structures across features.
+  - `auth.login.button` and `auth.signup.button` — parallel structure.
+- Do not use different naming patterns for the same concept.
+- Before adding a new key, check existing keys for established patterns.
+
+---
+
+## 6. RTL Language Support
+
+### 6.1 RTL Locales
+
+Flag these locales as right-to-left:
+
+- Arabic (`ar`)
+- Hebrew (`he`)
+- Persian / Farsi (`fa`)
+- Urdu (`ur`)
+- Pashto (`ps`)
+- Sindhi (`sd`)
+
+### 6.2 Content Rules for RTL
+
+- Body text flows right-to-left. Do not force LTR markers in body content.
+- Embedded elements that remain LTR: numbers, URLs, email addresses, code snippets, brand names in Latin script.
+- Punctuation placement follows RTL rules: period at the left end of a sentence.
+- Lists and bullet points align to the right margin.
+
+### 6.3 Bidirectional Text
+
+- When RTL text contains LTR segments (e.g., a product name in English), ensure proper Unicode bidi handling.
+- Do not manually insert Unicode directional markers (LRM, RLM) in content — leave that to the rendering layer.
+- Test that mixed-direction content reads correctly in sequence.
+
+---
+
+## 7. Pluralization
+
+### 7.1 Plural Categories
+
+Languages have different plural rule counts:
+
+| Category | Languages | Plural Forms |
+|---|---|---|
+| No plurals | Chinese, Japanese, Korean, Vietnamese | 1 (`other`) |
+| Two forms | English, German, Dutch, Spanish, Italian, Portuguese, Turkish | 2 (`one`, `other`) |
+| Three forms | French, Brazilian Portuguese | 2-3 (`one`, `other`, sometimes `many`) |
+| Multiple forms | Russian, Polish, Czech, Ukrainian | 3-4 (`one`, `few`, `many`, `other`) |
+| Complex | Arabic | 6 (`zero`, `one`, `two`, `few`, `many`, `other`) |
+
+### 7.2 Dictionary Key Structure for Plurals
+
+- Use CLDR plural categories as key suffixes:
+  - `items.zero` — zero items (where applicable)
+  - `items.one` — exactly one item
+  - `items.two` — exactly two items (Arabic)
+  - `items.few` — small numbers (language-specific rules)
+  - `items.many` — large numbers (language-specific rules)
+  - `items.other` — default/fallback (REQUIRED for every plural set)
+- The `other` key is mandatory. It is the fallback for any count not covered by other categories.
+- Only include the plural categories relevant to the target language.
+  - English: `items.one`, `items.other`
+  - Arabic: all six categories
+
+### 7.3 ICU Message Format
+
+- When the project uses ICU message format, reference it correctly:
+  - `{count, plural, one {# item} other {# items}}`
+- Do not invent custom pluralization logic. Use the established format.
+
+---
+
+## 8. Vocabulary Alignment
+
+### 8.1 Cross-Locale Vocabulary
+
+- `vocabulary.json` must have entries for ALL supported locales.
+- When adding a new canonical term, provide the translation for every supported locale.
+- If a term has no natural translation, mark it as "keep original" in the vocabulary entry.
+
+### 8.2 Consistency Enforcement
+
+- Every occurrence of a canonical term in every locale must match `vocabulary.json`.
+- Run vocabulary checks across all locales, not just the source locale.
+- If a translated term appears inconsistent (e.g., "Einstellungen" in one entry and "Konfiguration" in another for "Settings"), flag it and use the vocabulary-defined term.
+
+### 8.3 Adding New Terms
+
+- Do not add new terms to `vocabulary.json` without human approval.
+- When the agent encounters a term that should be canonical but is not in the vocabulary, flag it in the commit message or review notes.
+- New terms must include: source term, translation for each locale, context/usage note.
+
+---
+
+## Validation Checklist
+
+Before committing any multilingual content, verify:
+
+- [ ] All supported locales have entries for every content item
+- [ ] All required fields are populated in every locale
+- [ ] No machine-translation artifacts (literal translations, wrong grammar)
+- [ ] Tone matches source content in all target locales
+- [ ] Technical terms follow `vocabulary.json` or are kept in original form
+- [ ] Brand terms exactly match `vocabulary.json` per locale
+- [ ] Translated text fits within field `max` constraints
+- [ ] Date, number, and currency formats match target locale
+- [ ] Dictionary keys are semantic, hierarchical, and in English
+- [ ] Plural forms use correct CLDR categories for each language
+- [ ] RTL locales are flagged and content follows RTL rules
+- [ ] Vocabulary entries exist for all terms in all supported locales