@contentrain/skills 0.1.0

package/workflows/contentrain-init.md

@@ -0,0 +1,91 @@
+# Skill: Initialize Contentrain in a Project
+
+> Set up Contentrain content infrastructure in an existing project.
+
+---
+
+## When to Use
+
+The user wants to add Contentrain to their project, or says something like "set up contentrain", "initialize contentrain", "add content management".
+
+---
+
+## Steps
+
+### 1. Detect the Tech Stack
+
+Read `package.json` to identify the framework:
+
+| Dependency | Stack |
+|---|---|
+| `nuxt` | Nuxt 3 |
+| `next` | Next.js |
+| `@astrojs/astro` or `astro` | Astro |
+| `@sveltejs/kit` | SvelteKit |
+
+If none match, treat as a generic Node.js project. Report the detected stack to the user before proceeding.
+
+### 2. Ask for Configuration
+
+Ask the user for:
+
+- **Supported locales:** Which languages will the project support? Default: `["en"]`. Use ISO 639-1 codes.
+- **Source locale:** Which locale is the primary/source locale? Default: `"en"`.
+- **Domain names:** Suggest domains based on the project structure (e.g., `marketing`, `blog`, `app`, `docs`). Ask the user to confirm or modify.
+
+### 3. Initialize the Project
+
+Call the MCP tool:
+
+```
+contentrain_init(stack: "<detected>", locales: ["en", ...], domains: ["marketing", ...])
+```
+
+This creates the `.contentrain/` directory structure, `config.json`, and initial `context.json`.
+
+### 4. Analyze Project Conventions
+
+After initialization, review the project for conventions to inform content creation:
+
+- **Tone:** Analyze existing copy in the project (README, landing page, UI text) to determine the appropriate tone (e.g., `professional`, `casual`, `technical`).
+- **Naming conventions:** Note any patterns in file naming, component naming, or content structure.
+
+> **Note:** Do NOT manually edit `context.json`. It is managed automatically by MCP tools and updated after every write operation.
+
+### 5. Suggest Initial Models
+
+Based on the project analysis, suggest models that would be useful:
+
+- If the project has a landing page: suggest `hero` (singleton), `features` (singleton or collection).
+- If the project has a blog section: suggest `blog-post` (document), `categories` (collection), `authors` (collection).
+- If the project has UI text: suggest `ui-labels` (dictionary), `error-messages` (dictionary).
+
+Present suggestions to the user and ask which to create. For selected models, call `contentrain_model_save` for each.
+
+### 6. Offer Scaffold Templates
+
+If the project matches a common pattern, offer to use a scaffold template:
+
+```
+contentrain_scaffold(template: "blog", locales: ["en"], with_sample_content: true)
+```
+
+Available templates: `blog`, `landing`, `docs`, `ecommerce`, `saas`, `i18n`, `mobile`.
+
+### 7. Set Up Agent Rules
+
+Copy the appropriate rules file to the project:
+
+- For Claude Code projects: append Contentrain rules to the project's `CLAUDE.md` or create a new section.
+- For Cursor projects: create or update `.cursorrules` with Contentrain conventions.
+
+Include a reference to the framework-specific guide (nuxt.md, next.md, astro.md, sveltekit.md).
+
+### 8. Final Summary
+
+Report to the user:
+
+- What was created in `.contentrain/`.
+- Which models were set up.
+- How to import content in their code (show the `#contentrain` import).
+- Next steps: create content, run `npx contentrain generate`, start the dev server.

package/workflows/contentrain-model.md

@@ -0,0 +1,134 @@
+# Skill: Design and Save Models
+
+> Create or evolve Contentrain model definitions safely.
+
+---
+
+## When to Use
+
+Use this when the user wants to:
+
+- add a new model
+- change fields on an existing model
+- choose between `singleton`, `collection`, `document`, and `dictionary`
+- define relations, locales, or custom content paths
+
+---
+
+## Steps
+
+### 1. Inspect Project State
+
+Call `contentrain_status` first:
+
+- confirm the project is initialized
+- see existing model IDs and domains
+- avoid creating duplicates
+
+If the user is extending an existing model, call `contentrain_describe(model: "<model-id>")`.
+
+### 2. Confirm Storage Contract
+
+Call `contentrain_describe_format` before proposing structure changes.
+
+Use it to confirm:
+
+- model kinds and storage expectations
+- locale behavior
+- document vs JSON model tradeoffs
+- how custom `content_path` and `locale_strategy` affect files
+
+### 3. Choose the Right Kind
+
+- `singleton`: one object per locale, e.g. hero, navigation, footer
+- `collection`: repeated entries with IDs, e.g. testimonials, faq items, authors
+- `document`: long-form markdown content with frontmatter, e.g. blog posts, docs pages
+- `dictionary`: flat key-value strings, e.g. UI labels, error messages
+
+Default rules:
+
+- use `dictionary` for UI/system strings
+- use `document` for markdown-heavy long-form content
+- use `collection` for repeated structured items
+- use `singleton` for one page/section config per locale
+
+### 4. Design Fields
+
+Follow these rules:
+
+- model IDs must be kebab-case
+- field names must be snake_case
+- relation fields must define a target `model`
+- prefer small, explicit schemas over large generic `object` blobs
+- only mark fields as `required` when the content truly cannot function without them
+
+Relation guidance:
+
+- `relation`: single reference
+- `relations`: multiple references
+- use `slug`-driven relations for document-like linking
+
+### 5. Decide i18n and Path Strategy
+
+Ask or infer:
+
+- should this model be localized?
+- should it use the default `.contentrain/content/...` path or a custom `content_path`?
+- if custom path is needed, which `locale_strategy` matches the project layout?
+
+Use custom paths only when the framework or repo structure clearly benefits from it.
+
+### 6. Present the Proposed Model
+
+Before writing, show:
+
+- model ID
+- kind
+- domain
+- `i18n` behavior
+- field list with types
+- relation targets
+- any custom `content_path` / `locale_strategy`
+
+Get user confirmation before saving.
+
+### 7. Save the Model
+
+Call `contentrain_model_save` with the approved definition.
+
+Example:
+
+```json
+{
+  "id": "hero",
+  "name": "Hero",
+  "kind": "singleton",
+  "domain": "marketing",
+  "i18n": true,
+  "fields": {
+    "title": { "type": "string", "required": true },
+    "subtitle": { "type": "text" },
+    "cta_label": { "type": "string" },
+    "featured_post": { "type": "relation", "model": "blog-post" }
+  }
+}
+```
+
+### 8. Validate Downstream Impact
+
+After changing a model:
+
+- review whether existing content now needs updates
+- call `contentrain_validate`
+- if the model is consumed by the SDK, recommend `contentrain generate`
+
+### 9. Final Summary
+
+Report:
+
+- model created or updated
+- kind and domain
+- field count
+- any relation targets
+- whether content migration is needed next
+

package/workflows/contentrain-normalize.md

@@ -0,0 +1,294 @@
+# Skill: Extract Hardcoded Content Strings (Two-Phase Normalize)
+
+> Scan the project for hardcoded user-visible strings, extract them into Contentrain models, and then patch source files to reference the extracted content.
+
+---
+
+## When to Use
+
+The user wants to extract hardcoded strings from their codebase, or says something like "normalize my project", "extract content", "move strings to contentrain", "find hardcoded text", "internationalize", "add i18n".
+
+This is a two-phase process:
+- **Phase 1 (Extraction):** Pull hardcoded strings into `.contentrain/content/` — source files are NOT modified.
+- **Phase 2 (Reuse):** Replace hardcoded strings in source files with i18n/content references.
+
+Phase 1 is valuable on its own — extracted content can be managed in Studio, translated, and published without touching source code.
+
+---
+
+## Phase 1: Extraction
+
+Extract content from source code into `.contentrain/` without modifying source files.
+
+### Step 1. Check Project State
+
+Call `contentrain_status` to confirm:
+
+- The project is initialized (if not, run the `contentrain-init` skill first).
+- Note supported locales and configured domains.
+- Check for pending changes — resolve them before starting.
+
+### Step 1.5. Understand Content Formats
+
+Call `contentrain_describe_format` to review the storage format for each model kind before deciding how to structure extracted content.
+
+Know the four formats:
+
+- **Dictionary:** Flat key-value JSON. All values are strings. Keys are semantic dot-separated addresses (e.g., `auth.login.button`). No field schema. Path: `{model-id}/{locale}.json`
+- **Collection:** Object-map JSON keyed by auto-generated 12-char hex IDs. Each entry has typed fields. Path: `{model-id}/{locale}.json`
+- **Singleton:** Single JSON object per locale. One instance of typed fields. Path: `{model-id}/{locale}.json`
+- **Document:** Markdown file with frontmatter per slug per locale. Path: `{model-id}/{slug}/{locale}.md`
+
+Understanding these formats is essential for Step 4, where you choose the right model kind for each group of candidates.
+
+### Step 2. Build the Project Graph
+
+Call `contentrain_scan(mode: "graph")` to build the import/component dependency graph.
+
+Use this graph to:
+
+- Understand which components belong to which pages or features.
+- Identify shared components vs page-specific components.
+- Prioritize files by their role in the project (layout, page, component).
+
+### Step 3. Find Candidates
+
+Call `contentrain_scan(mode: "candidates")` iteratively to find hardcoded strings.
+
+The scan returns candidates with file paths, line numbers, string values, and surrounding context. Review candidates by file — not all strings should be extracted.
+
+### Step 4. Evaluate Candidates
+
+This is the intelligence step — you (the agent) make all the decisions:
+
+- **Filter false positives:** Remove CSS values, technical identifiers, import paths, variable names, config values, log messages, and test strings. Refer to `normalize-rules.md` Section 5 for the full heuristics.
+- **Assign domains:** Group candidates by domain (e.g., `marketing`, `blog`, `ui`, `system`).
+- **Determine model types:** Decide the appropriate model kind for each group:
+  - **dictionary** — UI strings, button labels, error messages, validation messages. Flat key-value, all strings, no field schema. Choose this when content is short text with no structured fields.
+  - **singleton** — Page-specific content with structured fields (hero section, features block, pricing header). One instance per locale with typed fields.
+  - **collection** — Repeating items with structured fields (testimonials, FAQs, team members). Multiple entries sharing the same field schema.
+  - **document** — Long-form content with markdown body and typed metadata (blog posts, documentation pages, changelogs).
+- **Structure fields:** Define field names and assign candidate strings to fields.
+
+### Step 5. Write Normalize Plan
+
+After evaluating candidates, write the plan as `.contentrain/normalize-plan.json`:
+
+```json
+{
+  "version": 1,
+  "status": "pending",
+  "created_at": "2026-03-16T12:00:00.000Z",
+  "agent": "claude",
+  "scan_stats": {
+    "files_scanned": 42,
+    "raw_strings": 320,
+    "candidates_sent": 85,
+    "extracted": 28,
+    "skipped": 57
+  },
+  "models": [
+    {
+      "id": "hero-section",
+      "kind": "singleton",
+      "domain": "marketing",
+      "i18n": true,
+      "fields": { "title": { "type": "string", "required": true }, "subtitle": { "type": "string" } }
+    }
+  ],
+  "extractions": [
+    { "value": "Build faster apps", "file": "src/pages/index.vue", "line": 12, "model": "hero-section", "field": "title" }
+  ],
+  "patches": [
+    { "file": "src/pages/index.vue", "line": 12, "old_value": "Build faster apps", "new_expression": "{{ $t('hero.title') }}" }
+  ]
+}
+```
+
+This file is watched by the serve UI — writing it triggers automatic detection.
+
+### Step 6. Open UI for Review
+
+Start the review UI and direct the developer to visually inspect the plan:
+
+1. **Start serve** (if not already running):
+
+```bash
+contentrain serve
+```
+
+2. **Direct the user** to the normalize page:
+
+> "I've prepared a normalize plan with **{N} extractions** across **{M} models**.
+> Review it visually at **http://localhost:3333/normalize** — you can inspect each extraction, see source traces, and preview patches.
+> **Approve** or **Reject** directly from the UI."
+
+3. **Wait for user action.** The UI provides:
+   - Extraction review panel — grouped by model with field mappings
+   - Source trace panel — click any extraction to see its original location
+   - Patch preview panel — see exact source file changes
+   - **Approve & Apply** button — executes the extraction
+   - **Reject** button — deletes the plan
+
+Do NOT proceed to apply unless the user approves (either via UI or explicit confirmation in chat).
+
+4. **Detect the user's decision.** After directing the user to the UI, check the plan file to determine the outcome:
+   - **Plan file exists** (`status: "pending"`) → user has not decided yet — wait
+   - **Plan file deleted + new `contentrain/normalize/extract/*` branch exists** → user approved, extraction applied
+   - **Plan file deleted + no new branch** → user rejected the plan
+
+   If rejected, ask the user what to change and iterate from Step 4 (re-evaluate candidates).
+
+   If approved, proceed to Step 9 (Validate and Submit).
+
+**Alternative (no UI):** If the user prefers terminal-only workflow, present the summary inline and wait for explicit confirmation before proceeding. Skip to Step 7.
+
+### Step 7. Preview Extraction (if not using UI)
+
+Call `contentrain_apply(mode: "extract", dry_run: true)` to generate a preview.
+
+Review the dry-run output:
+
+- Verify model definitions are correct.
+- Verify content assignments are accurate.
+- Check for any missed candidates or misclassifications.
+
+Show the preview to the user.
+
+### Step 8. Execute Extraction
+
+After user approval (via UI or chat), call `contentrain_apply(mode: "extract", dry_run: false)`.
+
+Note: `dry_run` defaults to `true`, so you MUST explicitly set `dry_run: false` to execute.
+
+This creates model definitions and content files in `.contentrain/` on a `contentrain/normalize/extract/{timestamp}` branch. Source files are NOT modified.
+
+If approved via UI, the UI calls this automatically — no additional agent action needed.
+
+### Step 9. Validate and Submit
+
+Call `contentrain_validate` to check the extracted content:
+
+- Schema compliance for all new models and entries.
+- i18n completeness — source locale has all keys.
+- No duplicate entries.
+- Vocabulary alignment.
+
+Call `contentrain_submit` to push the branch for review.
+
+Normalize operations always use `review` workflow mode — changes are never auto-merged.
+
+Tell the user: "Phase 1 complete. Content is now in Contentrain and can be managed, translated, and published from Studio. When ready, proceed with Phase 2 to update source files."
+
+---
+
+## Phase 2: Reuse
+
+Patch source files to replace hardcoded strings with content references. Only start after Phase 1 is reviewed and merged.
+
+### Step 1. Select Scope
+
+List the extracted models and ask the user which model or domain to process first.
+
+Process one model or domain at a time to keep diffs small and reviewable.
+
+### Step 2. Determine Replacement Expressions
+
+Based on the project's tech stack, determine the correct replacement pattern:
+
+| Stack | Pattern | Example |
+|---|---|---|
+| Vue/Nuxt (vue-i18n) | `{{ $t('key') }}` | `{{ $t('hero.title') }}` |
+| React/Next (next-intl) | `{t('key')}` | `{t('hero.title')}` |
+| React/Next (react-intl) | `{intl.formatMessage({id: 'key'})}` | `{intl.formatMessage({id: 'hero.title'})}` |
+| Svelte/SvelteKit | `{$t('key')}` | `{$t('hero.title')}` |
+| Astro | `{t('key')}` | `{t('key')}` |
+| SDK direct import | `query('model').all()` | Direct data access via `#contentrain` |
+
+Also determine any necessary import statements that must be added to patched files (e.g., `import { useTranslation } from 'next-intl'`).
+
+The agent determines the replacement expression — MCP does exact string replacement only.
+
+### Step 3. Preview Reuse
+
+Call `contentrain_apply(mode: "reuse", scope: { model: "<model-id>" }, patches: [...], dry_run: true)`.
+
+The `scope` requires at least one of `model` or `domain`. The `patches` array contains the replacement instructions:
+
+Review the dry-run output:
+
+- Verify each string replacement is correct.
+- Verify import statements will be added where needed.
+- Confirm no non-content strings are being replaced.
+- Check that component structure and behavior are preserved.
+
+Show the preview to the user.
+
+### Step 4. Execute Reuse
+
+After user confirmation, call `contentrain_apply(mode: "reuse", scope: { model: "<model-id>" }, patches: [...], dry_run: false)`.
+
+Note: `dry_run` defaults to `true`, so you MUST explicitly set `dry_run: false` to execute.
+
+This patches source files and creates a `contentrain/normalize/reuse/{model}/{timestamp}` branch.
+
+### Step 5. Validate and Submit
+
+Call `contentrain_validate` to verify:
+
+- Source files parse correctly after patching.
+- Content references resolve to existing entries.
+- No strings were missed or double-replaced.
+
+Call `contentrain_submit` to push the branch for review.
+
+### Step 6. Repeat
+
+Ask the user which model or domain to process next. Repeat steps 1-5 for each remaining model until all extracted content is referenced in source code.
+
+---
+
+## Phase 3: Translation (Optional)
+
+After Phase 1 (extract) and Phase 2 (reuse) are complete:
+
+1. Copy source locale to target locales:
+   ```
+   contentrain_bulk({ operation: "copy_locale", model: "ui-texts", source_locale: "en", target_locale: "tr" })
+   ```
+
+2. Translate each key's value while keeping the key names identical across locales.
+
+3. Re-generate the SDK client:
+   ```bash
+   npx contentrain generate
+   ```
+
+4. The application now serves localized content from the dictionary.
+
+---
+
+## Content Update Workflow
+
+When dictionary content is added or updated:
+
+1. Edit content via MCP (`contentrain_content_save`).
+2. Re-run `contentrain generate` to update the static data modules.
+3. Rebuild the application.
+
+For development, use watch mode:
+
+```bash
+npx contentrain generate --watch
+```
+
+---
+
+## Important Rules
+
+- **ALWAYS dry-run before apply.** Both extract and reuse require a preview step.
+- **Normalize branches always use `review` mode.** Never auto-merge.
+- **Phase 2 requires Phase 1 to be merged.** Content must exist in `.contentrain/` before patching source.
+- **Process reuse one model at a time.** Keep diffs small and reviewable.
+- **MCP is framework-agnostic.** You (the agent) provide all stack-specific replacement expressions.
+- **Do not change component structure.** Only replace string literals with content references.

package/workflows/contentrain-review.md

@@ -0,0 +1,162 @@
+# Skill: Review Pending Content Changes
+
+> Review content changes on Contentrain branches, apply quality checks, and recommend approval or rejection.
+
+---
+
+## When to Use
+
+The user wants to review content quality, audit existing entries, check pending changes, or run a pre-publish checklist. Triggers: "review content", "check pending changes", "review the contentrain branch", "content QA", "audit content", "pre-publish check".
+
+---
+
+## Steps
+
+### 1. Check Project State
+
+Call `contentrain_status` to understand the current project:
+
+- All models, their kinds, domains, and entry counts.
+- Configured locales and source locale.
+- Pending branches or unsubmitted changes.
+- Workflow mode (auto-merge or review).
+
+### 2. List Content for Review
+
+For each model (or the user-specified scope), call `contentrain_content_list(model: "<modelId>", locale: "<locale>")`:
+
+- Retrieve entries for the source locale first.
+- For i18n models, also retrieve entries for each target locale.
+- Note entry counts per locale to identify i18n coverage gaps.
+
+If reviewing a specific branch, list the `contentrain/*` branches and show:
+
+- Branch name (indicates operation type: extract, reuse, content-save, model-save).
+- Number of changed files.
+- Last commit date.
+
+### 3. Run Automated Validation
+
+Call `contentrain_validate` to get the automated validation report:
+
+- Schema compliance errors (missing required fields, type mismatches).
+- Referential integrity issues (broken relation references).
+- i18n completeness gaps (missing locale entries).
+- Content policy violations.
+
+### 4. Apply Quality Checklist
+
+Go through each category and report findings:
+
+#### 4.1 Content Quality (from content-quality.md)
+
+- [ ] All required fields are populated with real, non-placeholder values.
+- [ ] Text fields respect `min`/`max` constraints.
+- [ ] No placeholder text (lorem ipsum, TODO, TBD, [insert here]).
+- [ ] Tone is consistent with `context.json` → `conventions.tone`.
+- [ ] Vocabulary terms from `vocabulary.json` are used consistently.
+- [ ] Collection entries have no duplicate `unique` field values.
+- [ ] Content follows the correct content type pattern (blog post, landing page, docs, etc.).
+- [ ] No duplicate content across entries.
+
+#### 4.2 SEO (from seo-rules.md)
+
+- [ ] Page titles: 50-60 characters (max 70), primary keyword in first 30 characters.
+- [ ] Meta descriptions: 120-160 characters, complete sentences.
+- [ ] Slugs: kebab-case, descriptive, 3-5 words, no stop words.
+- [ ] Heading hierarchy in markdown/richtext: h1 → h2 → h3 (no skips).
+- [ ] Image alt text is present and descriptive (under 125 characters).
+- [ ] No orphan pages (content exists but is not linked/referenced).
+
+#### 4.3 Accessibility (from accessibility-rules.md)
+
+- [ ] Image fields have corresponding alt text fields (or the alt is embedded).
+- [ ] Color contrast: text color values meet WCAG AA ratio if paired colors are in the model.
+- [ ] Link text is descriptive (no raw URLs, "click here", or "read more" without context).
+- [ ] Media content has text alternatives where applicable.
+- [ ] Heading hierarchy is sequential (no skipped levels).
+- [ ] Color is not used as the sole means of conveying information.
+
+#### 4.4 Security (from security-rules.md)
+
+- [ ] No hardcoded secrets, API keys, or credentials in content fields.
+- [ ] No internal URLs or staging domains in production content.
+- [ ] User-generated or external URLs use HTTPS.
+- [ ] No inline JavaScript or script injection vectors in richtext/markdown fields.
+- [ ] No user-supplied HTML that could enable XSS.
+- [ ] Email fields contain valid, non-internal addresses (unless intended).
+
+#### 4.5 i18n Completeness (from i18n-quality.md)
+
+- [ ] All models with `i18n: true` have entries for every supported locale.
+- [ ] Entry counts match across locales (no missing translations).
+- [ ] Required fields are populated in every locale.
+- [ ] Dictionary keys are identical across all locale files.
+- [ ] Vocabulary terms are translated in all locales.
+- [ ] Translations are idiomatic (not word-for-word).
+- [ ] Translated text fits within field `max` constraints.
+- [ ] No source-locale text left untranslated in target locales.
+
+#### 4.6 Referential Integrity
+
+- [ ] All `relation` fields point to existing entries.
+- [ ] All `relations` arrays contain valid references.
+- [ ] No circular relations that could cause infinite loops.
+- [ ] Referenced entries are in a publishable state.
+
+### 5. Generate Review Report
+
+Present a structured report:
+
+```
+## Content Review Report
+
+### Summary
+- Models reviewed: X
+- Total entries: X
+- Locales checked: X
+
+### Issues Found
+
+#### Critical (must fix before publish)
+- [list of blocking issues with field references]
+
+#### Warning (should fix)
+- [list of non-blocking issues]
+
+#### Info (suggestions)
+- [list of improvements]
+
+### Per-Model Breakdown
+| Model | Kind | Entries | Issues | Status |
+|---|---|---|---|---|
+
+### i18n Coverage
+| Locale | Coverage | Missing Entries |
+|---|---|---|
+```
+
+### 6. Make a Recommendation
+
+Based on the findings:
+
+- **Approve:** No errors, few or no warnings. Changes are ready to merge.
+- **Request changes:** Errors or significant warnings found. List the specific changes needed.
+- **Reject:** Fundamental issues (wrong model structure, placeholder-only content, security violations). Explain why and suggest starting over.
+
+### 7. Offer Fixes
+
+For each fixable issue, offer to resolve it:
+
+- Missing translations: offer to run `/contentrain-translate`.
+- Schema violations: offer to update entries with `contentrain_content_save`.
+- Missing required fields: draft content for empty fields.
+- SEO issues: suggest improved titles, descriptions, slugs.
+
+Only make changes after user approval.
+
+### 8. Re-validate
+
+If fixes were applied, call `contentrain_validate` again to confirm all issues are resolved.
+
+Report the final status: "All checks passed" or list remaining issues that require manual attention.