@contentrain/rules 0.1.0 → 0.3.0

package/shared/normalize-rules.md

@@ -1,312 +0,0 @@
-# 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/shared/schema-rules.md

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