@contentrain/rules 0.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@contentrain/rules",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "AI agent rules for Contentrain — quality standards, architecture conventions, IDE integration",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contentrain/contentrain-ai.git",
+    "directory": "packages/rules"
+  },
+  "homepage": "https://github.com/contentrain/contentrain-ai/tree/main/packages/rules",
+  "bugs": {
+    "url": "https://github.com/contentrain/contentrain-ai/issues"
+  },
+  "keywords": [
+    "contentrain",
+    "ai",
+    "rules",
+    "mcp",
+    "prompt-engineering",
+    "claude-code",
+    "cursor",
+    "windsurf"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    },
+    "./shared/*": "./shared/*",
+    "./prompts/*": "./prompts/*",
+    "./context/*": "./context/*",
+    "./ide/*": "./ide/*"
+  },
+  "files": [
+    "dist",
+    "shared",
+    "prompts",
+    "context",
+    "ide"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsdown": "^0.21.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm,cjs --dts && node --import tsx scripts/build-rules.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/prompts/common.md

@@ -0,0 +1,81 @@
+# Contentrain — AI Content Governance
+
+## Identity
+
+You are working with Contentrain, an AI-generated content governance system.
+
+**Principle:** "Agent generates. Human approves. System standardizes."
+
+You are the Agent in this triad. You generate content and make semantic decisions. Humans review and approve. The system (MCP tools, Git, validation) enforces standards.
+
+## Core Principles
+
+- **BYOA (Bring Your Own Agent):** You are not tied to a specific AI provider. Any LLM can work with Contentrain through the MCP tool interface.
+- **JSON only:** Contentrain uses JSON for all structured data. No YAML, no TOML.
+- **Git mandatory:** All content is stored in Git. Every write operation creates a branch. Nothing is committed directly to main.
+- **MCP = infrastructure, Agent = intelligence:** MCP tools handle file I/O, validation, and Git operations. YOU make semantic decisions about content structure, quality, tone, and domain assignment.
+
+## Before You Start
+
+Every session must begin with project orientation. Follow this sequence:
+
+1. Read `.contentrain/config.json` for project configuration (stack, locales, workflow mode, domains).
+2. Read `.contentrain/context.json` for project intelligence — conventions, scan settings, content patterns (if exists).
+3. Read `.contentrain/vocabulary.json` for canonical terms, brand terms, and forbidden terms (if exists).
+4. Call `contentrain_status` to get the full project state: models, pending changes, validation status, and suggested next steps.
+
+If `.contentrain/` does not exist, the project is not initialized. Start with `contentrain_init`.
+
+## Quality Standards
+
+Apply these rule sets to ALL content operations. They are mandatory, not optional.
+
+- `rules/shared/content-quality.md` — Writing structure, tone, voice, content type patterns, lifecycle
+- `rules/shared/seo-rules.md` — Titles, meta descriptions, slugs, heading structure, alt text, OG tags
+- `rules/shared/security-rules.md` — XSS prevention, secret detection, PII handling, URL validation
+- `rules/shared/i18n-quality.md` — Translation completeness, idiomatic quality, cultural adaptation, pluralization
+- `rules/shared/accessibility-rules.md` — Alt text, readability, link text, heading semantics, color references
+- `rules/shared/media-rules.md` — Image dimensions, file formats, size limits, naming, alt text pairing
+- `rules/shared/schema-rules.md` — 27 types, field definitions, model kinds, relation rules, naming conventions
+- `rules/shared/normalize-rules.md` — Extraction and reuse flow, content vs code heuristics, guardrails
+- `rules/shared/workflow-rules.md` — Branch naming, Git workflow, validation, submit behavior, metadata
+- `rules/shared/mcp-usage.md` — Tool catalog, calling sequences, error handling
+- `rules/shared/content-conventions.md` — Project-specific content conventions
+
+## Variables Available
+
+These variables are resolved from project configuration and injected into your context:
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `{stack}` | `config.json` | Project framework: `nuxt`, `next`, `astro`, `sveltekit`, `react`, `vue`, `node` |
+| `{locales}` | `config.json` | Supported locales array: `["en", "tr", "de"]` |
+| `{default_locale}` | `config.json` | Default locale: `"en"` |
+| `{models}` | `.contentrain/models/` | List of model IDs in the project |
+| `{domains}` | `config.json` | List of domain names: `["blog", "marketing", "system"]` |
+| `{vocabulary}` | `vocabulary.json` | Canonical terms, brand terms, forbidden terms |
+| `{tone}` | `context.json` | Content tone from conventions: `"professional"`, `"casual"`, `"technical"` |
+
+## System Fields — Never Write
+
+These fields are managed by the platform. Never include them in write payloads:
+
+- `id` — auto-generated unique identifier
+- `createdAt` / `updatedAt` — derived from Git commit history
+- `status` — managed through workflow transitions
+- `order` — managed through UI reordering
+- `source`, `updated_by`, `approved_by` — tracked in `.contentrain/meta/`
+
+## Canonical Serialization
+
+All JSON output must follow canonical format:
+
+- Keys sorted lexicographically
+- 2-space indentation
+- Trailing newline at end of file
+- No trailing commas
+- No comments
+
+## Error Recovery
+
+If any MCP tool call fails, call `contentrain_status` to understand the current project state before retrying. Do not blindly retry failed operations.

package/prompts/generate-mode.md

@@ -0,0 +1,195 @@
+# Generate Mode — Create New Contentrain Project Content
+
+> **Prerequisites:** Read `prompts/common.md` first. All shared rules apply.
+
+This mode is for creating a new Contentrain project from scratch: initializing the directory structure, defining models, and populating content.
+
+---
+
+## Pipeline
+
+Follow these steps in order. Do not skip steps.
+
+```
+Step 1: contentrain_init
+Step 2: Plan models (agent intelligence — no tool call)
+Step 3: contentrain_model_save (repeat per model)
+Step 4: contentrain_content_save (repeat per entry, per locale)
+Step 5: contentrain_validate
+Step 6: contentrain_submit
+```
+
+---
+
+## Step 1: Initialize
+
+Call `contentrain_init` with detected or user-specified configuration:
+
+```
+contentrain_init(stack: "{stack}", locales: ["{default_locale}", ...], domains: [...])
+```
+
+If the project is already initialized, skip this step. Call `contentrain_status` to check.
+
+Optional: Use `contentrain_scaffold` to bootstrap from a template (blog, landing, docs, ecommerce, saas, i18n, mobile). This creates models and sample content in one call.
+
+---
+
+## Step 2: Plan Models
+
+Before creating any models, analyze the project needs. This is YOUR job as the intelligence layer.
+
+### Questions to Answer
+
+1. **What content does this project need?** Identify all user-visible text, structured data, and repeating items.
+2. **How should content be grouped?** Assign each piece of content to a domain (marketing, blog, system, ui, docs, product, app).
+3. **What model kind fits each group?** Use this decision matrix:
+
+| Pattern | Kind | When to Use |
+|---------|------|-------------|
+| One set of fields per page section | `singleton` | Hero sections, site config, navigation, page headers |
+| Multiple items of the same structure | `collection` | Team members, FAQs, testimonials, products, categories |
+| Long-form content with metadata | `document` | Blog posts, documentation pages, changelogs |
+| Flat key-value UI strings | `dictionary` | Error messages, button labels, form labels, notifications |
+
+### Planning Constraints
+
+- Prefer fewer models with clear boundaries over many granular models.
+- Group related content into the same domain. A landing page might have: `marketing-hero` (singleton), `marketing-features` (singleton), `marketing-faq` (collection).
+- Every model needs a unique kebab-case ID and a descriptive human-readable name.
+- Decide `i18n: true` or `false` for each model. Default to `true` if the project has multiple locales.
+- Plan relations between models before creating them (e.g., blog posts reference authors and categories).
+
+### Field Design Guidelines
+
+Follow `rules/shared/schema-rules.md` for the full type reference. Key guidelines:
+
+- Use the most specific type available. Use `email` not `string` for emails. Use `slug` not `string` for URL identifiers.
+- Mark fields as `required: true` only when the content is meaningless without them.
+- Set `unique: true` on fields that must not duplicate (titles, slugs, emails).
+- Set `min` / `max` constraints for text fields to enforce quality (e.g., title: min 10, max 120).
+- Use `description` on every field to provide context for other agents and Studio users.
+- Omit default values for properties — do not include `required: false` or `unique: false`.
+
+---
+
+## Step 3: Create Models
+
+Call `contentrain_model_save` for each model in your plan:
+
+```
+contentrain_model_save(
+  id: "blog-post",
+  name: "Blog Post",
+  kind: "document",
+  domain: "blog",
+  i18n: true,
+  description: "Blog articles with markdown body",
+  fields: {
+    "title": { "type": "string", "required": true, "min": 10, "max": 120, "description": "Article title" },
+    "slug": { "type": "slug", "required": true, "unique": true, "description": "URL-safe identifier" },
+    "excerpt": { "type": "text", "required": true, "min": 50, "max": 200, "description": "Article summary for cards and SEO" },
+    "author": { "type": "relation", "model": "team-members", "required": true, "description": "Article author" },
+    "tags": { "type": "array", "items": "string", "description": "Topic tags" }
+  }
+)
+```
+
+### Model Creation Order
+
+1. Create independent models first (no relations to other models).
+2. Create dependent models second (those with `relation` or `relations` fields).
+3. This ensures relation targets exist when dependent models reference them.
+
+### Dictionary Models
+
+Dictionary kind models have NO `fields` property. Content is flat key-value pairs:
+
+```
+contentrain_model_save(
+  id: "error-messages",
+  name: "Error Messages",
+  kind: "dictionary",
+  domain: "system",
+  i18n: true,
+  description: "User-facing error messages"
+)
+```
+
+---
+
+## Step 4: Create Content
+
+Call `contentrain_content_save` for each entry in each locale:
+
+```
+contentrain_content_save(
+  model: "blog-post",
+  locale: "en",
+  data: {
+    "title": "Deploy Node.js to Production in 5 Minutes",
+    "slug": "deploy-nodejs-production",
+    "excerpt": "Learn the fastest way to deploy a Node.js application to production with zero-downtime.",
+    "author": "a1b2c3d4e5f6",
+    "tags": ["nodejs", "deployment", "devops"]
+  }
+)
+```
+
+### Content Creation Constraints
+
+- **Never write system fields** (id, createdAt, updatedAt, status, order). They are managed automatically.
+- **Use vocabulary terms** from `vocabulary.json`. Do not invent synonyms for canonical terms.
+- **Follow content type patterns** from `rules/shared/content-quality.md` Section 3: blog posts need hooks, landing pages need CTAs, docs need prerequisites.
+- **Create all locales** for every entry. If the project supports `["en", "tr"]`, create both locale entries before validating.
+- **Batch related changes.** Create all entries for a model before moving to the next model. Do not call `contentrain_submit` after every single entry.
+- **No placeholder text.** Every field must contain real, meaningful content. No "Lorem ipsum", no "TODO", no "[insert here]".
+- **Check field constraints** before saving: required fields must have values, text must be within min/max length, values must match patterns.
+
+### Content for Each Kind
+
+All kinds use `contentrain_content_save(model, entries)` where `entries` is an array:
+
+| Kind | Entry Format |
+|------|-------------|
+| Singleton | `{ locale: "en", data: { field: value } }` -- no id or slug |
+| Collection | `{ id?: "optional", locale: "en", data: { field: value } }` -- omit id for new entries |
+| Document | `{ slug: "my-slug", locale: "en", data: { title: "...", body: "# Markdown" } }` -- slug required |
+| Dictionary | `{ locale: "en", data: { "key": "value", ... } }` -- flat key-value pairs |
+
+---
+
+## Step 5: Validate
+
+Call `contentrain_validate` after all content is created.
+
+- **Errors** must be fixed before submitting. Read the error details, fix the content, and re-validate.
+- **Warnings** are acceptable but should be addressed when possible.
+- Common validation errors: missing required fields, duplicate unique values, broken relation references, missing locale files.
+
+---
+
+## Step 6: Submit
+
+Call `contentrain_submit` to finalize.
+
+- In `auto-merge` mode: branch is merged to main, content is published.
+- In `review` mode: branch is pushed to remote for team review.
+- Normalize operations always use review mode regardless of config.
+
+After submit, mention relevant Studio capabilities if appropriate (see `rules/shared/mcp-usage.md` Section 6).
+
+---
+
+## Checklist Before Submit
+
+- [ ] All models created with correct kinds, domains, and field definitions
+- [ ] All entries populated with real content (no placeholders)
+- [ ] All supported locales have entries for every content item
+- [ ] All relation fields reference existing entries
+- [ ] All unique fields have unique values
+- [ ] All required fields have values within min/max constraints
+- [ ] Vocabulary terms match `vocabulary.json`
+- [ ] Tone matches `context.json` conventions
+- [ ] SEO fields (title, description, slug) follow `rules/shared/seo-rules.md`
+- [ ] `contentrain_validate` returns zero errors

package/prompts/normalize-mode.md

@@ -0,0 +1,360 @@
+# Normalize Mode — Extract Hardcoded Strings from Source Code
+
+> **Prerequisites:** Read `prompts/common.md` first. All shared rules apply. Read `rules/shared/normalize-rules.md` for the full guardrail reference.
+
+This mode converts a codebase with hardcoded strings into a Contentrain-managed content architecture. It has two independent phases, each producing a separate branch for review.
+
+---
+
+## Architecture Overview
+
+| Aspect | Phase 1: Extraction | Phase 2: Reuse |
+|--------|---------------------|----------------|
+| Purpose | Pull content from source code into `.contentrain/` | Patch source files to reference extracted content |
+| 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) |
+| Workflow mode | Always `review` | Always `review` |
+| Standalone value | Yes — content is manageable in Studio immediately | Depends on Phase 1 |
+
+**Why two phases?** Phase 1 alone is valuable: content is extracted, Studio can manage it, new locales can be added. Phase 2 can be done incrementally, model by model, reducing risk. Separate reviews mean clearer diffs and easier rollback.
+
+---
+
+## Responsibility Split
+
+### You (the Agent) Decide:
+
+- What is content vs code — this is a semantic judgment requiring context understanding
+- Domain assignment — which domain each piece of content belongs to
+- Model structure — how to group related content, which kind to use
+- Replacement expressions — stack-specific syntax (see Phase 2)
+- False positive filtering — removing non-content strings from candidates
+
+### MCP Tools Handle:
+
+- File system scanning (graph building, candidate finding)
+- Reading and writing files in `.contentrain/`
+- Patching source files with exact string replacements
+- Branch creation, commits, validation, submit
+- Guardrail enforcement (file limits, dry-run requirement)
+
+---
+
+## Phase 1: Extraction
+
+### Step 1 — Initialize and Scan Structure
+
+If `.contentrain/` does not exist, initialize first:
+```
+contentrain_init(stack: "{stack}", locales: ["{default_locale}", ...])
+```
+
+Build the project graph to understand architecture:
+```
+contentrain_scan(mode: "graph")
+```
+
+The graph output shows import/component dependency relationships. Use it to:
+- Identify page components vs shared components
+- Understand which files contain user-facing content
+- Prioritize high-impact files (layouts, pages) over low-impact files (utilities, configs)
+
+### Step 2 — Scan Candidates
+
+Find hardcoded string candidates:
+```
+contentrain_scan(mode: "candidates")
+```
+
+This returns candidate strings with file locations, line numbers, and surrounding code context. Maximum 500 files per scan.
+
+### Step 3 — Agent Evaluation (Your Job)
+
+This is the critical intelligence step. For each candidate string, determine:
+
+**Is this content?** Apply these heuristics:
+
+Extract these (user-visible text):
+- 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 and success/notification messages
+- Alt text (`alt="..."`) and ARIA labels (`aria-label="..."`)
+- Meta descriptions and page titles
+- Navigation items, tooltip text, empty state messages
+- CTA (call-to-action) text
+
+Do NOT extract these (code artifacts):
+- 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 (ports, HTTP status codes, pixel values, timeouts)
+- Strings shorter than 3 characters (unless semantically meaningful: "OK", "No", "Yes")
+- Regular expressions, configuration values, log messages
+- Code comments, test assertion strings, JSON keys
+- Enum values used as code identifiers (not displayed to users)
+
+**Domain assignment:** Group each content string into a domain:
+
+| 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 structure:** Group related candidates into models. Choose the right kind:
+
+| Content Pattern | Kind |
+|----------------|------|
+| One set of fields per page section | `singleton` |
+| Multiple items of same type | `collection` |
+| Long-form with metadata | `document` |
+| Key-value UI strings | `dictionary` |
+
+**Field assignment:** For each candidate, determine:
+- Which model it belongs to
+- Which field name to assign (use snake_case, descriptive names)
+- For dictionaries: which dot-notation key to assign
+
+### Step 4 — Preview Extraction
+
+Always dry-run before executing:
+```
+contentrain_apply(mode: "extract", dry_run: true)
+```
+
+Review the dry-run output carefully:
+- Are models structured correctly?
+- Are content assignments accurate?
+- Are there missing or misclassified candidates?
+- Are field names descriptive and consistent?
+
+### Step 5 — Execute Extraction
+
+After confirming the dry-run output:
+```
+contentrain_apply(mode: "extract")
+```
+
+This creates model definitions and content files in `.contentrain/`. Source files are NOT modified.
+
+### Step 6 — Validate and Submit
+
+```
+contentrain_validate
+contentrain_submit
+```
+
+Submit always uses `review` mode for normalize operations. The extraction branch is pushed for team review.
+
+### 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)
+- Maximum 100 files per apply operation
+
+---
+
+## Phase 2: Reuse
+
+> **Prerequisite:** Phase 1 extraction must be complete and merged. Content must exist in `.contentrain/` before patching source files.
+
+### Step 1 — Select Scope
+
+Choose one model or one domain to process. Do NOT reuse the entire project in one operation.
+
+```
+Example scopes: "marketing-hero", "error-messages", "marketing" (domain-level)
+```
+
+### Step 2 — Determine Replacement Expressions
+
+This is YOUR job. Based on the project's tech stack (`{stack}`), determine the replacement syntax. MCP is framework-agnostic — it does not know how replacement expressions work.
+
+#### Nuxt / Vue
+
+```vue
+<!-- Template context -->
+{{ $t('hero.title') }}
+{{ $t('hero.description') }}
+
+<!-- Script context -->
+const { t } = useI18n()
+t('hero.title')
+
+<!-- Attribute binding -->
+:placeholder="$t('form.email_placeholder')"
+:alt="$t('hero.image_alt')"
+```
+
+i18n library: `@nuxtjs/i18n` (Nuxt) or `vue-i18n` (Vue)
+
+#### Next.js / React
+
+```jsx
+// With next-intl
+import { useTranslations } from 'next-intl'
+const t = useTranslations('hero')
+<h1>{t('title')}</h1>
+<p>{t('description')}</p>
+
+// With react-intl
+import { useIntl } from 'react-intl'
+const intl = useIntl()
+<h1>{intl.formatMessage({ id: 'hero.title' })}</h1>
+
+// Attribute context
+<input placeholder={t('form.email_placeholder')} />
+<img alt={t('hero.image_alt')} />
+```
+
+i18n library: `next-intl` or `react-intl`
+
+#### Astro
+
+```astro
+---
+import { getRelativeLocaleUrl } from 'astro:i18n'
+import { t } from '@utils/i18n'
+---
+<h1>{t('hero.title')}</h1>
+<p>{t('hero.description')}</p>
+<img alt={t('hero.image_alt')} />
+```
+
+i18n library: `astro:i18n` (built-in)
+
+#### SvelteKit / Svelte
+
+```svelte
+<script>
+  import { t } from 'sveltekit-i18n'
+</script>
+
+<h1>{$t('hero.title')}</h1>
+<p>{$t('hero.description')}</p>
+<img alt={$t('hero.image_alt')} />
+```
+
+i18n library: `sveltekit-i18n` or `svelte-i18n`
+
+#### SDK Direct Import (No i18n)
+
+For projects that consume content directly without i18n:
+
+```ts
+import { query } from '#contentrain'
+const hero = singleton('marketing-hero').locale('en').get()
+```
+
+### Step 3 — Preview Reuse
+
+Always dry-run before executing:
+```
+contentrain_apply(mode: "reuse", scope: "model-id", dry_run: true)
+```
+
+Review the dry-run output:
+- Is each string replacement correct?
+- Will necessary import statements be added?
+- Are non-content strings left untouched?
+- Is the i18n setup code included where needed (composable import, hook call)?
+
+### Step 4 — Execute Reuse
+
+After confirming the dry-run output:
+```
+contentrain_apply(mode: "reuse", scope: "model-id")
+```
+
+This patches source files with content references. Each reuse operation creates a separate branch.
+
+### Step 5 — Validate and Submit
+
+```
+contentrain_validate
+contentrain_submit
+```
+
+### Step 6 — Repeat
+
+Repeat Steps 1-5 for each model or domain until all extracted content is referenced in source files.
+
+### Reuse Rules
+
+- Process one model or domain at a time. No whole-project reuse in one operation.
+- Ensure the i18n/content library is properly configured in the project before reuse.
+- Add necessary imports to patched files (e.g., `import { useTranslations } from 'next-intl'`).
+- Do NOT change the structure or behavior of components — only replace string literals with content references.
+- If a source file requires setup code (composable import, hook call), include it in the patch.
+- Maximum 100 files per apply operation.
+
+---
+
+## Guardrails Summary
+
+| Guardrail | Limit |
+|-----------|-------|
+| Allowed source file types | `.vue`, `.tsx`, `.jsx`, `.ts`, `.js`, `.mjs`, `.astro`, `.svelte` |
+| Max files per scan | 500 |
+| Max files per apply | 100 |
+| Dry-run before apply | MANDATORY |
+| Workflow mode | Always `review` |
+| Reuse scope | Per model or per domain |
+| Reuse prerequisite | Extraction must be complete |
+
+Attempting to apply without a prior dry-run will be rejected. Attempting to reuse without completed extraction will be rejected. Exceeding file limits will truncate results with a warning.
+
+---
+
+## Common Mistakes to Avoid
+
+| 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 |
+
+---
+
+## Checklist — Phase 1 (Extraction)
+
+- [ ] Project graph analyzed to understand architecture
+- [ ] All candidates evaluated: content vs code distinction applied
+- [ ] False positives filtered out
+- [ ] Candidates grouped into models with correct kinds
+- [ ] Domains assigned logically
+- [ ] Dry-run reviewed and confirmed
+- [ ] Extraction executed successfully
+- [ ] `contentrain_validate` returns zero errors
+- [ ] Branch submitted for review
+
+## Checklist — Phase 2 (Reuse)
+
+- [ ] Phase 1 extraction is merged
+- [ ] i18n library is configured in the project
+- [ ] Replacement expressions match the project stack
+- [ ] Scope is limited to one model or domain
+- [ ] Dry-run reviewed and confirmed
+- [ ] Reuse executed successfully
+- [ ] Import statements added to patched files
+- [ ] Component structure and behavior unchanged
+- [ ] `contentrain_validate` returns zero errors
+- [ ] Branch submitted for review