@contentrain/skills 0.1.2 → 0.2.1

package/skills/contentrain/references/schema-types.md

@@ -0,0 +1,177 @@
+---
+name: schema-types
+description: "Complete 27-type catalog organized by family with field properties, validation rules, and examples."
+---
+
+# Schema Types Reference
+
+Contentrain uses a **flat type system** with 27 types. Each type is a single keyword -- no `format` sub-layer. `type: "email"` is the complete specification.
+
+## 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" }` |
+
+### String Family Examples
+
+```json
+"title": { "type": "string", "required": true, "min": 3, "max": 120 }
+"bio": { "type": "text", "max": 500 }
+"contact_email": { "type": "email", "required": true, "unique": true }
+"website": { "type": "url" }
+"handle": { "type": "slug", "required": true, "unique": true }
+"brand_color": { "type": "color", "default": "#4F46E5" }
+"mobile": { "type": "phone" }
+"snippet": { "type": "code" }
+"logo_icon": { "type": "icon" }
+"body": { "type": "markdown", "required": true }
+"description": { "type": "richtext" }
+```
+
+## 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 }` |
+
+### Number Family Examples
+
+```json
+"price": { "type": "decimal", "required": true, "min": 0 }
+"quantity": { "type": "integer", "min": 0, "max": 10000 }
+"discount": { "type": "percent" }
+"score": { "type": "rating", "required": true }
+"weight": { "type": "number" }
+```
+
+## 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" }` |
+
+### Primitives Examples
+
+```json
+"is_featured": { "type": "boolean", "default": false }
+"publish_date": { "type": "date", "required": true }
+"event_start": { "type": "datetime", "required": true }
+```
+
+## 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.
+
+### Media Examples
+
+```json
+"avatar": { "type": "image", "accept": "image/png,image/jpeg,image/webp", "maxSize": 2097152 }
+"intro_video": { "type": "video", "accept": "video/mp4,video/webm" }
+"resume": { "type": "file", "accept": "application/pdf" }
+```
+
+## Relations (2 types)
+
+| Type | Cardinality | Storage |
+|------|-------------|---------|
+| `relation` | One-to-one | `"entry-id"` (string) |
+| `relations` | One-to-many | `["id-1", "id-2"]` (string array) |
+
+### Relation Examples
+
+```json
+"author": { "type": "relation", "model": "team-members", "required": true }
+"categories": { "type": "relations", "model": "categories" }
+"related_content": { "type": "relation", "model": ["blog-post", "page"] }
+"parent": { "type": "relation", "model": "categories" }
+```
+
+## 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 |
+
+### Structural Examples
+
+```json
+"status": { "type": "select", "options": ["draft", "published", "archived"], "default": "draft" }
+
+"tags": { "type": "array", "items": "string", "min": 1, "max": 10 }
+
+"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
+}
+
+"address": {
+  "type": "object",
+  "fields": {
+    "city": { "type": "string", "required": true },
+    "street": { "type": "string", "required": true },
+    "zip": { "type": "string" }
+  }
+}
+```
+
+## Field Properties Reference
+
+| 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) |
+
+## 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

package/skills/contentrain/references/security.md

@@ -0,0 +1,146 @@
+---
+name: security
+description: "Security rules: XSS prevention, secret detection, PII handling, URL validation"
+---
+
+# 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/skills/contentrain/references/workflow.md

@@ -0,0 +1,285 @@
+---
+name: workflow
+description: "Git workflow rules: branching, validation, review, conflict resolution, status management"
+---
+
+# 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" }
+```
+
+- Feature branch is created from the `contentrain` branch, changes are committed, feature branch is **merged into `contentrain`**, then baseBranch is advanced via **update-ref** (fast-forward), and `.contentrain/` files are **selectively synced** to the developer's working tree.
+- 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 Dedicated `contentrain` Branch
+
+The `contentrain` branch is the **single source of truth** for content state:
+
+- Created automatically at `contentrain_init`.
+- All content writes happen on feature branches forked from `contentrain`.
+- The `contentrain` branch is **protected from deletion**.
+- context.json is committed together with content changes, not as a separate commit.
+
+### 3.2 Worktree-Based Transactions
+
+Every write operation follows this flow:
+
+1. MCP creates a **temporary Git worktree** on a new feature branch forked from `contentrain`.
+2. Changes are made in the worktree (content files, model files, context.json).
+3. Changes are committed to the feature branch.
+4. **auto-merge mode:** Feature branch is merged into `contentrain`, then baseBranch is advanced via **update-ref** (fast-forward), then `.contentrain/` files are **selectively synced** to the developer's working tree. Dirty files are skipped with a warning. Worktree is cleaned up.
+5. **review mode:** Feature branch is pushed to remote for team review. Worktree is cleaned up. Studio notifies reviewers.
+
+Developer's working tree is **never mutated** during MCP git operations. There is no stash, no checkout, and no merge on the developer's tree.
+
+### 3.3 Developer Manual Editing
+
+If the developer manually edits `.contentrain/` files in their working tree, MCP selective sync skips those dirty files and issues a warning. The developer must commit or discard their local changes before MCP can sync those files.
+
+### 3.4 Critical Rules
+
+- **NEVER commit directly to main or the `contentrain` branch.** All changes go through feature branches.
+- **NEVER create branches manually.** MCP tools handle all Git operations.
+- **NEVER force-push or rebase** Contentrain branches.
+- **NEVER delete the `contentrain` branch.** It is the content state SSOT.
+- 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.5 Branch Lifecycle
+
+```
+Feature branch created (worktree on contentrain)
+  --> Changes committed
+  --> auto-merge: feature merged into contentrain
+                  --> update-ref advances baseBranch
+                  --> selective sync .contentrain/ to developer's tree
+  --> review: feature pushed to remote, awaiting review
+  --> Worktree cleaned up
+```
+
+The `contentrain` branch is permanent and protected. Feature branches are retained for `branchRetention` days (default: 30) for audit trail, then pruned.
+
+### 3.6 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 `contentrain` branch and synced to baseBranch | 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 feature branch into contentrain
+  --> Advance baseBranch via update-ref (fast-forward)
+  --> Selectively sync .contentrain/ files to developer's working tree
+  --> Clean up worktree
+  --> Status: published
+```
+
+### 7.2 review Mode
+
+```
+contentrain_submit
+  --> Push feature branch to remote
+  --> 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 |