@contentrain/skills 0.1.1 → 0.2.0

package/skills/contentrain-init/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: contentrain-init
+description: "Initialize a new Contentrain project. Use when setting up .contentrain/ directory, configuring stack and locales, or scaffolding templates."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# 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/skills/contentrain-model/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: contentrain-model
+description: "Design and save Contentrain model definitions. Use when creating models, updating schemas, adding fields, or changing model structure."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# 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/skills/contentrain-normalize/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: contentrain-normalize
+description: "Two-phase normalize flow: extract hardcoded strings from source code into .contentrain/ (Phase 1) and patch source files with content references (Phase 2). Use when normalizing, extracting content, or replacing hardcoded strings."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Contentrain Normalize
+
+Normalize converts a codebase with hardcoded strings into a Contentrain-managed content architecture. It runs in two independent phases, each producing a separate branch for review.
+
+- **Phase 1 (Extraction):** Pull content from source code into `.contentrain/` structure. Source files are NOT modified.
+- **Phase 2 (Reuse):** Patch source files to replace hardcoded strings with content references. Requires completed extraction.
+
+Phase 1 alone is valuable: content becomes manageable in Studio, translatable, and publishable without touching source code.
+
+---
+
+## Two-Phase Architecture
+
+| Aspect | Phase 1: Extraction | Phase 2: Reuse |
+|--------|-------------------|----------------|
+| Purpose | Pull content from source to `.contentrain/` | Patch source files with content references |
+| Scope | Full project scan | Per model or per domain |
+| Source files modified | No | Yes |
+| Branch pattern | `contentrain/normalize/extract/{domain}/{timestamp}` | `contentrain/normalize/reuse/{model}/{locale}/{timestamp}` |
+| Prerequisite | Initialized `.contentrain/` | Completed extraction (content exists in `.contentrain/`) |
+| Workflow mode | Always `review` | Always `review` |
+| Standalone value | Yes -- content is manageable in Studio immediately | Depends on Phase 1 |
+
+---
+
+## Agent vs MCP Responsibilities
+
+### Agent (Intelligence Layer)
+
+- **Decide what is content vs code.** Semantic judgment requiring context understanding.
+- **Assign domain grouping.** Determine which domain each piece of content belongs to.
+- **Determine model structure.** Group related content into models, choose the right kind.
+- **Create replacement expressions.** Stack-specific, requires framework knowledge (Vue/Nuxt, React/Next, Svelte, Astro, SDK).
+- **Filter false positives** from scan candidates.
+- **Evaluate and group** candidates into logical models.
+
+### MCP (Deterministic Infrastructure)
+
+- **Scan the file system** (build graph, find candidates).
+- **Read and write files** in `.contentrain/`.
+- **Patch source files** with exact string replacement (agent provides the replacement expression).
+- **Create branches, commit, validate** all changes.
+- **Enforce guardrails** (file limits, type restrictions, dry-run requirement).
+
+MCP is framework-agnostic. It does NOT know how `{t('key')}` differs from `{{ $t('key') }}`. The agent provides all stack-specific logic.
+
+---
+
+## Guardrails
+
+| Guardrail | Limit | Rationale |
+|-----------|-------|-----------|
+| Allowed source file types | `.vue`, `.tsx`, `.jsx`, `.ts`, `.js`, `.mjs`, `.astro`, `.svelte` | Only scan files that can contain UI content |
+| Max files per scan | 500 | Prevent scanning entire monorepos |
+| Max files per apply | 100 | Keep diffs reviewable |
+| Dry-run before apply | **MANDATORY** | Preview all changes before executing |
+| Workflow mode | Always `review` | Normalize changes are never auto-merged |
+| Reuse scope | Per model or per domain | No whole-project reuse in one operation |
+| Reuse prerequisite | Extraction must be complete | Content must exist in `.contentrain/` before patching source |
+
+Attempting to apply without a prior dry-run will be rejected. Exceeding file limits will truncate results with a warning.
+
+---
+
+## Phase 1: Extraction (Step-by-Step)
+
+### 1. Check Project State
+
+Call `contentrain_status` to confirm the project is initialized and note supported locales. Call `contentrain_describe_format` to understand the four storage formats (dictionary, collection, singleton, document) before deciding model structure.
+
+### 2. Build the Project Graph
+
+Call `contentrain_scan(mode: "graph")` to build the import/component dependency graph. Use this to understand which components belong to which pages, identify shared vs page-specific components, and prioritize files.
+
+### 3. Find Candidates
+
+Call `contentrain_scan(mode: "candidates")` to find hardcoded strings. The scan returns candidates with file paths, line numbers, string values, and surrounding context.
+
+### 4. Evaluate Candidates (Agent Intelligence)
+
+- **Filter false positives:** Remove CSS values, technical identifiers, import paths, variable names, config values, log messages, test strings. See [What Is Content](references/what-is-content.md) for full heuristics.
+- **Assign domains:** Group candidates by domain (e.g., `marketing`, `blog`, `ui`, `system`).
+- **Determine model types:** Choose dictionary, singleton, collection, or document kind for each group.
+- **Structure fields:** Define field names and assign candidate strings to fields.
+
+### 5. Preview Extraction
+
+Call `contentrain_apply(mode: "extract", dry_run: true)` to generate a preview. Review the dry-run output: verify model definitions, content assignments, and check for missed or misclassified candidates. Show the preview to the user.
+
+### 6. Execute Extraction
+
+After user approval, call `contentrain_apply(mode: "extract", dry_run: false)`. This creates model definitions and content files in `.contentrain/` on a `contentrain/normalize/extract/{timestamp}` branch. Source files are NOT modified.
+
+### 7. Validate and Submit
+
+Call `contentrain_validate` to check schema compliance, i18n completeness, and duplicate entries. Call `contentrain_submit` to push the branch for review. Normalize operations always use `review` workflow mode.
+
+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 (Step-by-Step)
+
+Only start after Phase 1 is reviewed and merged.
+
+### 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.
+
+### 2. Determine Replacement Expressions (Agent Intelligence)
+
+Based on the project's tech stack, determine the correct replacement pattern. See [Reuse Details](references/reuse.md) for the full replacement expressions table by stack. Also determine any necessary import statements for patched files.
+
+### 3. Preview Reuse
+
+Call `contentrain_apply(mode: "reuse", scope: { model: "<model-id>" }, patches: [...], dry_run: true)`. Review: verify each replacement is correct, import statements will be added, no non-content strings are being replaced, component structure is preserved.
+
+### 4. Execute Reuse
+
+After user confirmation, call `contentrain_apply(mode: "reuse", scope: { model: "<model-id>" }, patches: [...], dry_run: false)`. This patches source files and creates a `contentrain/normalize/reuse/{model}/{timestamp}` branch.
+
+### 5. Validate and Submit
+
+Call `contentrain_validate` to verify source files parse correctly, content references resolve, and no strings were missed or double-replaced. Call `contentrain_submit` to push the branch for review.
+
+### 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.
+
+---
+
+## Domain and Model Grouping Guidelines
+
+### Domain Assignment
+
+| Content Location | Suggested Domain |
+|------------------|-----------------|
+| Landing page, marketing sections | `marketing` |
+| Blog, articles, posts | `blog` |
+| Navigation, footer, header | `ui` |
+| Error messages, validation | `system` |
+| Product pages, e-commerce | `product` |
+| Documentation, help | `docs` |
+| User-facing app strings | `app` |
+
+### Model Kind Selection
+
+| Content Pattern | Kind | Rationale |
+|----------------|------|-----------|
+| One set of fields per page section | `singleton` | Hero, features, pricing header |
+| Multiple items of same type | `collection` | Team members, FAQs, testimonials |
+| Long-form with metadata | `document` | Blog posts, documentation pages |
+| Key-value UI strings | `dictionary` | Error messages, button labels, form labels |
+
+---
+
+## Common Mistakes
+
+| Mistake | Correct Approach |
+|---------|-----------------|
+| Extracting CSS values as content | Only extract user-visible text |
+| Creating one model per component | Group related content into shared models |
+| Skipping dry-run | ALWAYS preview before apply |
+| Auto-merging normalize changes | Normalize ALWAYS uses review mode |
+| Reusing before extraction is merged | Wait for extraction review and merge first |
+| Processing all models in one reuse | Scope reuse to one model/domain at a time |
+| Ignoring project graph | Use graph output to understand component relationships |
+| Hardcoding replacement patterns | Detect the project's i18n stack and use its conventions |
+| Extracting strings with runtime variables | Split parameterized strings: extract the static part, leave interpolation in code |
+
+---
+
+## References
+
+- [Extraction Details](references/extraction.md) -- Phase 1 extraction rules, parameters, and examples
+- [Reuse Details](references/reuse.md) -- Phase 2 replacement expressions by stack and patching rules
+- [What Is Content](references/what-is-content.md) -- Heuristics for identifying content vs code strings

package/skills/contentrain-normalize/references/extraction.md

@@ -0,0 +1,164 @@
+---
+name: extraction
+description: "Phase 1 extraction details, rules, and examples"
+---
+
+# Phase 1: Extraction Details
+
+Extraction pulls hardcoded content from source code into `.contentrain/` without modifying source files. Each extraction produces a single branch with all extracted content for review.
+
+---
+
+## Extraction Flow
+
+### 1. Build Project Graph
+
+```
+contentrain_scan(mode: "graph")
+```
+
+Returns the import/component dependency graph. Use this 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).
+
+### 2. Find Candidates
+
+```
+contentrain_scan(mode: "candidates")
+```
+
+Returns hardcoded string candidates with file paths, line numbers, and surrounding context. Review candidates by file -- not all strings should be extracted. See [What Is Content](what-is-content.md) for filtering heuristics.
+
+### 3. Agent Evaluation
+
+This is the intelligence step -- the agent makes all decisions:
+
+- **Filter false positives:** Remove CSS values, technical identifiers, import paths, variable names, config values, log messages, and test strings.
+- **Assign domains:** Group candidates by domain (e.g., `marketing`, `blog`, `ui`, `system`).
+- **Determine model types:** Choose the appropriate model kind for each group:
+  - **dictionary** -- UI strings, button labels, error messages. Flat key-value, all strings, no field schema.
+  - **singleton** -- Page-specific content with structured fields (hero section, features block).
+  - **collection** -- Repeating items with structured fields (testimonials, FAQs, team members).
+  - **document** -- Long-form content with markdown body and typed metadata (blog posts, docs).
+- **Structure fields:** Define field names and assign candidate strings to fields.
+
+### 4. Write Normalize Plan
+
+After evaluation, 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.
+
+### 5. Preview Extraction
+
+```
+contentrain_apply(mode: "extract", dry_run: true)
+```
+
+Returns a preview of what will be created in `.contentrain/` without making changes. Review the output:
+
+- Verify models are structured correctly.
+- Verify content assignments are accurate.
+- Check for missing or misclassified candidates.
+
+### 6. Execute Extraction
+
+```
+contentrain_apply(mode: "extract", dry_run: false)
+```
+
+Creates model definitions and content files in `.contentrain/` on a `contentrain/normalize/extract/{timestamp}` branch. `dry_run` defaults to `true`, so you MUST explicitly set `dry_run: false` to execute.
+
+### 7. Validate and Submit
+
+```
+contentrain_validate
+contentrain_submit
+```
+
+Submit always uses `review` mode for normalize operations.
+
+---
+
+## Extraction Rules
+
+- Extraction creates content in `.contentrain/` but does NOT modify source files.
+- Each extraction produces a single branch with all extracted content.
+- Group related content into the fewest models that make semantic sense.
+- Prefer **dictionary** kind for UI labels and error messages.
+- Prefer **singleton** kind for page-specific content (hero, features).
+- Prefer **collection** kind for repeating items (team members, FAQs, testimonials).
+- Prefer **document** kind for long-form content with markdown body.
+
+---
+
+## Group Related Content Guidelines
+
+When grouping candidates into models:
+
+- Content from the same page section should go into the same model.
+- Shared UI strings (navigation, footer, error messages) should be grouped into a single dictionary per domain.
+- Do not create one model per component -- group related content into shared models.
+- Use the project graph to understand component relationships and group accordingly.
+- If multiple components share the same type of content (e.g., all cards have a title and description), consider a single collection model.
+
+---
+
+## Content Format Reference
+
+Understand these formats before choosing model kinds:
+
+| Kind | Format | Keys | Example Path |
+|------|--------|------|-------------|
+| Dictionary | Flat key-value JSON, all strings | Semantic dot-separated addresses | `{model-id}/{locale}.json` |
+| Collection | Object-map JSON by 12-char hex ID | Auto-generated entry IDs | `{model-id}/{locale}.json` |
+| Singleton | Single JSON object per locale | Typed field names | `{model-id}/{locale}.json` |
+| Document | Markdown with frontmatter per slug | Slug-based file names | `{model-id}/{slug}/{locale}.md` |
+
+Call `contentrain_describe_format` before deciding model structure to see the exact format for each kind.