@contentrain/rules 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contentrain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# `@contentrain/rules`
+
+Shared AI-agent rules for Contentrain.
+
+This package is the policy layer of the Contentrain ecosystem. It defines how agents should behave when they work with:
+
+- Contentrain MCP tools
+- schema and model design
+- content quality
+- normalize workflows
+- git-backed review flows
+- IDE rule distribution
+
+If `@contentrain/mcp` is the deterministic execution layer, `@contentrain/rules` is the behavioral contract.
+
+## 🚀 Install
+
+```bash
+pnpm add @contentrain/rules
+```
+
+## 📦 What It Contains
+
+### Shared rule sets
+
+Published under `shared/*`:
+
+- `content-quality.md`
+- `seo-rules.md`
+- `i18n-quality.md`
+- `accessibility-rules.md`
+- `security-rules.md`
+- `media-rules.md`
+- `content-conventions.md`
+- `schema-rules.md`
+- `mcp-usage.md`
+- `workflow-rules.md`
+- `normalize-rules.md`
+
+### Prompt layers
+
+Published under `prompts/*`:
+
+- `common.md`
+- `generate-mode.md`
+- `normalize-mode.md`
+- `review-mode.md`
+
+### Context bridge
+
+Published under `context/*`:
+
+- `context-bridge.md`
+
+### IDE bundles
+
+Published under `ide/*`:
+
+- `ide/claude-code/contentrain.md`
+- `ide/cursor/contentrain.cursorrules`
+- `ide/windsurf/contentrain.windsurfrules`
+- `ide/generic/contentrain.md`
+
+## 🧰 Public Exports
+
+The package root exports constants that can be used by tooling:
+
+- `FIELD_TYPES`
+- `MODEL_KINDS`
+- `MCP_TOOLS`
+- `CONTENT_QUALITY_RULES`
+- `ARCHITECTURE_RULES`
+- `ALL_SHARED_RULES`
+- `IDE_RULE_FILES`
+- `STACKS`
+
+## 🧪 Example
+
+```ts
+import { IDE_RULE_FILES, MCP_TOOLS, ALL_SHARED_RULES } from '@contentrain/rules'
+
+console.log(MCP_TOOLS.includes('contentrain_validate'))
+console.log(IDE_RULE_FILES['claude-code'])
+console.log(ALL_SHARED_RULES)
+```
+
+## 🧠 Design Role
+
+`@contentrain/rules` exists to keep agent behavior aligned across tools and environments.
+
+It should answer questions like:
+
+- What is acceptable content quality?
+- How should an agent use MCP tools?
+- What is the normalize contract?
+- What workflow and review constraints exist?
+- How should rules be packaged for Claude Code, Cursor, Windsurf, and generic agents?
+
+## 🔗 Relationship To Other Packages
+
+- `@contentrain/mcp` enforces file, validation, and git behavior
+- `@contentrain/skills` provides step-by-step workflow playbooks
+- `contentrain` exposes CLI and serve UX
+- `@contentrain/query` is the generated runtime consumption layer
+
+Rule of thumb:
+
+- `rules` = policy and constraints
+- `skills` = procedures and playbooks
+
+## 🛠 Build
+
+The build does two things:
+
+1. builds the typed JS entry from `src/index.ts`
+2. generates IDE bundle files from the shared markdown rules
+
+From the monorepo root:
+
+```bash
+pnpm --filter @contentrain/rules build
+pnpm --filter @contentrain/rules test
+pnpm --filter @contentrain/rules typecheck
+```
+
+## 📄 License
+
+MIT

package/context/context-bridge.md

@@ -0,0 +1,241 @@
+# Context Bridge — `.contentrain/context.json` Specification
+
+## Purpose
+
+`context.json` is the project intelligence file. It provides AI agents and Contentrain Studio with structured knowledge about the project: its tech stack, content patterns, conventions, and normalize configuration.
+
+- **Written by:** MCP tools (updated after every write operation)
+- **Read by:** AI agents (at the start of every session) and Studio (for UI configuration)
+- **Location:** `.contentrain/context.json`
+
+---
+
+## Agent Reading Protocol
+
+Follow this exact sequence when starting any session:
+
+```
+1. config.json      — Project configuration (stack, locales, workflow, domains)
+2. context.json     — Project intelligence (conventions, scan settings, content patterns)
+3. vocabulary.json  — Canonical terms, brand terms, forbidden terms
+4. models/          — Model definitions (contentrain_status provides a summary)
+5. content/         — Existing content (contentrain_describe provides samples)
+```
+
+### When `context.json` Does Not Exist
+
+If the file does not exist, use defaults from `config.json`:
+- `stack`: from `config.json > stack`
+- `locales`: from `config.json > locales`
+- `tone`: default to `"professional"`
+- `scan_dirs`: default to `["src"]` or `["."]` depending on stack
+- `scan_extensions`: default to framework-appropriate extensions
+
+### Override Priority
+
+`context.json` values take priority over static rule defaults. For example:
+- If `context.json > conventions.max_title_length` is set to `80`, use `80` instead of the default `60` from `content-quality.md`.
+- If `context.json > conventions.allowed_richtext_tags` is defined, use that list instead of the default from `security-rules.md`.
+- Static rules are the fallback when `context.json` does not specify a value.
+
+---
+
+## Schema
+
+```json
+{
+  "version": 1,
+  "project": {
+    "name": "my-project",
+    "description": "Project description for agent context",
+    "stack": "nuxt",
+    "stack_version": "3.x",
+    "package_manager": "pnpm",
+    "src_dir": ".",
+    "content_consumption": "build-time"
+  },
+  "content": {
+    "import_pattern": "import {model} from '~/.contentrain/content/{domain}/{model}/{locale}.json'",
+    "i18n_strategy": "file-per-locale",
+    "default_locale": "en",
+    "supported_locales": ["en", "tr"],
+    "domains": [
+      {
+        "id": "marketing",
+        "description": "Landing page content",
+        "models": ["hero", "features", "pricing"]
+      },
+      {
+        "id": "blog",
+        "description": "Blog posts and categories",
+        "models": ["blog-post", "categories"]
+      }
+    ]
+  },
+  "normalize": {
+    "scan_dirs": ["components", "pages", "layouts"],
+    "scan_extensions": [".vue", ".ts"],
+    "ignore_patterns": ["node_modules", ".nuxt", "dist", ".contentrain"],
+    "import_rewrite": "import { t } from '~/composables/useContent'"
+  },
+  "conventions": {
+    "tone": "Professional, concise. Avoid jargon.",
+    "brand_terms": {
+      "product_name": "Acme Platform",
+      "company_name": "Acme Inc"
+    },
+    "forbidden_terms": ["click here", "lorem ipsum", "TODO"],
+    "max_title_length": 80,
+    "max_description_length": 160,
+    "target_reading_level": "grade-8",
+    "allowed_richtext_tags": [
+      "p", "strong", "em", "a", "ul", "ol", "li",
+      "h2", "h3", "h4", "h5", "h6",
+      "blockquote", "code", "pre", "img", "br", "hr",
+      "table", "thead", "tbody", "tr", "th", "td",
+      "del", "ins", "sup", "sub", "abbr", "mark",
+      "details", "summary"
+    ]
+  },
+  "lastOperation": {
+    "tool": "content_save",
+    "model": "blog-post",
+    "locale": "en",
+    "entries": ["a1b2c3d4e5f6"],
+    "timestamp": "2026-03-11T14:30:00Z",
+    "source": "mcp-local"
+  },
+  "stats": {
+    "models": 5,
+    "entries": 142,
+    "locales": ["en", "tr"],
+    "lastSync": "2026-03-11T14:30:00Z"
+  }
+}
+```
+
+---
+
+## Field Reference
+
+### `version` (number)
+
+Schema version. Currently `1`. Incremented on breaking schema changes.
+
+### `project` (object)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Project name. Used in branch names and commit messages. |
+| `description` | string | Brief description for agent context. Helps agents understand the project purpose. |
+| `stack` | string | Framework: `nuxt`, `next`, `astro`, `sveltekit`, `react`, `vue`, `node`. |
+| `stack_version` | string | Framework version: `"3.x"`, `"14.x"`, `"4.x"`. Affects API patterns. |
+| `package_manager` | string | `npm`, `pnpm`, `yarn`, `bun`. Affects install commands in suggestions. |
+| `src_dir` | string | Source directory relative to project root. `"."` for Nuxt, `"src"` for most others. |
+| `content_consumption` | string | How content is consumed: `"build-time"`, `"runtime"`, `"hybrid"`. |
+
+### `content` (object)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `import_pattern` | string | Content import template with `{model}`, `{domain}`, `{locale}` placeholders. |
+| `i18n_strategy` | string | Localization strategy: `"file-per-locale"` or `"single-file"`. |
+| `default_locale` | string | Default locale code (ISO 639-1): `"en"`, `"tr"`, `"de"`. |
+| `supported_locales` | string[] | All supported locale codes. |
+| `domains` | object[] | Content domain definitions. Each has `id` (string), `description` (string), and `models` (string[]). |
+
+### `normalize` (object)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `scan_dirs` | string[] | Directories to scan for hardcoded strings (relative to project root). |
+| `scan_extensions` | string[] | File extensions to include in scan. |
+| `ignore_patterns` | string[] | Glob patterns to exclude from scanning. |
+| `import_rewrite` | string | Import statement used when rewriting source files after normalization. |
+
+### `conventions` (object)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tone` | string | Content tone: `"professional"`, `"casual"`, `"technical"`, `"friendly"`, `"formal"`. |
+| `brand_terms` | object | Key-value pairs of brand terms that must be used with exact casing and spelling. |
+| `forbidden_terms` | string[] | Terms that must never appear in content. |
+| `max_title_length` | number | Override for maximum title character count. Default: `60`. |
+| `max_description_length` | number | Override for maximum description character count. Default: `160`. |
+| `target_reading_level` | string | Target readability: `"grade-6"`, `"grade-8"`, `"grade-10"`, `"technical"`. |
+| `allowed_richtext_tags` | string[] | Override for allowed HTML tags in richtext fields. |
+
+### `lastOperation` (object)
+
+Updated after every MCP write operation. Agents can use this to understand what changed most recently.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tool` | string | MCP tool that performed the operation: `"content_save"`, `"model_save"`, `"scaffold"`, `"apply"`. |
+| `model` | string | Model ID that was affected. |
+| `locale` | string | Locale of the operation (if applicable). |
+| `entries` | string[] | Entry IDs that were created or modified. |
+| `timestamp` | string | ISO 8601 timestamp of the operation. |
+| `source` | string | Origin: `"mcp-local"` (IDE), `"mcp-studio"` (Studio server-side MCP), `"studio-ui"` (Studio direct). |
+
+### `stats` (object)
+
+Aggregate project statistics, updated after every write operation.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `models` | number | Total number of models in the project. |
+| `entries` | number | Total number of content entries across all models and locales. |
+| `locales` | string[] | All locales that have content. |
+| `lastSync` | string | ISO 8601 timestamp of the last sync operation. |
+
+---
+
+## Stack-Specific Defaults
+
+When creating `context.json` for the first time, use stack-appropriate defaults. See template files in `context/templates/` for each supported stack:
+
+| Stack | Template | `src_dir` | `scan_extensions` | `scan_dirs` |
+|-------|----------|-----------|-------------------|-------------|
+| Nuxt | `nuxt.context.json` | `"app/"` | `[".vue", ".ts"]` | `["app/components/", "app/pages/", "app/layouts/"]` |
+| Next.js | `next.context.json` | `"src/"` | `[".tsx", ".ts", ".jsx"]` | `["src/components/", "src/app/"]` |
+| Astro | `astro.context.json` | `"src/"` | `[".astro", ".ts", ".tsx"]` | `["src/components/", "src/pages/", "src/layouts/"]` |
+| SvelteKit | `sveltekit.context.json` | `"src/"` | `[".svelte", ".ts"]` | `["src/lib/", "src/routes/"]` |
+
+---
+
+## Update Behavior
+
+MCP tools update `context.json` after every write operation:
+- `contentrain_init` creates the initial file
+- `contentrain_model_save` updates the domains list if a new domain is used
+- `contentrain_content_save` updates content stats
+- `contentrain_apply` updates normalize state
+- `contentrain_submit` updates last operation timestamp
+
+Agents MUST NOT write to `context.json` directly. It is managed exclusively by MCP tools. Agents read it for configuration and intelligence.
+
+---
+
+## Example: Reading Context in an Agent Session
+
+```
+1. Agent receives user request: "Add a blog post about deployment"
+2. Agent reads config.json:
+   - stack: "nuxt"
+   - locales: ["en", "tr"]
+   - workflow: "review"
+3. Agent reads context.json:
+   - tone: "professional"
+   - i18n_strategy: "@nuxtjs/i18n"
+   - domains: ["blog", "marketing"]
+4. Agent reads vocabulary.json:
+   - brand_terms: ["Contentrain"]
+   - forbidden_terms: ["click here"]
+5. Agent calls contentrain_status:
+   - Models: blog-post (document), categories (collection), authors (collection)
+6. Agent calls contentrain_describe(model: "blog-post"):
+   - Fields: title (string, required), slug (slug, required, unique), excerpt (text), ...
+7. Agent creates content following all rules, using vocabulary terms, matching tone
+8. Agent validates and submits
+```

package/context/templates/astro.context.json

@@ -0,0 +1,74 @@
+{
+  "version": 1,
+  "project": {
+    "name": "my-astro-site",
+    "description": "Content-driven marketing site with blog and portfolio",
+    "stack": "astro",
+    "stack_version": "5.x",
+    "package_manager": "pnpm",
+    "src_dir": "src/",
+    "content_consumption": "build-time"
+  },
+  "content": {
+    "import_pattern": "import {model} from '~/.contentrain/content/{domain}/{model}/{locale}.json'",
+    "i18n_strategy": "file-per-locale",
+    "default_locale": "en",
+    "supported_locales": ["en", "de"],
+    "domains": [
+      {
+        "id": "marketing",
+        "description": "Landing page content — hero, features, testimonials",
+        "models": ["hero", "features", "testimonials"]
+      },
+      {
+        "id": "blog",
+        "description": "Blog posts, authors, and categories",
+        "models": ["blog-post", "authors", "categories"]
+      },
+      {
+        "id": "portfolio",
+        "description": "Project showcase entries",
+        "models": ["projects"]
+      }
+    ]
+  },
+  "normalize": {
+    "scan_dirs": ["src/components/", "src/pages/", "src/layouts/"],
+    "scan_extensions": [".astro", ".ts", ".tsx"],
+    "ignore_patterns": ["dist/", "node_modules/", ".astro/", ".contentrain/", "*.test.*", "*.spec.*"],
+    "import_rewrite": "import { t } from '../i18n/utils'"
+  },
+  "conventions": {
+    "tone": "Friendly, informative. Approachable but professional.",
+    "brand_terms": {
+      "product_name": "My Astro Site",
+      "company_name": "Stellar Labs"
+    },
+    "forbidden_terms": ["click here", "lorem ipsum", "TODO"],
+    "max_title_length": 80,
+    "max_description_length": 160,
+    "target_reading_level": "grade-8",
+    "allowed_richtext_tags": [
+      "p", "strong", "em", "a", "ul", "ol", "li",
+      "h2", "h3", "h4", "h5", "h6",
+      "blockquote", "code", "pre", "img", "br", "hr",
+      "table", "thead", "tbody", "tr", "th", "td",
+      "del", "ins", "sup", "sub", "abbr", "mark",
+      "details", "summary"
+    ]
+  },
+  "lastOperation": {
+    "tool": "content_save",
+    "model": "blog-post",
+    "locale": "en",
+    "entries": ["c3d4e5f6a7b8"],
+    "timestamp": "2026-03-09T12:15:00Z",
+    "source": "mcp-local"
+  },
+  "stats": {
+    "models": 6,
+    "entries": 38,
+    "locales": ["en", "de"],
+    "lastSync": "2026-03-09T12:15:00Z"
+  }
+}

package/context/templates/next.context.json

@@ -0,0 +1,74 @@
+{
+  "version": 1,
+  "project": {
+    "name": "my-next-app",
+    "description": "SaaS marketing site with documentation and blog",
+    "stack": "next",
+    "stack_version": "15.x",
+    "package_manager": "npm",
+    "src_dir": "src/",
+    "content_consumption": "build-time"
+  },
+  "content": {
+    "import_pattern": "import {model} from '@/.contentrain/content/{domain}/{model}/{locale}.json'",
+    "i18n_strategy": "file-per-locale",
+    "default_locale": "en",
+    "supported_locales": ["en", "es", "fr"],
+    "domains": [
+      {
+        "id": "marketing",
+        "description": "Landing page content — hero, features, pricing, FAQ",
+        "models": ["hero", "features", "pricing", "faq"]
+      },
+      {
+        "id": "docs",
+        "description": "Documentation pages and sidebar navigation",
+        "models": ["doc-page", "doc-sidebar"]
+      },
+      {
+        "id": "blog",
+        "description": "Blog articles and tags",
+        "models": ["blog-post", "tags"]
+      }
+    ]
+  },
+  "normalize": {
+    "scan_dirs": ["src/components/", "src/app/"],
+    "scan_extensions": [".tsx", ".ts", ".jsx"],
+    "ignore_patterns": [".next/", "node_modules/", "out/", ".contentrain/", "*.test.*", "*.spec.*"],
+    "import_rewrite": "import { useTranslations } from 'next-intl'"
+  },
+  "conventions": {
+    "tone": "Professional, clear. Developer-friendly language.",
+    "brand_terms": {
+      "product_name": "My Next App",
+      "company_name": "Acme Corp"
+    },
+    "forbidden_terms": ["click here", "lorem ipsum", "TODO", "TBD"],
+    "max_title_length": 70,
+    "max_description_length": 155,
+    "target_reading_level": "grade-8",
+    "allowed_richtext_tags": [
+      "p", "strong", "em", "a", "ul", "ol", "li",
+      "h2", "h3", "h4", "h5", "h6",
+      "blockquote", "code", "pre", "img", "br", "hr",
+      "table", "thead", "tbody", "tr", "th", "td",
+      "del", "ins", "sup", "sub", "abbr", "mark",
+      "details", "summary"
+    ]
+  },
+  "lastOperation": {
+    "tool": "model_save",
+    "model": "blog-post",
+    "locale": "en",
+    "entries": [],
+    "timestamp": "2026-03-10T16:45:00Z",
+    "source": "mcp-local"
+  },
+  "stats": {
+    "models": 7,
+    "entries": 54,
+    "locales": ["en", "es", "fr"],
+    "lastSync": "2026-03-10T16:45:00Z"
+  }
+}

package/context/templates/nuxt.context.json

@@ -0,0 +1,74 @@
+{
+  "version": 1,
+  "project": {
+    "name": "my-nuxt-app",
+    "description": "Marketing website with blog and i18n support",
+    "stack": "nuxt",
+    "stack_version": "4.0",
+    "package_manager": "pnpm",
+    "src_dir": "app/",
+    "content_consumption": "build-time"
+  },
+  "content": {
+    "import_pattern": "import {model} from '~/.contentrain/content/{domain}/{model}/{locale}.json'",
+    "i18n_strategy": "file-per-locale",
+    "default_locale": "en",
+    "supported_locales": ["en", "tr"],
+    "domains": [
+      {
+        "id": "marketing",
+        "description": "Landing page content — hero, features, pricing, testimonials",
+        "models": ["hero", "features", "pricing", "testimonials"]
+      },
+      {
+        "id": "blog",
+        "description": "Blog posts and categories",
+        "models": ["blog-post", "categories"]
+      },
+      {
+        "id": "ui",
+        "description": "UI strings — navigation, forms, errors",
+        "models": ["navigation", "forms", "error-messages"]
+      }
+    ]
+  },
+  "normalize": {
+    "scan_dirs": ["app/components/", "app/pages/", "app/layouts/"],
+    "scan_extensions": [".vue", ".ts"],
+    "ignore_patterns": [".nuxt/", "node_modules/", "dist/", ".contentrain/", "*.test.*", "*.spec.*"],
+    "import_rewrite": "import { t } from '~/composables/useContent'"
+  },
+  "conventions": {
+    "tone": "Professional, concise. Avoid jargon.",
+    "brand_terms": {
+      "product_name": "My Nuxt App",
+      "company_name": "Acme Inc"
+    },
+    "forbidden_terms": ["click here", "lorem ipsum", "TODO"],
+    "max_title_length": 80,
+    "max_description_length": 160,
+    "target_reading_level": "grade-8",
+    "allowed_richtext_tags": [
+      "p", "strong", "em", "a", "ul", "ol", "li",
+      "h2", "h3", "h4", "h5", "h6",
+      "blockquote", "code", "pre", "img", "br", "hr",
+      "table", "thead", "tbody", "tr", "th", "td",
+      "del", "ins", "sup", "sub", "abbr", "mark",
+      "details", "summary"
+    ]
+  },
+  "lastOperation": {
+    "tool": "content_save",
+    "model": "hero",
+    "locale": "en",
+    "entries": ["f7e8d9c0b1a2"],
+    "timestamp": "2026-03-11T10:00:00Z",
+    "source": "mcp-local"
+  },
+  "stats": {
+    "models": 7,
+    "entries": 86,
+    "locales": ["en", "tr"],
+    "lastSync": "2026-03-11T10:00:00Z"
+  }
+}