@contentrain/skills 0.1.2 → 0.2.1

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.

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

@@ -0,0 +1,146 @@
+---
+name: reuse
+description: "Phase 2 reuse details, replacement expressions by stack, and patching rules"
+---
+
+# Phase 2: Reuse Details
+
+Reuse patches source files to replace hardcoded strings with content references. Only start after Phase 1 (extraction) is reviewed and merged. Content must exist in `.contentrain/` before patching source files.
+
+---
+
+## Reuse Flow
+
+### 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
+
+Based on the project's tech stack, determine how source files should reference content. The agent determines the replacement expression -- MCP does exact string replacement only.
+
+Also determine any necessary import statements that must be added to patched files (e.g., `import { useTranslation } from 'next-intl'`).
+
+### 3. Preview Reuse
+
+```
+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.
+
+### 4. Execute Reuse
+
+```
+contentrain_apply(mode: "reuse", scope: { model: "<model-id>" }, patches: [...], dry_run: false)
+```
+
+`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.
+
+### 5. Validate and Submit
+
+```
+contentrain_validate
+contentrain_submit
+```
+
+Verify source files parse correctly after patching, content references resolve to existing entries, and no strings were missed or double-replaced.
+
+### 6. Repeat
+
+Repeat steps 1-5 for each remaining model or domain until all extracted content is referenced in source code.
+
+---
+
+## Replacement Expressions by Stack
+
+| Stack | Template Pattern | Attribute Pattern | Script Pattern | Example |
+|-------|-----------------|-------------------|----------------|---------|
+| Vue/Nuxt (vue-i18n) | `{{ $t('key') }}` | `:attr="$t('key')"` | `t('key')` | `{{ $t('hero.title') }}` |
+| React/Next (next-intl) | `{t('key')}` | `{t('key')}` | `t('key')` | `{t('hero.title')}` |
+| React/Next (react-intl) | `{intl.formatMessage({id: 'key'})}` | `{intl.formatMessage({id: 'key'})}` | `intl.formatMessage({id: 'key'})` | `{intl.formatMessage({id: 'hero.title'})}` |
+| Svelte/SvelteKit | `{$t('key')}` | `{$t('key')}` | `$t('key')` | `{$t('hero.title')}` |
+| Astro | `{t('key')}` | `{t('key')}` | `t('key')` | `{t('hero.title')}` |
+| SDK direct import | `{data.field}` | `{data.field}` | `query('model').first()` | Direct data access via `#contentrain` |
+
+### Import Statements by Stack
+
+When patching files, ensure the necessary imports or setup code are added:
+
+| Stack | Required Import/Setup |
+|-------|----------------------|
+| Vue/Nuxt (vue-i18n) | `const { t } = useI18n()` in `<script setup>` |
+| React/Next (next-intl) | `import { useTranslations } from 'next-intl'` + `const t = useTranslations()` |
+| React/Next (react-intl) | `import { useIntl } from 'react-intl'` + `const intl = useIntl()` |
+| Svelte/SvelteKit | `import { t } from '$lib/i18n'` (project-specific) |
+| Astro | `import { t } from '@/i18n'` (project-specific) |
+| SDK direct import | `import { query } from '#contentrain'` |
+
+Detect the project's existing i18n setup and match its import conventions. Do not introduce new i18n libraries.
+
+---
+
+## Reuse Rules
+
+1. **One model at a time.** Do NOT reuse the entire project in one operation. Keep diffs small and reviewable.
+
+2. **Ensure i18n is configured.** The i18n/content library must be properly configured in the project before reuse. Check for existing i18n setup.
+
+3. **Add necessary imports.** Every patched file must have the required import statements and setup code (composable import, hook call, etc.).
+
+4. **Do NOT change component structure.** Only replace string literals with content references. Do not modify component behavior, layout, or logic.
+
+5. **Include setup code.** If a source file requires setup code (composable import, hook call), include it in the patch.
+
+6. **Handle attribute bindings.** When replacing strings in HTML attributes (e.g., `placeholder="Search"`), use the correct attribute binding syntax for the stack (e.g., `:placeholder="$t('search')"` in Vue).
+
+7. **Preserve surrounding markup.** Do not add or remove HTML tags, change class names, or alter component props beyond the string replacement.
+
+---
+
+## Reuse Patch Example
+
+```json
+{
+  "mode": "reuse",
+  "scope": { "model": "ui-texts" },
+  "dry_run": false,
+  "patches": [
+    {
+      "file": "src/components/Header.vue",
+      "line": 15,
+      "old_value": "Sign in",
+      "new_expression": "{{ $t('ui.sign-in') }}"
+    },
+    {
+      "file": "src/components/Header.vue",
+      "line": 22,
+      "old_value": "Sign up",
+      "new_expression": "{{ $t('ui.sign-up') }}"
+    }
+  ],
+  "imports": [
+    {
+      "file": "src/components/Header.vue",
+      "statement": "const { t } = useI18n()",
+      "location": "script-setup"
+    }
+  ]
+}
+```
+
+---
+
+## Edge Cases
+
+- **Strings in script blocks:** Use the script pattern (no template delimiters). Example: `const label = t('key')` not `const label = {{ $t('key') }}`.
+- **Strings in computed properties:** Wrap in the computed function body using the script pattern.
+- **Conditional content:** If a string appears inside a ternary or conditional, replace only the string literal, not the condition.
+- **Multi-line strings:** Replace the entire multi-line string as one unit. Do not split across multiple patches.

package/skills/contentrain-normalize/references/what-is-content.md

@@ -0,0 +1,115 @@
+---
+name: what-is-content
+description: "Heuristics for identifying content vs code strings in source files"
+---
+
+# What Is Content
+
+Use these heuristics to identify content strings in source code. Content is user-visible text that should be managed separately from code. Accurate classification is critical -- extracting code strings as content breaks the application, while missing content strings leaves hardcoded text unmanageable.
+
+---
+
+## Extract These
+
+These string types are user-visible content and should be extracted:
+
+- **Headings and titles** in templates/JSX (`<h1>`, `<h2>`, etc.)
+- **Paragraph text** and body copy
+- **Button labels** (`<button>Submit</button>`)
+- **Link text** (`<a>Learn more</a>`)
+- **Form labels and placeholders** (`<label>`, `placeholder="..."`)
+- **Error messages** shown to users
+- **Success/notification messages**
+- **Alt text** on images (`alt="..."`)
+- **ARIA labels** (`aria-label="..."`)
+- **Meta descriptions and page titles** (`<title>`, `<meta name="description">`)
+- **Navigation items** (menu labels, breadcrumbs)
+- **Tooltip text**
+- **Empty state messages** ("No results found")
+- **CTA (call-to-action) text**
+
+---
+
+## Do NOT Extract These
+
+These string types are code infrastructure and must remain in source:
+
+- CSS class names, HTML IDs
+- Variable names, function names, parameter names
+- Technical identifiers (API endpoints, route paths, event names)
+- Import paths and file paths
+- Numbers used as constants (port numbers, HTTP status codes, pixel dimensions, timeouts)
+- Strings shorter than 3 characters (unless semantically meaningful: "OK", "No", "Yes")
+- Regular expressions
+- Configuration values (environment variables, feature flags)
+- Log messages (internal, not user-facing)
+- Code comments
+- Test assertion strings
+- JSON keys
+- Enum values used as code identifiers (not displayed to users)
+
+---
+
+## Dictionary Interpolation Limitation
+
+Strings containing dynamic expressions (`${variable}`, template literals with runtime values) cannot be stored in dictionaries. These must remain as hardcoded expressions in source code.
+
+### CANNOT Extract
+
+- `"Add a new entry to ${modelId}"` -- contains runtime variable
+- `` `Hello, ${user.name}!` `` -- template literal with variable
+
+### CAN Extract
+
+- `"Add a new entry"` -- static string (parameterize separately if needed)
+- `"Hello, World!"` -- no runtime variables
+
+### Handling Parameterized Strings
+
+Split parameterized strings: extract the static template pattern and leave the interpolation in code.
+
+```
+// Instead of: `"Add a new entry to ${modelId}"`
+// Extract: dictionary key "add-entry-to" = "Add a new entry to"
+// Code: `${t['add-entry-to']} ${modelId}`
+```
+
+For i18n frameworks that support interpolation (e.g., `{count} items`), use the framework's built-in interpolation syntax instead of string concatenation. Check the project's i18n library documentation.
+
+---
+
+## Edge Cases
+
+| String | Extract? | Reason |
+|--------|----------|--------|
+| `"OK"` | Yes | User-visible confirmation |
+| `"px"` | No | CSS unit, not content |
+| `"Loading..."` | Yes | User-visible state message |
+| `"GET"` | No | HTTP method, technical |
+| `"en"` | No | Locale code, technical |
+| `"Submit Form"` | Yes | User-visible button label |
+| `"/api/users"` | No | API endpoint |
+| `"flex"` | No | CSS value |
+| `"user.name"` | No | Object property path |
+| `"An error occurred"` | Yes | User-facing error message |
+| `"true"` / `"false"` | No | Boolean string, technical |
+| `"none"` | No | CSS/config value |
+| `"No results found"` | Yes | User-visible empty state |
+| `"application/json"` | No | MIME type, technical |
+| `"Welcome back!"` | Yes | User-visible greeting |
+| `"div"` | No | HTML tag name, technical |
+| `"default"` | No | Config/switch value, technical |
+
+---
+
+## Decision Framework
+
+When uncertain whether a string is content, ask these questions in order:
+
+1. **Is this string displayed to the end user?** If no, do not extract.
+2. **Would this string need to change for a different locale?** If yes, extract.
+3. **Would a content editor reasonably want to update this text?** If yes, extract.
+4. **Does this string serve a technical function (routing, config, API)?** If yes, do not extract.
+5. **Is this string used as an identifier in code logic?** If yes, do not extract.
+
+If the answer is still unclear after these questions, err on the side of NOT extracting. It is safer to leave a string hardcoded than to extract a technical identifier.

package/skills/contentrain-quality/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: contentrain-quality
+description: "Content quality, SEO, accessibility, and media rules for Contentrain projects. Use when reviewing content quality, checking SEO, or validating media assets."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Contentrain Quality
+
+Quality rules govern how AI agents create, edit, and review content in Contentrain projects. These rules ensure every piece of content meets standards for writing quality, SEO, accessibility, and media optimization before publication.
+
+---
+
+## Quick Checklist
+
+Before committing any content, verify all of the following:
+
+- [ ] Heading hierarchy is sequential (H1 -> H2 -> H3, no skips)
+- [ ] Exactly one H1 per page
+- [ ] Title is 50-60 characters, primary keyword within first 30 chars, unique
+- [ ] Description is 120-160 characters, complete sentence, unique, differs from title
+- [ ] No placeholder text anywhere (no Lorem ipsum, TODO, TBD, [insert here])
+- [ ] No duplicate content across entries in the same collection
+- [ ] Tone matches `context.json > conventions.tone` configuration
+- [ ] All terms match `vocabulary.json` (canonical terms, brand terms, no forbidden terms)
+- [ ] All field constraints (length, pattern, required, unique) are satisfied
+- [ ] Content follows the correct content type pattern (blog, landing page, docs, etc.)
+- [ ] System fields (`id`, `createdAt`, `updatedAt`, `status`, `order`) are not in write payload
+- [ ] Slug is lowercase, hyphenated, 3-5 words, no special characters
+- [ ] All images have descriptive alt text (max 125 chars) or empty string for decorative
+- [ ] OG/social fields populated if model supports them
+- [ ] Media files follow naming conventions and size limits
+
+---
+
+## Key Writing Rules
+
+### Heading Hierarchy
+
+- Exactly ONE H1 per page (the page/entry title).
+- Follow sequential order: H1 -> H2 -> H3 -> H4. Never skip levels.
+- Every heading must have content beneath it. No empty sections.
+
+### Titles
+
+- Length: 50-60 characters. Measure before committing.
+- Place the primary keyword within the first 30 characters.
+- Use action-oriented phrasing: "Build a REST API" not "REST API Overview".
+- No clickbait, no ALL CAPS. Every title must be unique within its collection.
+
+### Descriptions and Excerpts
+
+- Length: 120-160 characters. Must be a complete sentence ending with a period.
+- Summarize the VALUE the reader gets, not the process of writing.
+- Must differ from the title.
+
+### Body Content
+
+- Active voice preferred. Target reading grade 8-10.
+- Paragraphs: 3-5 sentences each. One idea per paragraph.
+- Front-load key information in each paragraph.
+
+### Lists
+
+- Parallel grammatical structure across all items.
+- Ordered lists for sequential steps, unordered for non-sequential items.
+- Minimum 2 items in any list.
+
+### Prohibitions
+
+- No placeholder text: Lorem ipsum, TODO, TBD, [insert here], empty required fields.
+- No duplicate content: titles, descriptions, and text blocks must be unique within a collection.
+
+---
+
+## Tone Configuration
+
+### Reading Context
+
+Before writing any content, check these files:
+
+1. **`.contentrain/context.json`** -- Read `conventions.tone` and match the specified tone exactly. If absent, default to neutral professional.
+2. **`.contentrain/vocabulary.json`** -- Use canonical terms exactly as defined. Respect `brand_terms` casing. Never use `forbidden_terms`. If vocabulary does not exist, maintain internal consistency.
+
+### Content Type Voice Mapping
+
+| Content Type | Voice | Characteristics |
+|---|---|---|
+| Marketing / Landing pages | Persuasive | Benefit-focused, confident, action-oriented, second person ("you") |
+| Documentation / Guides | Instructional | Step-by-step, precise, imperative mood ("Run the command") |
+| Error messages | Empathetic | Solution-oriented, no blame, explain what happened and what to do |
+| UI labels | Concise | Consistent terminology, sentence case, no articles unless needed |
+| Blog posts | Conversational-professional | Engaging, informative, first person plural ("we") acceptable |
+| Changelogs | Factual | Past tense, specific, version-referenced, no marketing language |
+
+### Consistency
+
+- Do not shift tone mid-entry.
+- Do not mix second person ("you") and third person ("the user") within the same entry.
+- Maintain consistent use of contractions per project tone.
+
+---
+
+## Content Lifecycle States
+
+Content moves through four states with specific requirements at each:
+
+### Draft
+
+- Focus on completeness over polish.
+- ALL required fields must have real values -- no placeholders.
+- Flag any fields the agent could not confidently populate.
+
+### Review
+
+- Vocabulary compliance: every term matches `vocabulary.json`.
+- Tone consistency: matches configured tone throughout.
+- Factual accuracy: all claims and references are verifiable.
+- Cross-locale coverage: all target locales have corresponding entries.
+- Field constraint compliance: all values within defined bounds.
+
+### Published
+
+ALL of the following must be true:
+
+- Every required field is populated with final content.
+- Every supported locale has a complete translation.
+- Zero placeholder text anywhere.
+- All relation fields reference existing, published entries.
+- SEO fields (title, description, slug) are populated and valid.
+- Content passes tone and vocabulary checks.
+
+### Archived
+
+Move content to archived status when:
+
+- It references deprecated features, APIs, or products.
+- Dates or events referenced are more than 12 months past.
+- The content has been superseded by a newer entry.
+- Statistics or data points are outdated and cannot be updated.
+
+Never delete content. Archive it. Deletion is a manual human decision.
+
+---
+
+## Content Type Patterns
+
+### Blog Post (document kind)
+
+Hook opening -> Context paragraph -> Scannable body with H2/H3 -> Conclusion -> CTA. Do not start with "In this article, we will discuss..."
+
+### Landing Page (singleton kind)
+
+Hero statement (max 10 words) -> Problem -> Solution -> Features (3-6) -> Social proof -> CTA.
+
+### Documentation (document kind)
+
+Prerequisites callout -> Overview -> Step-by-step instructions -> Expected result -> Troubleshooting (min 2 items).
+
+### Error Messages (dictionary kind)
+
+What happened -> Why -> How to fix. No blame language, no technical jargon, no naked error codes.
+
+### Form Labels (dictionary kind)
+
+Noun or noun phrase, sentence case, no trailing colons. Helper text: one sentence with format requirements.
+
+### Navigation Items (dictionary kind)
+
+1-2 words maximum. Verbs for actions, nouns for destinations. No abbreviations.
+
+---
+
+## References
+
+- [Content Quality](references/content-quality.md) -- Detailed content writing rules, structure, tone, content type patterns, lifecycle
+- [SEO Rules](references/seo.md) -- SEO optimization rules for content fields, meta tags, and structured data
+- [Accessibility](references/accessibility.md) -- Accessibility rules for content: alt text, ARIA, color contrast, reading level
+- [Media Rules](references/media.md) -- Media asset rules: image optimization, video handling, file naming conventions