@contentrain/skills 0.1.2 → 0.2.1

package/skills/contentrain-serve/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: contentrain-serve
+description: "Start the local Contentrain review and normalize UI. Use when launching the serve interface, reviewing changes visually, or managing normalize plans."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Review the Project with `contentrain serve`
+
+> Start the local review UI as a bridge between agent and developer.
+
+---
+
+## When to Use
+
+Use this when:
+
+- a normalize plan, branch, or validation result needs developer review
+- the developer wants to browse models, content, or history visually
+- another skill needs to hand off to the UI for approval (normalize, review)
+
+---
+
+## Steps
+
+### 1. Check if Serve is Already Running
+
+Before starting a new instance, check if port 3333 is already in use:
+
+```bash
+lsof -ti:3333
+```
+
+If a process is running, serve is already up — skip to Step 3.
+
+### 2. Start Serve
+
+Run from the project root (where `.contentrain/` lives):
+
+```bash
+contentrain serve
+```
+
+Optional flags:
+
+- `--port` (default: 3333)
+- `--host` (default: localhost)
+- `--open=false` (prevent auto-opening browser)
+- `--stdio` (MCP stdio transport for IDE integration — no web UI)
+
+Wait for the "Contentrain Serve" banner confirming the server is ready.
+
+### 3. Direct the Developer to the Right Page
+
+Based on the current context, tell the developer exactly where to go:
+
+| Context | URL | What to do |
+|---|---|---|
+| Normalize plan ready | `http://localhost:3333/normalize` | Review extractions, approve or reject |
+| Pending branches | `http://localhost:3333/branches` | Review and merge branches |
+| Validation issues | `http://localhost:3333/validate` | Inspect errors and warnings |
+| Content browsing | `http://localhost:3333/content` | Browse entries and models |
+| General overview | `http://localhost:3333` | Dashboard with project stats |
+
+### 4. Wait for Developer Action
+
+After directing the developer to the UI:
+
+- **Normalize flow:** Check `.contentrain/normalize-plan.json` — if deleted, check for new branches to determine approve vs reject
+- **Branch flow:** Check branch list — if branch was merged or deleted, proceed accordingly
+- **Validation flow:** Re-read validation results after developer reviews
+
+The UI communicates back through filesystem changes (plan files, branches, context.json). Poll these to detect the developer's decision.
+
+### 5. Resume the Workflow
+
+After the developer acts in the UI:
+
+- If **approved**: continue with the next step in the calling skill (validate, submit, Phase 2)
+- If **rejected**: ask the developer what to change and iterate
+- If **merged**: confirm and report the final state
+
+Do NOT leave the developer hanging — always follow up after UI interaction.
+
+---
+
+## UI Philosophy
+
+The serve UI is a **monitoring + approval surface**, not an action trigger:
+
+- **Monitoring**: models, content, validation, history, branches — read-only browsing
+- **Approval**: approve/reject normalize plans, merge/delete branches — human decisions
+- **Prompts**: every page shows copyable agent prompts that developers paste into their AI agent
+
+All mutations (create, edit, delete, scan, fix, normalize) are **agent-driven via MCP tools**. The UI never triggers these directly.

package/skills/contentrain-translate/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: contentrain-translate
+description: "Translate Contentrain content across supported locales. Use when adding translations, localizing content, or managing multi-language entries."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Translate Content to a New Locale
+
+> Translate existing content entries to a target locale, following i18n quality rules.
+
+---
+
+## When to Use
+
+The user wants to translate content, add a new language, or says something like "translate to Turkish", "add German locale", "create French translations", "fill in missing translations", "localize".
+
+---
+
+## Steps
+
+### 1. Check Project State
+
+Call `contentrain_status` to understand:
+
+- Supported locales (from `config.json` → `locales.supported`).
+- Source locale (from `config.json` → `locales.source`).
+- Available models and their i18n status.
+- Any pending changes or validation errors.
+
+### 2. Determine Target Locale
+
+If the user specified a locale, use it. Otherwise:
+
+- Ask which locale to translate to.
+- If the target locale is not in `locales.supported`, inform the user it needs to be added to the configuration first.
+
+### 3. Select Models to Translate
+
+Identify which models need translation:
+
+- List all models with `i18n: true`.
+- For each model, call `contentrain_content_list(model: "<modelId>", locale: "<sourceLocale>")` to get the source content.
+- Check which models already have entries in the target locale by calling `contentrain_content_list(model: "<modelId>", locale: "<targetLocale>")`.
+- Report the translation gap: how many entries exist in the source locale but not the target.
+
+Ask the user which models to translate, or offer to translate all models with missing entries.
+
+### 4. Load Vocabulary
+
+Read `.contentrain/vocabulary.json` for canonical term translations. All vocabulary-defined terms must use the exact translation specified for the target locale — do not create alternative translations.
+
+### 5. Translate Following i18n Rules
+
+Apply the rules from `i18n-quality.md` during translation:
+
+#### Translation Quality
+
+- Translate meaning, not words. Produce idiomatic text in the target language.
+- Match the sentence structure of the target language, not the source.
+- Preserve the tone: if the source is casual, the translation must be casual. If formal, stay formal.
+- Fix any machine-translation artifacts: literal translations, incorrect gender agreement, wrong register.
+
+#### Vocabulary Alignment
+
+- Check `.contentrain/vocabulary.json` for approved translations of terms in the target locale.
+- Keep technical terms in their original form if no widely accepted translation exists (API, SDK, CLI, URL).
+- Use brand terms exactly as specified per locale in the vocabulary.
+- Do not alternate between synonyms — use the same translation for repeated terms throughout.
+
+#### Cultural Adaptation
+
+- Adapt idioms, metaphors, and culturally specific references. Do not translate literally when a cultural equivalent exists.
+- Use locale-appropriate date formats, number formats, and units of measurement.
+- Replace culturally specific references with locale-appropriate equivalents.
+- Avoid idioms that do not translate — use target-language equivalents.
+
+#### String Length Awareness
+
+- Check field `max` constraints in the model definition.
+- Account for expansion ratios: German +30-40%, French +15-25%, Chinese -30-50%.
+- If a translation exceeds the field limit, rewrite it shorter. Never truncate mid-word.
+- Pay special attention to UI strings (button labels, menu items) with tight space constraints.
+- Flag any fields that hit `max` constraints.
+
+#### Pluralization
+
+- Use correct CLDR plural categories for the target language.
+- English: `one`, `other`. German: `one`, `other`. Russian: `one`, `few`, `many`, `other`. Arabic: all six categories.
+
+#### Preserve Non-Translatable Content
+
+- Keep relation IDs, slugs, URLs, image paths, and code snippets unchanged — only translate human-readable text.
+- Preserve markdown structure, HTML tags, line breaks, and whitespace patterns from the source.
+- Entry IDs (object-map keys) remain the same across locales.
+
+### 6. Kind-Specific Rules
+
+- **singleton:** Translate all string/text/markdown/richtext fields.
+- **collection:** Translate each entry's fields. Use the same entry IDs across locales.
+- **document:** Translate frontmatter fields and markdown body. Slug may stay the same or be localized (ask the user).
+- **dictionary:** Translate all values. Keys remain identical across locales (e.g., `"auth.login"` key stays the same, value changes).
+
+### 7. Present Translations for Review
+
+Show the user a side-by-side comparison:
+
+```
+Model: hero (singleton)
+Field: title
+  en: "Build faster with AI"
+  tr: "AI ile daha hizli gelistirin"
+
+Field: description
+  en: "Ship content-driven apps in minutes"
+  tr: "Icerik odakli uygulamalari dakikalar icinde yayinlayin"
+```
+
+Wait for user approval. The user may request adjustments to tone, phrasing, or terminology.
+
+### 7.5. Bulk Copy for New Locales
+
+When translating a model to a brand-new locale, use `copy_locale` to bootstrap the target locale with source content before translating:
+
+```
+contentrain_bulk({ operation: "copy_locale", model: "<model-id>", source_locale: "en", target_locale: "<target>" })
+```
+
+This creates target locale files with the source content as a starting point. Then translate each entry's values in-place — keys and entry IDs remain identical.
+
+After all translations are saved, re-generate the SDK client so the application picks up the new locale data:
+
+```bash
+npx contentrain generate
+```
+
+### 8. Save Translations
+
+After approval, call `contentrain_content_save` for each model and target locale:
+
+```
+contentrain_content_save(model: "<model-id>", entries: [
+  { id: "<same-id>", locale: "<target-locale>", data: { ...translatedFields } }
+])
+```
+
+Use the same `id` (for collections) or `slug` (for documents) as the source entry to maintain the cross-locale link. Batch all entries for a model in one call.
+
+### 9. Validate
+
+Call `contentrain_validate` to verify:
+
+- i18n completeness — all source locale keys exist in the target locale.
+- Schema compliance — translated values respect field constraints (`min`, `max`, `pattern`).
+- Vocabulary alignment — vocabulary terms match their canonical translations.
+- Referential integrity — relation fields are unchanged and still valid.
+
+If validation fails, fix issues and re-save.
+
+### 10. Submit
+
+Call `contentrain_submit` to commit the translations:
+
+- Branch: `contentrain/content/{model}/{targetLocale}/{timestamp}`.
+- Each locale can be submitted independently.
+
+### 11. Final Summary
+
+Report to the user:
+
+- Models translated: X.
+- Entries translated: X.
+- Target locale(s): X.
+- Vocabulary terms applied: X.
+- Any fields that hit `max` constraints (flagged for review).
+- Validation result.
+- Submission status.
+- Reminder to review translations for nuance that automated checks cannot catch.
+- Suggestion: run `/contentrain-review` to verify overall i18n coverage.

package/skills/contentrain-validate-fix/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: contentrain-validate-fix
+description: "Validate Contentrain content against model schemas and auto-fix structural issues. Use when checking content validity or fixing validation errors."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Validate and Fix Content Issues
+
+> Diagnose validation failures, apply safe fixes, and re-check the project.
+
+---
+
+## When to Use
+
+Use this when:
+
+- validation reports errors or warnings
+- the user asks to fix schema/content issues
+- a write operation succeeded but the project still needs verification
+
+---
+
+## Steps
+
+### 1. Run Validation
+
+Call `contentrain_validate` first.
+
+Group results into:
+
+- schema/type errors
+- missing required fields
+- relation integrity problems
+- locale completeness issues
+- canonical format warnings
+
+### 2. Decide Auto-fix vs Manual Fix
+
+Auto-fix candidates:
+
+- canonical formatting
+- orphan metadata cleanup
+- structural housekeeping reported by the validator
+
+Manual fix candidates:
+
+- missing required content
+- wrong field values
+- broken relations
+- incorrect slugs/IDs
+
+### 3. Use Auto-fix Carefully
+
+If the issues are structural, run:
+
+```json
+{
+  "fix": true
+}
+```
+
+After that, validate again.
+
+### 4. Fix Semantic Errors
+
+For real content or schema issues:
+
+- inspect the model with `contentrain_describe`
+- patch content with `contentrain_content_save`
+- patch schema with `contentrain_model_save`
+
+Do not claim the project is valid until validation is rerun.
+
+### 5. Re-run Validation
+
+Call `contentrain_validate` again and compare:
+
+- errors reduced to zero
+- remaining warnings acknowledged
+
+### 6. Submit or Recommend Review
+
+If validation is clean:
+
+- call `contentrain_submit` when pending review branches exist
+
+If validation still fails:
+
+- summarize remaining blockers precisely
+- tell the user which model/entry needs manual attention