@contentrain/rules 0.3.2 → 0.4.0

package/shared/content-conventions.md

@@ -0,0 +1,314 @@
+# Contentrain Content Conventions
+
+> These rules govern how content is structured, stored, and serialized in the `.contentrain/` directory. Follow them exactly when creating or modifying content through MCP tools.
+
+---
+
+## 1. Directory Structure
+
+All Contentrain data lives under the `.contentrain/` directory at the project root. Understand every subdirectory's purpose before reading or writing.
+
+```
+.contentrain/
+  config.json               # Project configuration (stack, workflow, locales, domains)
+  vocabulary.json            # Canonical terms for consistent terminology
+  context.json               # Project intelligence — committed with content changes, agents READ ONLY
+  assets.json                # Media asset registry
+  models/
+    {model-id}.json          # Model definitions (one file per model)
+  content/
+    {domain}/
+      {model-id}/
+        en.json              # Content per locale (i18n: true)
+        tr.json
+        data.json            # Content without locale (i18n: false)
+        {slug}/              # Document kind only
+          en.md
+          tr.md
+  meta/
+    {model-id}/
+      {locale}.json          # System-managed metadata
+      {slug}/                # Document kind only
+        {locale}.json
+  client/                    # SDK generated client — auto-generated, NEVER edit
+  assets/                    # Media files (images, videos, documents)
+```
+
+### Critical Boundaries
+
+- **NEVER write to `.contentrain/meta/`** -- metadata is system-managed (status, source, updated_by, approved_by).
+- **NEVER edit `.contentrain/client/`** -- this is auto-generated by `contentrain generate`.
+- **NEVER edit `.contentrain/context.json`** -- MCP writes it; agents read it for project intelligence.
+- **ALWAYS use MCP tools** to create/update content and models. Do not write JSON files directly.
+
+---
+
+## 2. config.json Structure
+
+The project configuration file controls global behavior. It is created by `contentrain_init`.
+
+```json
+{
+  "version": 1,
+  "stack": "nuxt",
+  "workflow": "auto-merge",
+  "repository": {
+    "provider": "github",
+    "owner": "contentrain",
+    "name": "demo",
+    "default_branch": "main"
+  },
+  "locales": {
+    "default": "en",
+    "supported": ["en", "tr"]
+  },
+  "domains": ["blog", "marketing", "system"],
+  "assets_path": ".contentrain/assets",
+  "branchRetention": 30
+}
+```
+
+### Field Reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | `number` | Config schema version. Always `1`. |
+| `stack` | `string` | Detected or set framework: `"nuxt"`, `"next"`, `"astro"`, `"sveltekit"`, `"react"`, `"node"` |
+| `workflow` | `string` | `"auto-merge"` (solo dev) or `"review"` (team governance) |
+| `repository` | `object` | Git remote info. Provider is always `"github"` in v1. |
+| `locales.default` | `string` | Primary locale (ISO 639-1) |
+| `locales.supported` | `string[]` | All locales including default |
+| `domains` | `string[]` | Organizational groups for content (e.g., `"blog"`, `"marketing"`, `"system"`) |
+| `assets_path` | `string` | Path for media files |
+| `branchRetention` | `number` | Days to keep merged branches |
+
+---
+
+## 3. Content File Formats by Model Kind
+
+Each of the 4 model kinds has a distinct storage format. Know them precisely.
+
+### 3.1 Singleton
+
+One JSON object per locale file. No `id` field.
+
+**Path:** `.contentrain/content/{domain}/{model-id}/{locale}.json`
+
+```json
+{
+  "cta": "Get Started",
+  "subtitle": "The modern content platform",
+  "title": "Build faster"
+}
+```
+
+**Use for:** Hero sections, navigation, site config, form labels -- anything with exactly one instance per locale.
+
+### 3.2 Collection
+
+Object-map on disk: keys are entry IDs, sorted lexicographically. The `id` field is the key itself and is NOT stored inside the entry object.
+
+**Path:** `.contentrain/content/{domain}/{model-id}/{locale}.json`
+
+```json
+{
+  "a1b2c3d4e5f6": {
+    "avatar": "assets/ahmet.jpg",
+    "name": "Ahmet",
+    "role": "CEO"
+  },
+  "f6e5d4c3b2a1": {
+    "avatar": "assets/jane.jpg",
+    "name": "Jane",
+    "role": "CTO"
+  }
+}
+```
+
+**MCP output format differs from storage:** MCP tools return collections as arrays with `id` injected:
+
+```json
+[
+  { "id": "a1b2c3d4e5f6", "name": "Ahmet", "role": "CEO", "avatar": "assets/ahmet.jpg" },
+  { "id": "f6e5d4c3b2a1", "name": "Jane", "role": "CTO", "avatar": "assets/jane.jpg" }
+]
+```
+
+**Why object-map?**
+- Sorted keys produce predictable diffs and minimize Git merge conflicts.
+- No ID duplication -- key IS the ID.
+- Consistent structure with metadata files.
+
+### 3.3 Document
+
+Markdown file with YAML-like frontmatter. One file per slug per locale.
+
+**Path:** `.contentrain/content/{domain}/{model-id}/{slug}/{locale}.md`
+
+```markdown
+---
+title: Getting Started
+slug: getting-started
+author: a1b2c3d4e5f6
+tags: [tutorial, intro]
+---
+# Getting Started with Contentrain
+
+Your markdown body content here...
+```
+
+**Use for:** Blog posts, documentation pages, changelogs -- long-form content with typed metadata.
+
+### 3.4 Dictionary
+
+Flat key-value JSON per locale. No `fields` in the model definition -- all values are strings.
+
+**Path:** `.contentrain/content/{domain}/{model-id}/{locale}.json`
+
+```json
+{
+  "auth.expired": "Session expired",
+  "auth.failed": "Authentication failed",
+  "validation.required": "{field} is required"
+}
+```
+
+**Use for:** Error messages, UI strings, i18n translation files, mobile app strings.
+
+---
+
+## 4. Canonical Serialization Rules
+
+ALL JSON files in `.contentrain/` MUST follow these rules for deterministic, git-friendly output:
+
+1. **Keys sorted lexicographically** within every object (including nested objects).
+2. **2-space indent** for all nesting levels.
+3. **UTF-8 encoding** without BOM.
+4. **Trailing newline** at end of file (single `\n` after closing brace/bracket).
+5. **Omit null values** -- do not write `"field": null`.
+6. **Omit default values** -- if `required` is `false`, do not include it. If `default` is `null`, do not include it.
+7. **Field key order in content entries** follows the model definition insertion order for readability, but storage uses lexicographic sort for determinism.
+
+### Why This Matters
+
+- Deterministic output means identical data always produces identical files.
+- Sorted keys prevent artificial Git diffs from key reordering.
+- Clean diffs enable meaningful code review of content changes.
+
+---
+
+## 5. System Fields
+
+Several fields are managed by the platform. Agents MUST NOT set or modify them.
+
+| Field | Where | Managed By |
+|-------|-------|------------|
+| `id` | Collection entry key | Auto-generated 12-char hex UUID |
+| `slug` | Document directory name | Derived from content or set by agent via `slug` field |
+| `createdAt` | Not stored | Derived from Git commit history |
+| `updatedAt` | Not stored | Derived from Git commit history |
+| `status` | `.contentrain/meta/` | Platform workflow engine |
+| `source` | `.contentrain/meta/` | Set by MCP: `"agent"`, `"human"`, or `"import"` |
+| `updated_by` | `.contentrain/meta/` | Set by MCP: agent name or user email |
+| `approved_by` | `.contentrain/meta/` | Set by Studio on review approval |
+
+**Rule:** When creating content via `contentrain_content_save`, provide only the content fields defined in the model. Do not include `id`, `createdAt`, `updatedAt`, `status`, or any metadata fields.
+
+---
+
+## 6. Localization Rules
+
+| Rule | Detail |
+|------|--------|
+| `i18n: true` on model | Each locale gets its own file: `en.json`, `tr.json`, etc. |
+| `i18n: false` on model | Single file: `data.json` (or `{slug}.md` for documents) |
+| Locale code | ISO 639-1: `en`, `tr`, `de`, `fr`, `ja`, `ar` |
+| ID/slug are locale-agnostic | The same entry ID or document slug is used across all locales |
+| Entry parity (collections) | All locales MUST have the same set of entry IDs |
+| Key parity (dictionaries) | All locales MUST have the same set of keys |
+
+### Validation Checks
+
+| Check | Severity | Example |
+|-------|----------|---------|
+| Missing locale file | Error | `hero: tr.json missing` |
+| Collection entry ID mismatch | Error | `team-members: entry "member-2" missing in tr` |
+| Dictionary key missing | Warning | `error-messages: tr missing 5 keys` |
+| Document missing translation | Warning | `blog-post: "getting-started" has no tr translation` |
+
+---
+
+## 7. Vocabulary
+
+The `vocabulary.json` file provides canonical terms for consistent content.
+
+```json
+{
+  "version": 1,
+  "terms": {
+    "email": { "en": "Email", "tr": "E-posta" },
+    "sign-up": { "en": "Sign Up", "tr": "Kayit Ol" }
+  }
+}
+```
+
+### Rules
+
+- **Check vocabulary FIRST** before writing any content. Use existing terms when they match.
+- **Add new terms** to the vocabulary when creating content with reusable terminology.
+- **Term keys** are kebab-case identifiers.
+- **Each term** maps to locale-specific approved strings.
+- Vocabulary ensures consistency across models, locales, and agent sessions.
+
+---
+
+## 8. context.json
+
+MCP writes `context.json` after every write operation. It provides project intelligence for agents and Studio synchronization.
+
+```json
+{
+  "version": "1.0",
+  "lastOperation": {
+    "tool": "content_save",
+    "model": "blog-post",
+    "locale": "en",
+    "entries": ["a1b2c3d4e5f6"],
+    "timestamp": "2026-03-11T14:30:00Z",
+    "source": "mcp-local"
+  },
+  "stats": {
+    "models": 5,
+    "entries": 142,
+    "locales": ["en", "tr"],
+    "lastSync": "2026-03-11T14:30:00Z"
+  }
+}
+```
+
+### Rules
+
+- **Read only** -- agents MUST NOT write to this file.
+- **Use it for awareness** -- check last operation, entry counts, locale coverage.
+- `source` values: `"mcp-local"` (IDE), `"mcp-studio"` (Studio server-side), `"studio-ui"` (Studio direct).
+- Updated only on write operations (not reads).
+- Git-tracked within `.contentrain/`.
+
+---
+
+## 9. Assets
+
+Media files are stored in the configured `assets_path`. The `assets.json` file tracks registered assets.
+
+```json
+[
+  { "path": "assets/hero.webp", "type": "image/webp", "size": 245680, "alt": "Hero background" }
+]
+```
+
+### Rules for Media References
+
+- Use relative paths from the `.contentrain/` root in content fields.
+- Media field types (`image`, `video`, `file`) store string path references.
+- In v1, media fields are URL/path strings only. Upload and processing are out of scope.
+- Always provide `alt` text for images when the information is available.

package/shared/content-quality.md

@@ -0,0 +1,294 @@
+# 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