@contentrain/rules 0.1.0 → 0.2.0

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

@@ -0,0 +1,141 @@
+# Security Rules
+
+These rules are MANDATORY for all AI agents creating or editing content in Contentrain projects.
+Content that violates these rules MUST be rejected. These rules protect against XSS, data leaks, and injection attacks.
+
+---
+
+## XSS Prevention in Content
+
+1. `richtext` and `markdown` fields MUST NOT contain any of the following:
+   - `<script>` or `</script>` tags
+   - `javascript:` protocol in any attribute value
+   - Event handler attributes: `onerror`, `onload`, `onclick`, `onmouseover`, `onfocus`, `onblur`, `onsubmit`, `onchange`, `onkeydown`, `onkeyup`, `onkeypress`, `ondblclick`, `onmousedown`, `onmouseup`, `onmousemove`, `onmouseout`, `oncontextmenu`, `ondrag`, `ondrop`, `onpaste`, `oninput`
+   - `<iframe>`, `<embed>`, `<object>`, `<applet>`, `<form>`, `<input>`, `<textarea>`, `<select>`, `<button>` tags
+   - `data:` URIs containing executable content (e.g., `data:text/html`, `data:application/javascript`)
+   - CSS expressions: `expression()`, `url(javascript:)`, `-moz-binding`
+   - `<base>` tag (can redirect all relative URLs)
+   - `<meta>` tag with `http-equiv="refresh"`
+   - `<svg>` with embedded scripts or event handlers
+
+2. **Allowed HTML tags** in richtext fields:
+   ```
+   p, strong, em, a, ul, ol, li, h2, h3, h4, h5, h6,
+   blockquote, code, pre, img, br, hr,
+   table, thead, tbody, tr, th, td,
+   del, ins, sup, sub, abbr, mark, details, summary
+   ```
+   Any tag not on this list MUST be stripped or rejected.
+
+3. **Allowed attributes on `<a>` tags**: `href`, `title`, `target`.
+   - `href` MUST use `http://`, `https://`, or `mailto:` protocol only.
+   - `target` MUST be `_blank` or `_self` only.
+   - When `target="_blank"`, the frontend should add `rel="noopener noreferrer"` — but the content itself must not rely on this.
+
+4. **Allowed attributes on `<img>` tags**: `src`, `alt`, `width`, `height`.
+   - `src` MUST use `https://`, `http://`, or a relative path starting with `/` or `./`.
+   - No `data:` URIs for `src` in production content.
+
+5. Strip or reject all other HTML attributes not explicitly allowed above.
+
+---
+
+## Secret Detection
+
+1. NEVER include any of the following in ANY content field:
+   - **API keys**: patterns matching `sk-`, `pk_`, `sk_live_`, `sk_test_`, `api_key=`, `apiKey:`, `x-api-key`
+   - **Access tokens**: JWT tokens (`eyJ...`), Bearer tokens, OAuth tokens, session tokens
+   - **Passwords or credentials**: any field value resembling `password=`, `passwd:`, `secret=`
+   - **Private keys**: `-----BEGIN RSA PRIVATE KEY-----`, `-----BEGIN OPENSSH PRIVATE KEY-----`, `-----BEGIN PGP PRIVATE KEY BLOCK-----`, or similar PEM blocks
+   - **Database connection strings**: `mongodb://`, `postgres://`, `mysql://`, `redis://` with credentials
+   - **Cloud credentials**: AWS (`AKIA...`), GCP (`AIza...`), Azure storage keys
+   - **Webhook URLs with tokens**: URLs containing `token=`, `secret=`, or `/hooks/` with embedded credentials
+
+2. If a field value matches any secret pattern, **reject the value** and warn the user: `"This value appears to contain a secret or credential. Secrets must not be stored in content fields."`
+
+3. Environment-specific values (API endpoints, service IDs) SHOULD use placeholder references (e.g., `{{API_URL}}`) or be stored in environment configuration, not hardcoded in content.
+
+---
+
+## PII Handling
+
+1. **Flag** when email addresses appear in fields that are not typed as `email`. The agent should warn: `"Email address detected in a non-email field. Confirm this is intentional."`
+
+2. **Flag** when phone numbers appear in fields that are not typed as `phone`.
+
+3. **Flag** physical addresses, government ID numbers (SSN, national ID), and dates of birth when they appear in generic `string` or `richtext` fields.
+
+4. User-generated content fields SHOULD be marked for frontend sanitization in the model metadata.
+
+5. NEVER store authentication credentials (usernames, passwords, tokens) in content fields.
+
+---
+
+## URL Validation
+
+1. All URLs in `url` type fields MUST use `https://` protocol.
+   - **Exception**: `http://localhost` and `http://127.0.0.1` URLs are allowed for development references.
+
+2. Reject URLs containing path traversal sequences: `../`, `..\\`, `%2e%2e/`, `%2e%2e%5c`.
+
+3. URLs MUST have a valid format: protocol + domain + valid TLD. Reject malformed URLs.
+
+4. Do not use IP-based URLs in production content. Use domain names.
+   - **Exception**: private/internal documentation that explicitly references infrastructure IPs.
+
+5. Reject `file://` protocol URLs. Content must never reference local filesystem paths as URLs.
+
+6. Reject `ftp://` protocol URLs unless the content model explicitly documents FTP support.
+
+---
+
+## File & Media Security
+
+1. Media paths MUST be relative to the `assets_path` defined in `config.json`. Never use absolute filesystem paths.
+
+2. Reject any file path containing:
+   - Absolute system paths: `/etc/`, `/usr/`, `/var/`, `C:\\`, `C:/`, `/Users/`, `/home/`
+   - Path traversal: `../`, `..\\`, `%2e%2e`
+
+3. Validate file extensions match the field type:
+   - `image` fields: `.webp`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.avif`
+   - `video` fields: `.mp4`, `.webm`, `.ogg`
+   - `file` fields: any extension, but **flag executables** and warn the user: `.exe`, `.sh`, `.bat`, `.cmd`, `.ps1`, `.msi`, `.dmg`, `.app`, `.jar`, `.dll`, `.so`
+
+4. File names MUST NOT contain spaces or special characters. Only alphanumeric characters, hyphens (`-`), underscores (`_`), and dots (`.`) are allowed.
+
+5. Reject files with double extensions that disguise executables: `report.pdf.exe`, `image.jpg.sh`.
+
+---
+
+## Content Injection
+
+1. Values in `object` and `array` type fields MUST be valid JSON. Reject values with:
+   - Trailing commas
+   - JavaScript comments (`//`, `/* */`)
+   - Unquoted keys
+   - Single-quoted strings
+   - Executable code patterns (function declarations, `eval()`, `require()`, `import()`)
+
+2. `code` type fields are displayed as code and never executed, but still apply these rules:
+   - No embedded secrets (see Secret Detection above)
+   - Content is stored as-is — no sanitization needed beyond secret detection
+
+3. Template literals and interpolation patterns (`${...}`, `{{...}}`, `{%...%}`) in content fields MUST be intentional. Flag unexpected template syntax in plain text fields.
+
+---
+
+## Markdown-Specific
+
+1. Fenced code blocks (`` ``` ``) are rendered as code, not executed. They are safe from an execution standpoint but still subject to secret detection rules.
+
+2. Raw HTML embedded in markdown MUST follow the same XSS rules as richtext fields. Apply the allowed-tags whitelist.
+
+3. Link destinations in markdown (`[text](url)`) MUST use `http://`, `https://`, or `mailto:` protocol only. Reject `javascript:`, `data:`, `vbscript:`, and `file:` protocols.
+
+4. Image sources in markdown (`![alt](src)`) MUST use valid paths:
+   - No path traversal (`../`)
+   - Valid image extensions (`.webp`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.avif`)
+   - `https://` for external images, relative paths for local images
+
+5. Do not allow HTML comments (`<!-- -->`) to hide content in markdown — they may be rendered in some parsers and can be used to smuggle payloads.

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

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

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

@@ -0,0 +1,262 @@
+# Contentrain Workflow Rules
+
+> These rules govern how content changes flow through the Git-based workflow, including branching, validation, review, and status management.
+
+---
+
+## 1. Two Workflow Modes
+
+Contentrain supports two workflow modes, configured in `.contentrain/config.json` under the `workflow` field.
+
+### 1.1 auto-merge
+
+```json
+{ "workflow": "auto-merge" }
+```
+
+- Branch is created, changes are committed, branch is **automatically merged to main**.
+- No review step -- changes go live immediately.
+- Best for: solo developers, rapid iteration, prototyping, vibe coding.
+- Status flow: `draft` --> `published` (skips `in_review`).
+
+### 1.2 review
+
+```json
+{ "workflow": "review" }
+```
+
+- Branch is created, changes are committed, branch is **pushed to remote**.
+- Studio or team reviews the changes before merging.
+- Best for: teams, content governance, production environments.
+- Status flow: `draft` --> `in_review` --> `published` | `rejected`.
+
+### 1.3 Mode Selection Rules
+
+- Default is `auto-merge` -- minimal friction for getting started.
+- Switch to `review` as the project or team grows and governance becomes important.
+- **Normalize operations ALWAYS use `review` mode** regardless of the config setting. Normalize changes are never auto-merged.
+
+---
+
+## 2. Branch Naming Convention
+
+All Contentrain branches follow a strict naming pattern:
+
+```
+contentrain/{operation}/{model}/{locale}/{timestamp}
+```
+
+### Examples
+
+| Scenario | Branch Name |
+|----------|-------------|
+| Content update | `contentrain/content/blog-post/en/1710300000` |
+| Model creation | `contentrain/model/team-member/1710300000` |
+| Normalize extraction | `contentrain/normalize/extract/blog/1710300000` |
+| Normalize reuse | `contentrain/normalize/reuse/marketing-hero/en/1710300000` |
+| Scaffold | `contentrain/new/scaffold-landing/en/1710300000` |
+
+### Rules
+
+- Branches are created automatically by MCP tools. Do NOT create them manually.
+- The `{timestamp}` component ensures uniqueness.
+- `{locale}` is included when the operation is locale-specific.
+- `{model}` is included when the operation targets a specific model.
+
+---
+
+## 3. Git Workflow
+
+### 3.1 Worktree-Based Transactions
+
+Every write operation follows this flow:
+
+1. MCP creates a **Git worktree** on a new branch.
+2. Changes are made in the worktree (content files, model files).
+3. Changes are committed to the branch.
+4. **auto-merge mode:** Branch is merged to main. Worktree is cleaned up.
+5. **review mode:** Branch is pushed to remote. Worktree is cleaned up. Studio notifies reviewers.
+
+### 3.2 Critical Rules
+
+- **NEVER commit directly to main.** All changes go through branches.
+- **NEVER create branches manually.** MCP tools handle all Git operations.
+- **NEVER force-push or rebase** Contentrain branches.
+- Worktrees are temporary. They are created for the operation and cleaned up afterward.
+- Each branch contains a cohesive set of changes (e.g., all entries for one model update).
+
+### 3.3 Branch Lifecycle
+
+```
+Created (worktree) --> Committed --> Merged/Pushed --> Cleaned up
+                                         |
+                                         v
+                            auto-merge: merged to main
+                            review: pushed to remote, awaiting review
+```
+
+Merged branches are retained for `branchRetention` days (default: 30) for audit trail, then pruned.
+
+### 3.4 Branch Health
+
+MCP enforces branch health limits to prevent branch accumulation:
+
+- **50+ active branches**: Warning. Operations continue but the user is alerted.
+- **80+ active branches**: Blocked. No new write operations until branches are merged or deleted.
+- `contentrain_status` reports branch health automatically (total, merged, unmerged counts).
+- Merged branches are cleaned up lazily during status checks and submit operations.
+
+---
+
+## 4. Conflict Resolution
+
+### 4.1 How Conflicts Are Minimized
+
+Contentrain's storage format is designed to minimize Git merge conflicts:
+
+- **Object-map storage** for collections: each entry is a separate key-value pair. Two branches adding different entries rarely conflict.
+- **Canonical serialization**: sorted keys and deterministic formatting prevent artificial diffs.
+- **Review mode for normalize**: separate branches for extraction and reuse reduce concurrent editing conflicts.
+
+### 4.2 When Conflicts Occur
+
+| Scenario | Likelihood | Resolution |
+|----------|-----------|------------|
+| Different fields on the same entry | Low | Auto-merge succeeds (JSON field-level merge) |
+| Same field changed by two branches | Medium | Studio conflict resolution UI |
+| Two entries added with adjacent IDs | Very low | Auto-merge usually succeeds |
+| Concurrent normalize operations | Avoided | Always review mode, sequential per model |
+
+### 4.3 Conflict Resolution Rules
+
+- Field-level merge for JSON: if the same entry has different fields changed in two branches, Git auto-merges.
+- Same field changed by multiple branches creates a conflict requiring Studio resolution.
+- When a conflict occurs, the agent should NOT attempt to resolve it. Inform the user and direct them to Studio.
+- Collection object-map format with sorted keys means ~0.3% chance of conflict for two new entries in a 350-entry collection.
+
+---
+
+## 5. Workflow States
+
+Content entries move through these states:
+
+```
+draft --> in_review --> published
+              |
+              v
+          rejected (with feedback)
+
+published --> archived
+```
+
+### 5.1 State Definitions
+
+| State | Git State | Trigger |
+|-------|-----------|---------|
+| `draft` | Branch exists, not yet reviewed/merged | Content created or updated |
+| `in_review` | PR/branch open, labeled `contentrain-content` | `contentrain_submit` in review mode |
+| `published` | Content is on main branch | Auto-merge, or PR merged after review |
+| `rejected` | PR closed without merge | Studio reviewer rejects changes |
+| `archived` | Metadata-only state | Manual action -- content hidden but retained |
+
+### 5.2 State Rules
+
+- **State is tracked in `.contentrain/meta/`, NOT in content files.** Agents never read or write state directly.
+- **auto-merge mode:** `draft` --> `published` (no `in_review` step).
+- **review mode:** `draft` --> `in_review` --> `published` or `rejected`.
+- **Git is the source of truth.** States are derived from Git state (branch existence, merge status, PR status).
+- Rejected content includes reviewer feedback. The agent can address feedback and resubmit.
+
+---
+
+## 6. Validation Rules
+
+### 6.1 When to Validate
+
+- ALWAYS call `contentrain_validate` before `contentrain_submit`.
+- `contentrain_submit` will fail if validation errors exist.
+- Run validation after completing all changes in a batch, not after every individual save.
+
+### 6.2 What Validation Checks
+
+| Check | Severity | Description |
+|-------|----------|-------------|
+| Schema compliance | Error | Field values match their type definitions |
+| Required fields | Error | All `required: true` fields have values |
+| Unique constraints | Error | `unique: true` fields have no duplicates within the model |
+| Locale completeness | Error/Warning | All supported locales have corresponding files and entries |
+| Referential integrity | Error | Relation targets (IDs/slugs) exist in the target model |
+| Canonical format | Warning | Files follow canonical serialization rules |
+| Vocabulary usage | Warning | Content uses vocabulary terms when available |
+
+### 6.3 Handling Validation Results
+
+- **Errors:** MUST be fixed before submitting. Fix the content and re-validate.
+- **Warnings:** Acceptable but should be addressed when possible. Acknowledge them before submitting.
+- If validation returns zero errors, proceed with `contentrain_submit`.
+
+---
+
+## 7. Submit Behavior
+
+### 7.1 auto-merge Mode
+
+```
+contentrain_submit
+  --> Merge branch to main
+  --> Update context.json
+  --> Clean up worktree
+  --> Status: published
+```
+
+### 7.2 review Mode
+
+```
+contentrain_submit
+  --> Push branch to remote
+  --> Update context.json
+  --> Clean up worktree
+  --> Status: in_review
+  --> Studio notifies reviewers
+```
+
+### 7.3 Submit Rules
+
+- Submit operates on the current pending branch. There must be pending changes.
+- If no changes are pending, submit is a no-op.
+- After submit, the agent can continue with other operations (new branch will be created for new changes).
+- Normalize operations ALWAYS submit in review mode, regardless of project workflow setting.
+
+---
+
+## 8. Metadata Structure
+
+Metadata files track governance information. They are system-managed -- agents NEVER write to them.
+
+### File Paths
+
+| Kind | Path |
+|------|------|
+| Singleton / Dictionary | `.contentrain/meta/{modelId}/{locale}.json` |
+| Collection | `.contentrain/meta/{modelId}/{locale}.json` (object-map: `{ entryId: meta }`) |
+| Document | `.contentrain/meta/{modelId}/{slug}/{locale}.json` |
+
+### Metadata Fields
+
+```json
+{
+  "status": "published",
+  "source": "agent",
+  "updated_by": "claude",
+  "approved_by": "ahmet@contentrain.io",
+  "version": "1"
+}
+```
+
+| Field | Values | Description |
+|-------|--------|-------------|
+| `status` | `draft`, `in_review`, `published`, `rejected`, `archived` | Current workflow state |
+| `source` | `agent`, `human`, `import` | How the content was created |
+| `updated_by` | string | Agent name or user email |
+| `approved_by` | string or null | Who approved (review mode only) |
+| `version` | string | Content version identifier |