@contentrain/skills 0.1.2 → 0.2.1

package/skills/contentrain/references/architecture.md

@@ -0,0 +1,212 @@
+---
+name: architecture
+description: "Contentrain schema and type architecture overview including design principles, type system, model definitions, and storage patterns."
+---
+
+# Contentrain Architecture
+
+## Design Principles
+
+1. **Token-efficient:** Flat type system with single keywords. No `format` sub-layer. `type: "email"` is the complete specification.
+2. **AI-first:** Easy to produce, cheap to read, fast to validate. Minimal properties, omit defaults.
+3. **Platform-agnostic:** MCP tools are framework-agnostic. Agent provides stack-specific intelligence.
+4. **Git-native:** All content is Git-tracked. Object-map storage with sorted keys for clean diffs.
+5. **Deterministic:** Canonical serialization ensures identical data always produces identical files.
+
+## Type System Overview
+
+Contentrain uses a **flat type system** with 27 types organized into 7 families. Each type is a single keyword.
+
+| Family | Types | Count |
+|--------|-------|-------|
+| String | `string`, `text`, `email`, `url`, `slug`, `color`, `phone`, `code`, `icon`, `markdown`, `richtext` | 11 |
+| Number | `number`, `integer`, `decimal`, `percent`, `rating` | 5 |
+| Primitives | `boolean`, `date`, `datetime` | 3 |
+| Media | `image`, `video`, `file` | 3 |
+| Relations | `relation`, `relations` | 2 |
+| Structural | `select`, `array`, `object` | 3 |
+
+**Total: 27 types**
+
+See [Schema Types](schema-types.md) for the complete catalog with validation rules and JSON Schema exports.
+
+## Field Definition
+
+A field definition describes one field in a model. Include only properties that apply -- omit all defaults.
+
+```json
+{
+  "type": "string",
+  "required": true,
+  "min": 3,
+  "max": 100,
+  "unique": true,
+  "description": "Page title"
+}
+```
+
+### Key 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. Default: `false`. Omit if `false` |
+| `default` | ALL | Default value. Omit if `null` |
+| `min` / `max` | strings (chars), numbers (value), arrays (elements) | Constraints |
+| `pattern` | `string`, `text`, `code` | Regex validation |
+| `options` | `select` ONLY | Fixed choices array |
+| `model` | `relation`, `relations` ONLY | Target model ID (string or string array for polymorphic) |
+| `items` | `array` ONLY | Element type definition |
+| `fields` | `object` ONLY | Nested field definitions |
+| `accept` | `image`, `video`, `file` | Allowed MIME types |
+| `maxSize` | `image`, `video`, `file` | Max file size in bytes |
+| `description` | ALL | Human-readable hint |
+
+### Omission Rules
+
+- `required: false` (default) --> do NOT include
+- `unique: false` (default) --> do NOT include
+- `default: null` --> do NOT include
+- Fewer properties = fewer tokens = faster agent processing
+
+## 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" }
+  }
+}
+```
+
+### Model Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | string | Yes | Unique identifier, **kebab-case** |
+| `name` | string | Yes | Human-readable display name |
+| `kind` | string | Yes | `singleton`, `collection`, `document`, `dictionary` |
+| `domain` | string | Yes | Organizational group (maps to content subdirectory) |
+| `i18n` | boolean | Yes | Whether model supports multiple locales |
+| `description` | string | No | Model description for docs and agent context |
+| `fields` | object | Yes (except dictionary) | Field definitions. Dictionary has NO fields |
+| `content_path` | string | No | Framework-relative path. When set, content writes here instead of `.contentrain/content/` |
+| `locale_strategy` | string | No | How locale is encoded: `"file"` (default), `"suffix"`, `"directory"`, `"none"` |
+
+## The Four Kinds
+
+### Singleton
+One instance per locale. JSON object.
+```json
+{ "cta": "Get Started", "title": "Build faster" }
+```
+Path: `content/{domain}/{model-id}/{locale}.json`
+
+### Collection
+Multiple entries. Object-map with entry ID as key, sorted lexicographically.
+```json
+{
+  "a1b2c3d4e5f6": { "name": "Ahmet", "role": "CEO" },
+  "f6e5d4c3b2a1": { "name": "Jane", "role": "CTO" }
+}
+```
+Path: `content/{domain}/{model-id}/{locale}.json`
+MCP tools return collections as **arrays** with `id` injected.
+
+### Document
+Markdown with YAML frontmatter. One file per slug per locale.
+```markdown
+---
+title: Getting Started
+slug: getting-started
+---
+# Getting Started with Contentrain
+```
+Path: `content/{domain}/{model-id}/{slug}/{locale}.md`
+
+### Dictionary
+Flat key-value. All values are strings. No `fields` property in model definition.
+```json
+{ "auth.expired": "Session expired", "auth.failed": "Authentication failed" }
+```
+Path: `content/{domain}/{model-id}/{locale}.json`
+
+## Entry ID Generation
+
+- **Format:** 12-character hexadecimal string (e.g., `a1b2c3d4e5f6`)
+- **Scope:** Collection entries only
+- **Generation:** Auto-generated by MCP tools. Agents never create IDs manually
+- **Usage:** Object-map key on disk, injected as `id` field in MCP tool output
+- **Locale-agnostic:** Same ID used across all locale files for the same entry
+
+## Object-Map Rationale
+
+Collections use object-map storage (`{ entryId: { fields } }`) instead of arrays because:
+
+1. **Sorted keys produce predictable diffs** -- adding entries at deterministic positions
+2. **Minimizes Git merge conflicts** -- two branches adding different entries rarely conflict (~0.3% chance for 350-entry collection)
+3. **No ID duplication** -- key IS the ID, no redundant `id` field inside entries
+4. **Consistent with metadata files** -- same structure in `.contentrain/meta/`
+
+## 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** | **INVALID** | `{dir}/{model}.json` or `{dir}/{slug}.md` |
+
+- `locale_strategy: "none"` requires `i18n: false`
+- When `content_path` is set, `{dir}` is the content_path. Otherwise `{dir}` is `.contentrain/content/{domain}/{model-id}`
+
+## Nesting Limits
+
+**Maximum nesting depth: 2 levels.**
+
+An `object` inside an `object` is allowed. An `object` inside an `object` inside an `object` is NOT.
+
+```json
+"address": {
+  "type": "object",
+  "fields": {
+    "city": { "type": "string", "required": true },
+    "coordinates": {
+      "type": "object",
+      "fields": {
+        "lat": { "type": "decimal" },
+        "lng": { "type": "decimal" }
+      }
+    }
+  }
+}
+```
+
+- 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
+
+## 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` |

package/skills/contentrain/references/content-formats.md

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