@contentrain/skills 0.1.2 → 0.2.1

package/skills/contentrain/references/mcp-tools.md

@@ -0,0 +1,308 @@
+---
+name: mcp-tools
+description: "Complete MCP tool parameter tables, entry formats, scan modes, apply parameters, bulk operations, and workflow tools."
+---
+
+# MCP Tools Reference
+
+## Context Tools (read-only)
+
+### contentrain_status
+
+Get full project state in one call. No parameters.
+
+Returns:
+- `initialized`: whether `.contentrain/` exists with config.json
+- `config`: project configuration (stack, workflow, locales, domains)
+- `models[]`: summary of all models (id, kind, domain, i18n, field count)
+- `context`: last operation and project stats from `context.json`
+- `vocabulary_size`: number of terms in vocabulary.json
+- `branches`: branch health (total, merged, unmerged counts)
+- `branch_warning`: warning message if too many active branches
+- `next_steps`: suggested next actions
+
+If not initialized, returns `detected_stack` and a suggestion to run `contentrain_init`.
+
+### contentrain_describe
+
+Get full schema + optional sample for one model.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `model` | string | Yes | Model ID |
+| `include_sample` | boolean | No | Include a sample entry |
+| `locale` | string | No | Locale for sample data |
+
+Returns full schema, all field definitions, entry stats, and stack-aware import snippets.
+
+### contentrain_describe_format
+
+Get the storage and file-format contract for Contentrain content. No parameters.
+
+Returns the complete format specification for all four model kinds, canonical serialization rules, and file path patterns.
+
+## Setup Tools
+
+### contentrain_init
+
+Initialize `.contentrain/` directory structure.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `stack` | string | No | Framework: `"nuxt"`, `"next"`, `"astro"`, `"sveltekit"`, `"react"`, `"node"` |
+| `locales` | string[] | No | Supported locales |
+| `domains` | string[] | No | Content domains |
+
+### contentrain_scaffold
+
+Generate models from a built-in template.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `template` | string | Yes | Template name (see below) |
+| `locales` | string[] | No | Override default locales |
+| `with_sample_content` | boolean | No | Generate example content (default: true) |
+
+Available templates:
+
+| Template | Models Created | Use Case |
+|----------|---------------|----------|
+| `blog` | blog-post (document), categories (collection), authors (collection) | Blog/magazine |
+| `landing` | hero (singleton), features (singleton), pricing (collection), faq (collection), testimonials (collection) | Landing page |
+| `docs` | doc-page (document), doc-categories (collection) | Documentation |
+| `ecommerce` | products (collection), categories (collection), brands (collection) | E-commerce |
+| `saas` | hero (singleton), features (singleton), pricing (collection), changelog (document), faq (collection) | SaaS site |
+| `i18n` | navigation (singleton), form-labels (singleton), error-messages (dictionary), app-strings (dictionary) | Localization |
+| `mobile` | app-strings (dictionary), error-messages (dictionary), onboarding (collection) | Mobile app |
+
+## Model Tools
+
+### contentrain_model_save
+
+Create or update a model definition (upsert).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Kebab-case model ID |
+| `name` | string | Yes | Human-readable display name |
+| `kind` | string | Yes | `singleton`, `collection`, `document`, `dictionary` |
+| `domain` | string | Yes | Organizational group |
+| `i18n` | boolean | Yes | Whether model supports localization |
+| `fields` | object | No | Field definitions (not for dictionary) |
+| `description` | string | No | Model description |
+| `content_path` | string | No | Framework-relative path for content files |
+| `locale_strategy` | string | No | `"file"` (default), `"suffix"`, `"directory"`, `"none"` |
+
+Notes:
+- Upserts by model ID: existing model is updated, new model is created
+- `locale_strategy: "none"` requires `i18n: false`
+- `content_path` overrides default `.contentrain/content/` location
+
+### contentrain_model_delete
+
+Delete a model and its content.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `model` | string | Yes | Model ID to delete |
+| `confirm` | boolean | Yes | Must be `true` |
+
+Performs referential integrity check before deletion. If other models reference the target model via `relation` or `relations` fields, deletion is **BLOCKED**. Remove the referencing fields first.
+
+## Content Tools
+
+### contentrain_content_save
+
+Create or update content entries (upsert).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `model` | string | Yes | Target model ID |
+| `entries` | array | Yes | Array of entry objects |
+
+#### Entry Format
+
+Each entry in the `entries` array:
+
+```json
+{
+  "id": "optional-entry-id",
+  "slug": "optional-slug",
+  "locale": "en",
+  "data": { "field_name": "field_value" }
+}
+```
+
+**Per kind:**
+
+| Kind | Required Fields | Notes |
+|------|----------------|-------|
+| **Collection** | `locale`, `data` | Provide `id` to update, omit for new (auto-generated) |
+| **Document** | `slug`, `locale`, `data` | `slug` is required. Include `"body"` in `data` for markdown content |
+| **Singleton** | `locale`, `data` | No `id` or `slug` needed |
+| **Dictionary** | `locale`, `data` | `data` is flat key-value: `{ "auth.login": "Log In" }` |
+
+**NEVER include system fields** (`status`, `source`, `updated_by`, `updated_at`, `createdAt`, `updatedAt`) in `data`.
+
+### contentrain_content_delete
+
+Delete a content entry.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `model` | string | Yes | Model ID |
+| `id` | string | Conditional | Entry ID (for collections) |
+| `slug` | string | Conditional | Document slug (for documents) |
+| `locale` | string | Conditional | Locale (for singleton/dictionary) |
+| `confirm` | boolean | Yes | Must be `true` |
+
+### contentrain_content_list
+
+List content entries for a model (read-only).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `model` | string | Yes | Model ID |
+| `locale` | string | No | Locale filter |
+| `filter` | object | No | Field-based filter |
+| `resolve` | boolean | No | Resolve relations |
+| `limit` | number | No | Max entries to return |
+| `offset` | number | No | Pagination offset |
+
+## Normalize Tools
+
+### contentrain_scan
+
+Scan project for structure or content candidates.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mode` | string | No | `"candidates"` (default), `"graph"`, `"summary"` |
+| `paths` | string[] | No | Directories to scan (auto-detected if omitted) |
+| `include` | string[] | No | File extensions (default: .tsx, .jsx, .vue, .ts, .js, .mjs, .astro, .svelte) |
+| `exclude` | string[] | No | Additional directories to exclude |
+| `limit` | number | No | Batch size for candidates mode (default: 50) |
+| `offset` | number | No | Pagination offset for candidates mode |
+| `min_length` | number | No | Min string length filter |
+| `max_length` | number | No | Max string length filter |
+
+#### Scan Modes
+
+| Mode | Output | Purpose |
+|------|--------|---------|
+| `graph` | Import/component dependency graph with string counts | Understand project structure, prioritize files |
+| `candidates` | Hardcoded string candidates with file locations, context | Find content to extract (paginated) |
+| `summary` | High-level stats by directory, top repeated strings | Quick project overview |
+
+Candidates mode supports pagination via `offset` and `limit`. Response includes `stats.has_more`.
+
+### contentrain_apply
+
+Apply normalize operation (extract or reuse).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mode` | string | Yes | `"extract"` or `"reuse"` |
+| `dry_run` | boolean | No | Preview without executing (default: `true`) |
+| `extractions` | array | Conditional | For extract mode |
+| `scope` | object | Conditional | For reuse mode (requires `model` or `domain`) |
+| `patches` | array | Conditional | For reuse mode (max 100 per call) |
+
+#### Extract Mode
+
+```json
+{
+  "mode": "extract",
+  "dry_run": true,
+  "extractions": [
+    {
+      "model": "ui-texts",
+      "kind": "dictionary",
+      "domain": "system",
+      "i18n": true,
+      "fields": {},
+      "entries": [
+        {
+          "locale": "en",
+          "data": { "nav.home": "Home" },
+          "source": { "file": "src/Nav.vue", "line": 5, "value": "Home" }
+        }
+      ]
+    }
+  ]
+}
+```
+
+#### Reuse Mode
+
+```json
+{
+  "mode": "reuse",
+  "dry_run": true,
+  "scope": { "model": "ui-texts" },
+  "patches": [
+    {
+      "file": "src/Nav.vue",
+      "line": 5,
+      "old_value": "Home",
+      "new_expression": "{{ $t('nav.home') }}",
+      "import_statement": ""
+    }
+  ]
+}
+```
+
+- `dry_run` defaults to `true`. ALWAYS preview first, then `dry_run: false` to execute
+- `scope` requires at least one of `model` or `domain`
+- `patches` max: 100 per call
+
+## Workflow Tools
+
+### contentrain_validate
+
+Validate project content against model schemas.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `model` | string | No | Validate specific model only (omit for all) |
+| `fix` | boolean | No | Auto-fix structural issues (canonical sort, orphan meta, missing locale files). Default: `false` |
+
+### contentrain_submit
+
+Push contentrain/* branches to remote.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `branches` | string[] | No | Specific branches to push (omit for all contentrain/* branches) |
+| `message` | string | No | Optional message for the push operation |
+
+## Bulk Tools
+
+### contentrain_bulk
+
+Run git-backed batch operations on existing content entries.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `operation` | string | Yes | `"copy_locale"`, `"update_status"`, `"delete_entries"` |
+| `model` | string | Yes | Target model ID |
+| `source_locale` | string | Conditional | For `copy_locale` |
+| `target_locale` | string | Conditional | For `copy_locale` |
+| `entry_ids` | string[] | Conditional | For `update_status` and `delete_entries` |
+| `status` | string | Conditional | For `update_status` |
+| `confirm` | boolean | Conditional | For `delete_entries` (must be `true`) |
+
+#### Operations
+
+| Operation | Applicable Kinds | Required Params |
+|-----------|-----------------|-----------------|
+| `copy_locale` | collection, singleton, dictionary (i18n only) | `source_locale`, `target_locale` |
+| `update_status` | collection only | `entry_ids`, `status` |
+| `delete_entries` | collection only | `entry_ids`, `confirm: true` |
+
+#### Rules
+
+- ALWAYS verify the target model with `contentrain_describe` or `contentrain_status` before running bulk
+- `copy_locale` MUST NOT be used on non-i18n models
+- Bulk operations create branches and commits like other write tools
+- Validate afterward when content shape may have changed

package/skills/contentrain/references/model-kinds.md

@@ -0,0 +1,330 @@
+---
+name: model-kinds
+description: "Detailed model kinds reference including storage formats, relations, nesting rules, and examples for all four kinds."
+---
+
+# Model Kinds Reference
+
+Contentrain has four model kinds, each with distinct storage format, ID management, and use cases.
+
+## Singleton
+
+**One instance per locale.** Use for page sections, site config, navigation.
+
+| Aspect | Detail |
+|--------|--------|
+| Storage | JSON object (one file per locale) |
+| File path | `.contentrain/content/{domain}/{model-id}/{locale}.json` |
+| `i18n: false` path | `.contentrain/content/{domain}/{model-id}/data.json` |
+| ID management | None (single instance) |
+| Relation target | Cannot be referenced by relations |
+
+### Example Model
+
+```json
+{
+  "id": "hero-section",
+  "name": "Hero Section",
+  "kind": "singleton",
+  "domain": "marketing",
+  "i18n": true,
+  "fields": {
+    "title": { "type": "string", "required": true, "max": 80 },
+    "subtitle": { "type": "text", "max": 200 },
+    "cta": { "type": "string", "required": true },
+    "cta_url": { "type": "url", "required": true },
+    "background": { "type": "image" }
+  }
+}
+```
+
+### Example Content (`en.json`)
+
+```json
+{
+  "background": "assets/hero-bg.webp",
+  "cta": "Get Started",
+  "cta_url": "https://app.example.com/signup",
+  "subtitle": "The modern content platform for developers",
+  "title": "Build faster with Contentrain"
+}
+```
+
+**Use for:** Hero sections, navigation menus, site settings, form labels, footer content -- anything with exactly one instance per locale.
+
+## Collection
+
+**Multiple entries.** Use for team members, products, FAQs, categories.
+
+| Aspect | Detail |
+|--------|--------|
+| Storage | JSON object-map (entry ID as key, sorted lexicographically) |
+| File path | `.contentrain/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` |
+
+### Example Model
+
+```json
+{
+  "id": "team-members",
+  "name": "Team Members",
+  "kind": "collection",
+  "domain": "marketing",
+  "i18n": true,
+  "fields": {
+    "name": { "type": "string", "required": true },
+    "role": { "type": "string", "required": true },
+    "avatar": { "type": "image" },
+    "bio": { "type": "text" },
+    "linkedin": { "type": "url" }
+  }
+}
+```
+
+### Storage Format (on disk)
+
+```json
+{
+  "a1b2c3d4e5f6": {
+    "avatar": "assets/ahmet.jpg",
+    "bio": "Founder and CEO",
+    "linkedin": "https://linkedin.com/in/ahmet",
+    "name": "Ahmet",
+    "role": "CEO"
+  },
+  "f6e5d4c3b2a1": {
+    "avatar": "assets/jane.jpg",
+    "bio": "Technical leader",
+    "linkedin": "https://linkedin.com/in/jane",
+    "name": "Jane",
+    "role": "CTO"
+  }
+}
+```
+
+### MCP Tool Output (differs from storage)
+
+MCP tools return collections as arrays with `id` injected:
+
+```json
+[
+  { "id": "a1b2c3d4e5f6", "name": "Ahmet", "role": "CEO", "avatar": "assets/ahmet.jpg" },
+  { "id": "f6e5d4c3b2a1", "name": "Jane", "role": "CTO", "avatar": "assets/jane.jpg" }
+]
+```
+
+### ID Management
+
+- IDs are 12-char hex strings, auto-generated by MCP tools
+- Provide `id` in `contentrain_content_save` entry to update an existing entry
+- Omit `id` to create a new entry (ID auto-generated)
+- The same ID is used across all locale files for the same entry
+
+**Why object-map?**
+- Sorted keys produce predictable diffs and minimize Git merge conflicts
+- No ID duplication -- key IS the ID
+- Two branches adding different entries rarely conflict (~0.3% chance for 350 entries)
+
+## Document
+
+**Markdown with frontmatter.** Use for blog posts, documentation, changelogs.
+
+| Aspect | Detail |
+|--------|--------|
+| Storage | `.md` file with YAML frontmatter |
+| File path | `.contentrain/content/{domain}/{model-id}/{slug}/{locale}.md` |
+| `i18n: false` path | `.contentrain/content/{domain}/{model-id}/{slug}.md` |
+| ID management | `slug` field (URL-safe, unique) |
+| Relation target | Referenced by `slug` |
+
+### Example Model
+
+```json
+{
+  "id": "blog-post",
+  "name": "Blog Post",
+  "kind": "document",
+  "domain": "blog",
+  "i18n": true,
+  "fields": {
+    "title": { "type": "string", "required": true, "max": 120 },
+    "slug": { "type": "slug", "required": true, "unique": true },
+    "excerpt": { "type": "text", "max": 200 },
+    "author": { "type": "relation", "model": "team-members", "required": true },
+    "tags": { "type": "array", "items": "string" },
+    "cover": { "type": "image" }
+  }
+}
+```
+
+### Example Content (`getting-started/en.md`)
+
+```markdown
+---
+title: Getting Started
+slug: getting-started
+excerpt: Learn how to set up Contentrain in your project
+author: a1b2c3d4e5f6
+tags: [tutorial, intro]
+cover: assets/getting-started-cover.webp
+---
+# Getting Started with Contentrain
+
+Your markdown body content here...
+```
+
+### Slug Management
+
+- Slug is the directory name and identity for the document
+- Provide `slug` in `contentrain_content_save` entry (required for documents)
+- Slug must be URL-safe: lowercase, kebab-case, matching `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`
+- Same slug used across all locale files
+
+**Use for:** Blog posts, documentation pages, changelogs, knowledge base articles -- long-form content with typed metadata.
+
+## 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 | `.contentrain/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 |
+
+### Example Model
+
+```json
+{
+  "id": "error-messages",
+  "name": "Error Messages",
+  "kind": "dictionary",
+  "domain": "system",
+  "i18n": true
+}
+```
+
+### Example Content (`en.json`)
+
+```json
+{
+  "auth.expired": "Session expired. Please log in again.",
+  "auth.failed": "Authentication failed. Check your credentials.",
+  "auth.locked": "Account locked. Contact support.",
+  "validation.email": "Please enter a valid email address.",
+  "validation.required": "{field} is required."
+}
+```
+
+### Key Naming Rules
+
+- Semantic, hierarchical, dot-separated keys
+- Always in English regardless of locale
+- Lowercase with dots as separators, no spaces, no camelCase
+- Group by feature/domain, not by page/position
+- GOOD: `auth.login.button`, `errors.404.title`, `nav.main.dashboard`
+- BAD: `button1`, `text_3`, `label_top`, `str_47`
+
+**Use for:** Error messages, UI strings, i18n translation files, mobile app strings, form validation messages.
+
+## Relations
+
+### 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
+
+### Target Model Restrictions
+
+| Target Kind | Reference Key | Can Be Target? |
+|-------------|--------------|----------------|
+| Collection | Entry `id` | Yes |
+| Document | Document `slug` | Yes |
+| Singleton | -- | No |
+| Dictionary | -- | No |
+
+### 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" }
+```
+
+### Self-Referencing
+
+Models can reference themselves (e.g., hierarchical categories):
+
+```json
+"parent": { "type": "relation", "model": "categories" }
+```
+
+### 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
+
+### 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
+
+## Nesting
+
+### Object Type
+
+```json
+"address": {
+  "type": "object",
+  "fields": {
+    "city": { "type": "string", "required": true },
+    "street": { "type": "string", "required": true },
+    "zip": { "type": "string" }
+  }
+}
+```
+
+### 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
+}
+```
+
+### 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