@contentrain/rules 0.1.0 → 0.2.0

package/ide/claude-code/rules/contentrain-normalize-rules.md

@@ -0,0 +1,312 @@
+# Contentrain Normalize Rules
+
+> These rules govern the normalize flow: extracting hardcoded content from source code into `.contentrain/` (Phase 1) and patching source files to reference extracted content (Phase 2).
+
+---
+
+## 1. Purpose
+
+Normalize converts a codebase with hardcoded strings into a Contentrain-managed content architecture:
+
+- **Phase 1 (Extraction):** Pull content from source code into `.contentrain/` structure. Source files are NOT modified.
+- **Phase 2 (Reuse):** Patch source files to replace hardcoded strings with content references. Requires completed extraction.
+
+Each phase produces a separate branch for independent review. This separation ensures extraction can be reviewed and merged before any source file modifications occur.
+
+---
+
+## 2. Two-Phase Architecture
+
+| Aspect | Phase 1: Extraction | Phase 2: Reuse |
+|--------|-------------------|----------------|
+| Purpose | Pull content from source to `.contentrain/` | Patch source files with content references |
+| Scope | Full project scan | Per model or per domain |
+| Source files modified | No | Yes |
+| Branch pattern | `contentrain/normalize/extract/{domain}/{timestamp}` | `contentrain/normalize/reuse/{model}/{locale}/{timestamp}` |
+| Prerequisite | Initialized `.contentrain/` | Completed extraction (content exists in `.contentrain/`) |
+| Workflow mode | Always `review` | Always `review` |
+| Standalone value | Yes -- content is manageable in Studio immediately | Depends on Phase 1 |
+
+### Why Two Phases?
+
+- Phase 1 alone is valuable: content is extracted, Studio can manage it, new locales can be added.
+- Phase 2 can be done incrementally, model by model, reducing risk.
+- Separate reviews mean clearer diffs and easier rollback.
+
+---
+
+## 3. Agent vs MCP Responsibilities
+
+### Agent (Intelligence Layer -- You)
+
+- **Decide what is content vs code.** This is a semantic judgment that requires understanding context.
+- **Assign domain grouping.** Determine which domain each piece of content belongs to.
+- **Determine model structure.** Group related content into models, choose the right kind.
+- **Create replacement expressions.** These are stack-specific and require framework knowledge:
+  - Vue/Nuxt: `{{ $t('key') }}` or `{{ t('key') }}`
+  - React/Next: `{t('key')}` or `{intl.formatMessage({id: 'key'})}`
+  - Svelte/SvelteKit: `{$t('key')}`
+  - Astro: `{t('key')}`
+  - Generic: direct import from `#contentrain`
+- **Filter false positives** from scan candidates.
+- **Evaluate and group** candidates into logical models.
+
+### MCP (Deterministic Infrastructure)
+
+- **Scan the file system** (build graph, find candidates).
+- **Read and write files** in `.contentrain/`.
+- **Patch source files** with exact string replacement (agent provides the replacement expression).
+- **Create branches, commit, validate** all changes.
+- **Enforce guardrails** (file limits, type restrictions, dry-run requirement).
+
+**Rule:** MCP is framework-agnostic. It does NOT know how `{t('key')}` differs from `{{ $t('key') }}`. The agent provides all stack-specific logic.
+
+---
+
+## 4. Guardrails
+
+These limits protect against runaway operations and ensure reviewable changes.
+
+| Guardrail | Limit | Rationale |
+|-----------|-------|-----------|
+| Allowed source file types | `.vue`, `.tsx`, `.jsx`, `.ts`, `.js`, `.mjs`, `.astro`, `.svelte` | Only scan files that can contain UI content |
+| Max files per scan | 500 | Prevent scanning entire monorepos |
+| Max files per apply | 100 | Keep diffs reviewable |
+| Dry-run before apply | **MANDATORY** | Preview all changes before executing |
+| Workflow mode | Always `review` | Normalize changes are never auto-merged |
+| Reuse scope | Per model or per domain | No whole-project reuse in one operation |
+| Reuse prerequisite | Extraction must be complete | Content must exist in `.contentrain/` before patching source |
+
+### Enforcement
+
+- Attempting to apply without a prior dry-run will be rejected.
+- Attempting to reuse without completed extraction will be rejected.
+- Exceeding file limits will truncate results with a warning.
+
+---
+
+## 5. What IS Content
+
+Use these heuristics to identify content strings in source code. Content is user-visible text that should be managed separately from code.
+
+### Extract These
+
+- **Headings and titles** in templates/JSX (`<h1>`, `<h2>`, etc.)
+- **Paragraph text** and body copy
+- **Button labels** (`<button>Submit</button>`)
+- **Link text** (`<a>Learn more</a>`)
+- **Form labels and placeholders** (`<label>`, `placeholder="..."`)
+- **Error messages** shown to users
+- **Success/notification messages**
+- **Alt text** on images (`alt="..."`)
+- **ARIA labels** (`aria-label="..."`)
+- **Meta descriptions and page titles** (`<title>`, `<meta name="description">`)
+- **Navigation items** (menu labels, breadcrumbs)
+- **Tooltip text**
+- **Empty state messages** ("No results found")
+- **CTA (call-to-action) text**
+
+### Do NOT Extract These
+
+- CSS class names, HTML IDs
+- Variable names, function names, parameter names
+- Technical identifiers (API endpoints, route paths, event names)
+- Import paths and file paths
+- Numbers used as constants (port numbers, HTTP status codes, pixel dimensions, timeouts)
+- Strings shorter than 3 characters (unless semantically meaningful: "OK", "No", "Yes")
+- Regular expressions
+- Configuration values (environment variables, feature flags)
+- Log messages (internal, not user-facing)
+- Code comments
+- Test assertion strings
+- JSON keys
+- Enum values used as code identifiers (not displayed to users)
+
+### Dictionary Interpolation Limitation
+
+Strings containing dynamic expressions (`${variable}`, template literals with runtime values) cannot be stored in dictionaries. These must remain as hardcoded expressions in source code.
+
+**CANNOT extract:**
+
+- `"Add a new entry to ${modelId}"` — contains runtime variable
+- `` `Hello, ${user.name}!` `` — template literal with variable
+
+**CAN extract:**
+
+- `"Add a new entry"` — static string (parameterize separately if needed)
+- `"Hello, World!"` — no runtime variables
+
+Agent should split parameterized strings: extract the static template pattern and leave the interpolation in code.
+
+```
+// Instead of: `"Add a new entry to ${modelId}"`
+// Extract: dictionary key "add-entry-to" = "Add a new entry to"
+// Code: `${t['add-entry-to']} ${modelId}`
+```
+
+### Edge Cases
+
+| String | Extract? | Reason |
+|--------|----------|--------|
+| `"OK"` | Yes | User-visible confirmation |
+| `"px"` | No | CSS unit, not content |
+| `"Loading..."` | Yes | User-visible state message |
+| `"GET"` | No | HTTP method, technical |
+| `"en"` | No | Locale code, technical |
+| `"Submit Form"` | Yes | User-visible button label |
+| `"/api/users"` | No | API endpoint |
+| `"flex"` | No | CSS value |
+| `"user.name"` | No | Object property path |
+| `"An error occurred"` | Yes | User-facing error message |
+
+---
+
+## 6. Phase 1: Extraction Flow
+
+### Step-by-Step
+
+1. **Build project graph:**
+   ```
+   contentrain_scan(mode: "graph")
+   ```
+   Returns import/component dependency graph. Use this to understand project structure and prioritize files.
+
+2. **Find candidates:**
+   ```
+   contentrain_scan(mode: "candidates")
+   ```
+   Returns hardcoded string candidates with file locations, line numbers, and surrounding context.
+
+3. **Agent evaluation (your job):**
+   - Filter out false positives using the heuristics in Section 5.
+   - Group candidates by domain (e.g., `marketing`, `blog`, `system`).
+   - Determine model structure: which kind (singleton, collection, dictionary), which fields.
+   - Assign field names and keys.
+
+4. **Preview extraction:**
+   ```
+   contentrain_apply(mode: "extract", dry_run: true)
+   ```
+   Returns a preview of what will be created in `.contentrain/` without making changes.
+
+5. **Review dry-run output:**
+   - Verify models are structured correctly.
+   - Verify content assignments are accurate.
+   - Check for missing or misclassified candidates.
+
+6. **Execute extraction:**
+   ```
+   contentrain_apply(mode: "extract")
+   ```
+   Creates model definitions and content files in `.contentrain/`.
+
+7. **Validate and submit:**
+   ```
+   contentrain_validate
+   contentrain_submit
+   ```
+   Submit always uses `review` mode for normalize operations.
+
+### Extraction Rules
+
+- Extraction creates content in `.contentrain/` but does NOT modify source files.
+- Each extraction produces a single branch with all extracted content.
+- Group related content into the fewest models that make semantic sense.
+- Prefer dictionary kind for UI labels and error messages.
+- Prefer singleton kind for page-specific content (hero, features).
+- Prefer collection kind for repeating items (team members, FAQs, testimonials).
+
+---
+
+## 7. Phase 2: Reuse Flow
+
+### Step-by-Step
+
+1. **Select scope:** Choose one model or domain to process.
+
+2. **Determine replacement expressions (your job):**
+   Based on the project's tech stack, determine how source files should reference content:
+
+   | Stack | Pattern | Example |
+   |-------|---------|---------|
+   | Vue/Nuxt (i18n) | `{{ $t('key') }}` | `{{ $t('hero.title') }}` |
+   | React/Next (react-intl) | `{intl.formatMessage({id: 'key'})}` | `{intl.formatMessage({id: 'hero.title'})}` |
+   | React/Next (next-intl) | `{t('key')}` | `{t('hero.title')}` |
+   | Svelte/SvelteKit | `{$t('key')}` | `{$t('hero.title')}` |
+   | Astro | `{t('key')}` | `{t('hero.title')}` |
+   | SDK import | `query('model').all()` | Direct data access via `#contentrain` |
+
+3. **Preview reuse:**
+   ```
+   contentrain_apply(mode: "reuse", scope: "model-id", dry_run: true)
+   ```
+   Returns a preview of source file patches.
+
+4. **Review dry-run output:**
+   - Verify each replacement is correct.
+   - Verify import statements will be added where needed.
+   - Check that no non-content strings are being replaced.
+
+5. **Execute reuse:**
+   ```
+   contentrain_apply(mode: "reuse", scope: "model-id")
+   ```
+   Patches source files with content references.
+
+6. **Validate and submit:**
+   ```
+   contentrain_validate
+   contentrain_submit
+   ```
+
+7. **Repeat** for each model/domain until all extracted content is referenced.
+
+### Reuse Rules
+
+- Process one model or domain at a time. Do NOT reuse the entire project in one operation.
+- Ensure the i18n/content library is properly configured in the project before reuse.
+- Add necessary imports to patched files (e.g., `import { useTranslation } from 'next-intl'`).
+- Do NOT change the structure or behavior of components -- only replace string literals with content references.
+- If a source file requires setup code (composable import, hook call), include it in the patch.
+
+---
+
+## 8. Domain and Model Grouping Guidelines
+
+When evaluating scan candidates, group content logically:
+
+### Domain Assignment
+
+| Content Location | Suggested Domain |
+|------------------|-----------------|
+| Landing page, marketing sections | `marketing` |
+| Blog, articles, posts | `blog` |
+| Navigation, footer, header | `ui` |
+| Error messages, validation | `system` |
+| Product pages, e-commerce | `product` |
+| Documentation, help | `docs` |
+| User-facing app strings | `app` |
+
+### Model Kind Selection
+
+| Content Pattern | Kind | Rationale |
+|----------------|------|-----------|
+| One set of fields per page section | `singleton` | Hero, features, pricing header |
+| Multiple items of same type | `collection` | Team members, FAQs, testimonials |
+| Long-form with metadata | `document` | Blog posts, documentation pages |
+| Key-value UI strings | `dictionary` | Error messages, button labels, form labels |
+
+---
+
+## 9. Common Mistakes to Avoid
+
+| Mistake | Correct Approach |
+|---------|-----------------|
+| Extracting CSS values as content | Only extract user-visible text |
+| Creating one model per component | Group related content into shared models |
+| Skipping dry-run | ALWAYS preview before apply |
+| Auto-merging normalize changes | Normalize ALWAYS uses review mode |
+| Reusing before extraction is merged | Wait for extraction review and merge first |
+| Processing all models in one reuse | Scope reuse to one model/domain at a time |
+| Ignoring project graph | Use graph output to understand component relationships |
+| Hardcoding replacement patterns | Detect the project's i18n stack and use its conventions |

package/ide/claude-code/rules/contentrain-schema-rules.md

@@ -0,0 +1,380 @@
+# Contentrain Schema Rules
+
+> These rules define the Contentrain type system, field definitions, model definitions, and relation system. Follow them exactly when creating or modifying models and content schemas.
+
+---
+
+## 1. Type System Overview
+
+Contentrain uses a **flat type system** with 27 types. Each type is a single keyword -- there is no `format` sub-layer. `type: "email"` is the complete specification.
+
+This design is optimized for AI agents: easy to produce, cheap to read, fast to validate.
+
+---
+
+## 2. Complete Type Reference (27 Types)
+
+### 2.1 String Family (11 types)
+
+| Type | Description | Validation | JSON Schema Export |
+|------|-------------|------------|-------------------|
+| `string` | Single-line text | -- | `{ "type": "string" }` |
+| `text` | Multi-line text | -- | `{ "type": "string" }` |
+| `email` | Email address | RFC 5321 | `{ "type": "string", "format": "email" }` |
+| `url` | URL | RFC 3986 | `{ "type": "string", "format": "uri" }` |
+| `slug` | URL-safe identifier | `/^[a-z0-9]+(?:-[a-z0-9]+)*$/` | `{ "type": "string", "pattern": "..." }` |
+| `color` | Hex color code | `/^#[0-9a-fA-F]{6}$/` | `{ "type": "string" }` |
+| `phone` | Phone number | E.164 or freeform | `{ "type": "string" }` |
+| `code` | Code snippet | -- | `{ "type": "string" }` |
+| `icon` | Icon identifier | -- | `{ "type": "string" }` |
+| `markdown` | Markdown content | -- | `{ "type": "string" }` |
+| `richtext` | HTML rich text | -- | `{ "type": "string" }` |
+
+### 2.2 Number Family (5 types)
+
+| Type | Description | Constraints | JSON Schema Export |
+|------|-------------|-------------|-------------------|
+| `number` | General number | -- | `{ "type": "number" }` |
+| `integer` | Whole number | -- | `{ "type": "integer" }` |
+| `decimal` | Decimal number | -- | `{ "type": "number" }` |
+| `percent` | Percentage | 0-100 | `{ "type": "number", "minimum": 0, "maximum": 100 }` |
+| `rating` | Rating score | 1-5 | `{ "type": "integer", "minimum": 1, "maximum": 5 }` |
+
+### 2.3 Primitives (3 types)
+
+| Type | Storage Format | JSON Schema Export |
+|------|---------------|-------------------|
+| `boolean` | `true` / `false` | `{ "type": "boolean" }` |
+| `date` | `"YYYY-MM-DD"` string | `{ "type": "string", "format": "date" }` |
+| `datetime` | ISO 8601 string | `{ "type": "string", "format": "date-time" }` |
+
+### 2.4 Media (3 types)
+
+| Type | Storage | Description |
+|------|---------|-------------|
+| `image` | Relative path (string) | Image file reference |
+| `video` | Relative path (string) | Video file reference |
+| `file` | Relative path (string) | Generic file reference |
+
+In v1, media fields store URL/path strings only. Upload and processing are out of scope.
+
+### 2.5 Relations (2 types)
+
+| Type | Cardinality | Storage |
+|------|-------------|---------|
+| `relation` | One-to-one | `"entry-id"` (string) |
+| `relations` | One-to-many | `["id-1", "id-2"]` (string array) |
+
+### 2.6 Structural (3 types)
+
+| Type | Description | Requires |
+|------|-------------|----------|
+| `select` | Fixed options, pick one | `options` property |
+| `array` | Ordered list of items | `items` property |
+| `object` | Nested key-value structure | `fields` property |
+
+---
+
+## 3. Field Definition
+
+A field definition describes one field in a model. Include only the properties that apply -- omit all defaults.
+
+```json
+{
+  "type": "string",
+  "required": true,
+  "min": 3,
+  "max": 100,
+  "unique": true,
+  "description": "Page title"
+}
+```
+
+### 3.1 Field Properties
+
+| Property | Applicable Types | Description |
+|----------|-----------------|-------------|
+| `type` | ALL | **Required.** One of the 27 types. |
+| `required` | ALL | Mark field as mandatory. Default: `false`. Omit if `false`. |
+| `unique` | `string`, `email`, `slug`, `integer` | Enforce uniqueness within model. Default: `false`. Omit if `false`. |
+| `default` | ALL | Default value. Omit if `null`. |
+| `min` | string/text: char count; numbers: value; array: element count | Minimum constraint. |
+| `max` | Same as `min` | Maximum constraint. |
+| `pattern` | `string`, `text`, `code` | Regex validation pattern. |
+| `options` | `select` ONLY | Fixed choices: `["draft", "published", "archived"]` |
+| `model` | `relation`, `relations` ONLY | Target model ID. String or string array for polymorphic. |
+| `items` | `array` ONLY | Element type: `"string"` or `{ "type": "object", "fields": {...} }` |
+| `fields` | `object` ONLY | Nested field definitions. |
+| `accept` | `image`, `video`, `file` | Allowed MIME types: `"image/png,image/jpeg"` |
+| `maxSize` | `image`, `video`, `file` | Maximum file size in bytes. |
+| `description` | ALL | Human-readable hint (shown in Studio UI tooltip, used as agent context). |
+
+### 3.2 Omission Rules
+
+These rules produce minimal, clean schema definitions:
+
+- If `required` is `false` (the default), do NOT include it.
+- If `unique` is `false` (the default), do NOT include it.
+- If `default` is `null`, do NOT include it.
+- Only include properties that add information. Fewer properties = fewer tokens = faster agent processing.
+
+---
+
+## 4. Model Definition
+
+Model definitions live at `.contentrain/models/{model-id}.json`. One file per model.
+
+```json
+{
+  "id": "blog-post",
+  "name": "Blog Post",
+  "kind": "document",
+  "domain": "blog",
+  "i18n": true,
+  "description": "Blog articles with markdown body",
+  "fields": {
+    "title": { "type": "string", "required": true, "max": 120 },
+    "slug": { "type": "slug", "required": true, "unique": true },
+    "author": { "type": "relation", "model": "team-members", "required": true },
+    "tags": { "type": "array", "items": "string" }
+  }
+}
+```
+
+### 4.1 Model Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | Yes | Unique identifier, **kebab-case**. |
+| `name` | `string` | Yes | Human-readable display name. |
+| `kind` | `string` | Yes | One of: `singleton`, `collection`, `document`, `dictionary`. |
+| `domain` | `string` | Yes | Organizational group (maps to content subdirectory). |
+| `i18n` | `boolean` | Yes | Whether the model supports multiple locales. |
+| `description` | `string` | No | Model description for documentation and agent context. |
+| `fields` | `object` | Yes (except dictionary) | Field definitions. Dictionary kind has NO fields. |
+| `content_path` | `string` | No | Framework-relative path for content files (e.g., `"content/blog"`, `"locales"`). When set, content is written here instead of `.contentrain/content/`. |
+| `locale_strategy` | `string` | No | How locale is encoded in file names: `"file"` (default), `"suffix"`, `"directory"`, `"none"`. |
+
+### 4.2 System Fields
+
+Do NOT define these in the schema. The platform manages them automatically:
+
+| Field | Kind | Source |
+|-------|------|--------|
+| `id` | Collection | 12-char hex, used as object-map key |
+| `slug` | Document | Directory name in content path |
+| `createdAt` / `updatedAt` | All | Derived from Git commit history (not stored) |
+| `status`, `source`, `updated_by`, `approved_by` | All | Stored in `.contentrain/meta/` |
+
+---
+
+### 4.3 Locale Strategy Rules
+
+The `locale_strategy` property controls how locale is encoded in file paths:
+
+| Strategy | i18n:true JSON path | i18n:true Document path | i18n:false path |
+|----------|---------------------|------------------------|-----------------|
+| `file` (default) | `{dir}/{locale}.json` | `{dir}/{slug}/{locale}.md` | `{dir}/data.json` |
+| `suffix` | `{dir}/{model}.{locale}.json` | `{dir}/{slug}.{locale}.md` | `{dir}/data.json` |
+| `directory` | `{dir}/{locale}/{model}.json` | `{dir}/{locale}/{slug}.md` | `{dir}/data.json` |
+| `none` | **INVALID** (requires i18n:false) | **INVALID** | `{dir}/{model}.json` or `{dir}/{slug}.md` |
+
+- `locale_strategy: "none"` requires `i18n: false`. The "none" strategy stores a single file without locale encoding.
+- When `content_path` is set, `{dir}` is the content_path. Otherwise `{dir}` is `.contentrain/content/{domain}/{model-id}`.
+
+---
+
+## 5. The Four Model Kinds
+
+### 5.1 Singleton
+
+**One instance per locale.** Use for page sections, site config, navigation.
+
+| Aspect | Detail |
+|--------|--------|
+| Storage | JSON object (one file per locale) |
+| File path | `content/{domain}/{model-id}/{locale}.json` |
+| `i18n: false` path | `content/{domain}/{model-id}/data.json` |
+| ID management | None (single instance) |
+| Relation target | Cannot be referenced by relations |
+
+```json
+{
+  "cta": "Get Started",
+  "title": "Build faster"
+}
+```
+
+### 5.2 Collection
+
+**Multiple entries.** Use for team members, products, FAQs, categories.
+
+| Aspect | Detail |
+|--------|--------|
+| Storage | JSON object-map (entry ID as key, sorted lexicographically) |
+| File path | `content/{domain}/{model-id}/{locale}.json` |
+| Tool output | Array with `id` injected |
+| ID management | Auto-generated 12-char hex |
+| Relation target | Referenced by entry `id` |
+
+```json
+{
+  "a1b2c3d4e5f6": { "name": "Ahmet", "role": "CEO" },
+  "f6e5d4c3b2a1": { "name": "Jane", "role": "CTO" }
+}
+```
+
+### 5.3 Document
+
+**Markdown with frontmatter.** Use for blog posts, documentation, changelogs.
+
+| Aspect | Detail |
+|--------|--------|
+| Storage | `.md` file with YAML frontmatter |
+| File path | `content/{domain}/{model-id}/{slug}/{locale}.md` |
+| `i18n: false` path | `content/{domain}/{model-id}/{slug}.md` |
+| ID management | `slug` field (URL-safe, unique) |
+| Relation target | Referenced by `slug` |
+
+```markdown
+---
+title: Getting Started
+slug: getting-started
+author: a1b2c3d4e5f6
+---
+# Getting Started with Contentrain
+```
+
+### 5.4 Dictionary
+
+**Flat key-value pairs.** Use for error messages, UI strings, translations.
+
+| Aspect | Detail |
+|--------|--------|
+| Storage | Flat JSON object (key-value, all values are strings) |
+| File path | `content/{domain}/{model-id}/{locale}.json` |
+| Fields definition | None -- dictionary models have NO `fields` property |
+| ID management | Key is identity |
+| Relation target | Cannot be referenced by relations |
+
+```json
+{
+  "auth.expired": "Session expired",
+  "auth.failed": "Authentication failed"
+}
+```
+
+---
+
+## 6. Relation Rules
+
+### 6.1 Basic Relations
+
+```json
+"author": { "type": "relation", "model": "team-members", "required": true }
+"categories": { "type": "relations", "model": "categories" }
+```
+
+- `relation` (1:1): Value is a single string -- an entry ID or slug.
+- `relations` (1:many): Value is a string array of entry IDs or slugs.
+
+### 6.2 Target Model Restrictions
+
+| Target Kind | Reference Key | Can Be Target? |
+|-------------|--------------|----------------|
+| Collection | Entry `id` | Yes |
+| Document | Document `slug` | Yes |
+| Singleton | -- | No |
+| Dictionary | -- | No |
+
+### 6.3 Polymorphic Relations
+
+When a field can reference multiple model types:
+
+```json
+"target": { "type": "relation", "model": ["blog-post", "page"] }
+```
+
+Storage for polymorphic references uses a compound value:
+
+```json
+{ "model": "blog-post", "ref": "getting-started" }
+```
+
+### 6.4 Self-Referencing
+
+Models can reference themselves (e.g., hierarchical categories):
+
+```json
+"parent": { "type": "relation", "model": "categories" }
+```
+
+### 6.5 Resolution Rules
+
+- Relations are resolved **1 level deep** -- no recursive resolution.
+- **Unresolved IDs** (target entry does not exist) are kept as raw strings (graceful degradation).
+- **Cascade deletion does not exist.** Deleting a referenced entry produces a broken relation warning.
+- **Array order is preserved** for `relations` type.
+- **IDs/slugs are locale-agnostic.** The same reference works across all locales.
+
+### 6.6 Validation
+
+- Referenced ID/slug MUST exist in the target model.
+- `model` property MUST reference an existing model ID.
+- Referential integrity is checked by `contentrain_validate`.
+- Deleting a model that is referenced by other models is BLOCKED.
+
+---
+
+## 7. Nesting Limits
+
+### 7.1 Object Type
+
+```json
+"address": {
+  "type": "object",
+  "fields": {
+    "city": { "type": "string", "required": true },
+    "street": { "type": "string", "required": true },
+    "zip": { "type": "string" }
+  }
+}
+```
+
+### 7.2 Array of Objects
+
+```json
+"variants": {
+  "type": "array",
+  "items": {
+    "type": "object",
+    "fields": {
+      "color": { "type": "color", "required": true },
+      "price": { "type": "decimal", "required": true },
+      "size": { "type": "select", "options": ["S", "M", "L"] }
+    }
+  },
+  "max": 50
+}
+```
+
+### 7.3 Depth Limit
+
+**Maximum nesting depth: 2 levels.** An object inside an object is allowed. An object inside an object inside an object is NOT.
+
+- Prefer flat types over deeply nested structures.
+- Use relations to model complex data relationships instead of nesting.
+- If you need deeper nesting, create a separate model and use a `relation` field.
+
+---
+
+## 8. Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Model ID | kebab-case | `blog-post`, `team-members` |
+| Field key | snake_case | `hero_image`, `cta_url` |
+| Domain | lowercase, single word or kebab-case | `blog`, `marketing`, `system` |
+| Dictionary key | dot-notation | `auth.failed`, `validation.required` |
+| Slug | lowercase, kebab-case | `getting-started` |
+| Locale | ISO 639-1 | `en`, `tr`, `de` |