@contentrain/rules 0.2.0 → 0.3.1

package/README.md

@@ -12,33 +12,22 @@ This package is the policy layer of the Contentrain ecosystem. It defines how ag
 - 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
+## Install
 
 ```bash
 pnpm add @contentrain/rules
 ```
 
-## 📦 What It Contains
+## What It Contains
 
-### Shared rule sets
+### Essential guardrails
 
-Published under `shared/*`:
+Published under `essential/*`:
 
-- `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`
+- `contentrain-essentials.md` — compact, always-loaded rules (~86 lines) covering architecture, model kinds, MCP tools, mandatory protocols, and security basics
 
 ### Prompt layers
 
@@ -55,39 +44,27 @@ 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
+## 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`
+- `FIELD_TYPES` — 27 flat field types
+- `MODEL_KINDS` — singleton, collection, document, dictionary
+- `MCP_TOOLS` — 15 MCP tool names
+- `ESSENTIAL_RULES_FILE` — path to essential guardrails markdown
+- `STACKS` — supported framework stacks
 
-## 🧪 Example
+## Example
 
 ```ts
-import { IDE_RULE_FILES, MCP_TOOLS, ALL_SHARED_RULES } from '@contentrain/rules'
+import { MCP_TOOLS, ESSENTIAL_RULES_FILE, FIELD_TYPES } from '@contentrain/rules'
 
 console.log(MCP_TOOLS.includes('contentrain_validate'))
-console.log(IDE_RULE_FILES['claude-code'])
-console.log(ALL_SHARED_RULES)
+console.log(ESSENTIAL_RULES_FILE) // 'essential/contentrain-essentials.md'
+console.log(FIELD_TYPES.length)   // 27
 ```
 
-## 🧠 Design Role
+## Design Role
 
 `@contentrain/rules` exists to keep agent behavior aligned across tools and environments.
 
@@ -97,26 +74,22 @@ It should answer questions like:
 - 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
+Detailed reference material and step-by-step procedures live in `@contentrain/skills` (Agent Skills standard format).
+
+## Relationship To Other Packages
 
 - `@contentrain/mcp` enforces file, validation, and git behavior
-- `@contentrain/skills` provides step-by-step workflow playbooks
+- `@contentrain/skills` provides Agent Skills with progressive disclosure (SKILL.md + references/)
 - `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:
+- `rules` = essential guardrails (always loaded, ~86 lines)
+- `skills` = detailed procedures and reference docs (on-demand)
 
-1. builds the typed JS entry from `src/index.ts`
-2. generates IDE bundle files from the shared markdown rules
+## Build
 
 From the monorepo root:
 
@@ -126,6 +99,6 @@ pnpm --filter @contentrain/rules test
 pnpm --filter @contentrain/rules typecheck
 ```
 
-## 📄 License
+## License
 
 MIT

package/context/context-bridge.md

@@ -4,7 +4,7 @@
 
 `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)
+- **Written by:** MCP tools (committed together with content changes in the same branch, not as a separate commit)
 - **Read by:** AI agents (at the start of every session) and Studio (for UI configuration)
 - **Location:** `.contentrain/context.json`
 
@@ -206,7 +206,7 @@ When creating `context.json` for the first time, use stack-appropriate defaults.
 
 ## Update Behavior
 
-MCP tools update `context.json` after every write operation:
+MCP tools update `context.json` as part of each write operation, committed together with the content changes in the same branch (not as a separate commit):
 - `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

package/dist/index.cjs

@@ -57,28 +57,7 @@ const MCP_TOOLS = [
 	"contentrain_submit",
 	"contentrain_bulk"
 ];
-const CONTENT_QUALITY_RULES = [
-	"content-quality",
-	"seo-rules",
-	"i18n-quality",
-	"accessibility-rules",
-	"security-rules",
-	"media-rules"
-];
-const ARCHITECTURE_RULES = [
-	"content-conventions",
-	"schema-rules",
-	"mcp-usage",
-	"workflow-rules",
-	"normalize-rules"
-];
-const ALL_SHARED_RULES = [...CONTENT_QUALITY_RULES, ...ARCHITECTURE_RULES];
-const IDE_RULE_FILES = {
-	"claude-code": "ide/claude-code/contentrain.md",
-	"cursor": "ide/cursor/contentrain.cursorrules",
-	"windsurf": "ide/windsurf/contentrain.windsurfrules",
-	"generic": "ide/generic/contentrain.md"
-};
+const ESSENTIAL_RULES_FILE = "essential/contentrain-essentials.md";
 const STACKS = [
 	"nuxt",
 	"next",
@@ -88,11 +67,8 @@ const STACKS = [
 	"node"
 ];
 //#endregion
-exports.ALL_SHARED_RULES = ALL_SHARED_RULES;
-exports.ARCHITECTURE_RULES = ARCHITECTURE_RULES;
-exports.CONTENT_QUALITY_RULES = CONTENT_QUALITY_RULES;
+exports.ESSENTIAL_RULES_FILE = ESSENTIAL_RULES_FILE;
 exports.FIELD_TYPES = FIELD_TYPES;
-exports.IDE_RULE_FILES = IDE_RULE_FILES;
 exports.MCP_TOOLS = MCP_TOOLS;
 exports.MODEL_KINDS = MODEL_KINDS;
 exports.STACKS = STACKS;

package/dist/index.d.cts

@@ -10,18 +10,9 @@ declare const MODEL_KINDS: readonly ["singleton", "collection", "document", "dic
 type ModelKind = (typeof MODEL_KINDS)[number];
 declare const MCP_TOOLS: readonly ["contentrain_status", "contentrain_describe", "contentrain_describe_format", "contentrain_init", "contentrain_scaffold", "contentrain_model_save", "contentrain_model_delete", "contentrain_content_save", "contentrain_content_delete", "contentrain_content_list", "contentrain_scan", "contentrain_apply", "contentrain_validate", "contentrain_submit", "contentrain_bulk"];
 type McpTool = (typeof MCP_TOOLS)[number];
-declare const CONTENT_QUALITY_RULES: readonly ["content-quality", "seo-rules", "i18n-quality", "accessibility-rules", "security-rules", "media-rules"];
-declare const ARCHITECTURE_RULES: readonly ["content-conventions", "schema-rules", "mcp-usage", "workflow-rules", "normalize-rules"];
-declare const ALL_SHARED_RULES: readonly ["content-quality", "seo-rules", "i18n-quality", "accessibility-rules", "security-rules", "media-rules", "content-conventions", "schema-rules", "mcp-usage", "workflow-rules", "normalize-rules"];
-declare const IDE_RULE_FILES: {
-  readonly 'claude-code': "ide/claude-code/contentrain.md";
-  readonly cursor: "ide/cursor/contentrain.cursorrules";
-  readonly windsurf: "ide/windsurf/contentrain.windsurfrules";
-  readonly generic: "ide/generic/contentrain.md";
-};
-type IdeTarget = keyof typeof IDE_RULE_FILES;
+declare const ESSENTIAL_RULES_FILE: "essential/contentrain-essentials.md";
 declare const STACKS: readonly ["nuxt", "next", "astro", "sveltekit", "react", "node"];
 type Stack = (typeof STACKS)[number];
 //#endregion
-export { ALL_SHARED_RULES, ARCHITECTURE_RULES, CONTENT_QUALITY_RULES, FIELD_TYPES, FieldType, IDE_RULE_FILES, IdeTarget, MCP_TOOLS, MODEL_KINDS, McpTool, ModelKind, STACKS, Stack };
+export { ESSENTIAL_RULES_FILE, FIELD_TYPES, FieldType, MCP_TOOLS, MODEL_KINDS, McpTool, ModelKind, STACKS, Stack };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;AAQA;;;;cAAa,WAAA;AAAA,KAUD,SAAA,WAAoB,WAAA;AAAA,cAInB,WAAA;AAAA,KACD,SAAA,WAAoB,WAAA;AAAA,cAInB,SAAA;AAAA,KAUD,OAAA,WAAkB,SAAA;AAAA,cAIjB,qBAAA;AAAA,cAKA,kBAAA;AAAA,cAKA,gBAAA;AAAA,cAIA,cAAA;EAAA;;;;;KAOD,SAAA,gBAAyB,cAAA;AAAA,cAIxB,MAAA;AAAA,KACD,KAAA,WAAgB,MAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;AAQA;;;;cAAa,WAAA;AAAA,KAUD,SAAA,WAAoB,WAAA;AAAA,cAInB,WAAA;AAAA,KACD,SAAA,WAAoB,WAAA;AAAA,cAInB,SAAA;AAAA,KAUD,OAAA,WAAkB,SAAA;AAAA,cAIjB,oBAAA;AAAA,cAIA,MAAA;AAAA,KACD,KAAA,WAAgB,MAAA"}

package/dist/index.d.mts

@@ -10,18 +10,9 @@ declare const MODEL_KINDS: readonly ["singleton", "collection", "document", "dic
 type ModelKind = (typeof MODEL_KINDS)[number];
 declare const MCP_TOOLS: readonly ["contentrain_status", "contentrain_describe", "contentrain_describe_format", "contentrain_init", "contentrain_scaffold", "contentrain_model_save", "contentrain_model_delete", "contentrain_content_save", "contentrain_content_delete", "contentrain_content_list", "contentrain_scan", "contentrain_apply", "contentrain_validate", "contentrain_submit", "contentrain_bulk"];
 type McpTool = (typeof MCP_TOOLS)[number];
-declare const CONTENT_QUALITY_RULES: readonly ["content-quality", "seo-rules", "i18n-quality", "accessibility-rules", "security-rules", "media-rules"];
-declare const ARCHITECTURE_RULES: readonly ["content-conventions", "schema-rules", "mcp-usage", "workflow-rules", "normalize-rules"];
-declare const ALL_SHARED_RULES: readonly ["content-quality", "seo-rules", "i18n-quality", "accessibility-rules", "security-rules", "media-rules", "content-conventions", "schema-rules", "mcp-usage", "workflow-rules", "normalize-rules"];
-declare const IDE_RULE_FILES: {
-  readonly 'claude-code': "ide/claude-code/contentrain.md";
-  readonly cursor: "ide/cursor/contentrain.cursorrules";
-  readonly windsurf: "ide/windsurf/contentrain.windsurfrules";
-  readonly generic: "ide/generic/contentrain.md";
-};
-type IdeTarget = keyof typeof IDE_RULE_FILES;
+declare const ESSENTIAL_RULES_FILE: "essential/contentrain-essentials.md";
 declare const STACKS: readonly ["nuxt", "next", "astro", "sveltekit", "react", "node"];
 type Stack = (typeof STACKS)[number];
 //#endregion
-export { ALL_SHARED_RULES, ARCHITECTURE_RULES, CONTENT_QUALITY_RULES, FIELD_TYPES, FieldType, IDE_RULE_FILES, IdeTarget, MCP_TOOLS, MODEL_KINDS, McpTool, ModelKind, STACKS, Stack };
+export { ESSENTIAL_RULES_FILE, FIELD_TYPES, FieldType, MCP_TOOLS, MODEL_KINDS, McpTool, ModelKind, STACKS, Stack };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;AAQA;;;;cAAa,WAAA;AAAA,KAUD,SAAA,WAAoB,WAAA;AAAA,cAInB,WAAA;AAAA,KACD,SAAA,WAAoB,WAAA;AAAA,cAInB,SAAA;AAAA,KAUD,OAAA,WAAkB,SAAA;AAAA,cAIjB,qBAAA;AAAA,cAKA,kBAAA;AAAA,cAKA,gBAAA;AAAA,cAIA,cAAA;EAAA;;;;;KAOD,SAAA,gBAAyB,cAAA;AAAA,cAIxB,MAAA;AAAA,KACD,KAAA,WAAgB,MAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;AAQA;;;;cAAa,WAAA;AAAA,KAUD,SAAA,WAAoB,WAAA;AAAA,cAInB,WAAA;AAAA,KACD,SAAA,WAAoB,WAAA;AAAA,cAInB,SAAA;AAAA,KAUD,OAAA,WAAkB,SAAA;AAAA,cAIjB,oBAAA;AAAA,cAIA,MAAA;AAAA,KACD,KAAA,WAAgB,MAAA"}

package/dist/index.mjs

@@ -56,28 +56,7 @@ const MCP_TOOLS = [
 	"contentrain_submit",
 	"contentrain_bulk"
 ];
-const CONTENT_QUALITY_RULES = [
-	"content-quality",
-	"seo-rules",
-	"i18n-quality",
-	"accessibility-rules",
-	"security-rules",
-	"media-rules"
-];
-const ARCHITECTURE_RULES = [
-	"content-conventions",
-	"schema-rules",
-	"mcp-usage",
-	"workflow-rules",
-	"normalize-rules"
-];
-const ALL_SHARED_RULES = [...CONTENT_QUALITY_RULES, ...ARCHITECTURE_RULES];
-const IDE_RULE_FILES = {
-	"claude-code": "ide/claude-code/contentrain.md",
-	"cursor": "ide/cursor/contentrain.cursorrules",
-	"windsurf": "ide/windsurf/contentrain.windsurfrules",
-	"generic": "ide/generic/contentrain.md"
-};
+const ESSENTIAL_RULES_FILE = "essential/contentrain-essentials.md";
 const STACKS = [
 	"nuxt",
 	"next",
@@ -87,6 +66,6 @@ const STACKS = [
 	"node"
 ];
 //#endregion
-export { ALL_SHARED_RULES, ARCHITECTURE_RULES, CONTENT_QUALITY_RULES, FIELD_TYPES, IDE_RULE_FILES, MCP_TOOLS, MODEL_KINDS, STACKS };
+export { ESSENTIAL_RULES_FILE, FIELD_TYPES, MCP_TOOLS, MODEL_KINDS, STACKS };
 
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @contentrain/rules — AI agent rules for Contentrain\n *\n * Quality standards, architecture conventions, and IDE integration.\n */\n\n// ─── Field Types (27 flat types) ───\n\nexport const FIELD_TYPES = [\n  'string', 'text', 'email', 'url', 'slug', 'color', 'phone', 'code', 'icon',\n  'markdown', 'richtext',\n  'number', 'integer', 'decimal', 'percent', 'rating',\n  'boolean', 'date', 'datetime',\n  'image', 'video', 'file',\n  'relation', 'relations',\n  'select', 'array', 'object',\n] as const\n\nexport type FieldType = (typeof FIELD_TYPES)[number]\n\n// ─── Model Kinds ───\n\nexport const MODEL_KINDS = ['singleton', 'collection', 'document', 'dictionary'] as const\nexport type ModelKind = (typeof MODEL_KINDS)[number]\n\n// ─── MCP Tools (15 tools) ───\n\nexport const MCP_TOOLS = [\n  'contentrain_status', 'contentrain_describe', 'contentrain_describe_format',\n  'contentrain_init', 'contentrain_scaffold',\n  'contentrain_model_save', 'contentrain_model_delete',\n  'contentrain_content_save', 'contentrain_content_delete', 'contentrain_content_list',\n  'contentrain_scan', 'contentrain_apply',\n  'contentrain_validate', 'contentrain_submit',\n  'contentrain_bulk',\n] as const\n\nexport type McpTool = (typeof MCP_TOOLS)[number]\n\n// ─── Rule Sets ───\n\nexport const CONTENT_QUALITY_RULES = [\n  'content-quality', 'seo-rules', 'i18n-quality',\n  'accessibility-rules', 'security-rules', 'media-rules',\n] as const\n\nexport const ARCHITECTURE_RULES = [\n  'content-conventions', 'schema-rules', 'mcp-usage',\n  'workflow-rules', 'normalize-rules',\n] as const\n\nexport const ALL_SHARED_RULES = [...CONTENT_QUALITY_RULES, ...ARCHITECTURE_RULES] as const\n\n// ─── IDE Rule Paths ───\n\nexport const IDE_RULE_FILES = {\n  'claude-code': 'ide/claude-code/contentrain.md',\n  'cursor': 'ide/cursor/contentrain.cursorrules',\n  'windsurf': 'ide/windsurf/contentrain.windsurfrules',\n  'generic': 'ide/generic/contentrain.md',\n} as const\n\nexport type IdeTarget = keyof typeof IDE_RULE_FILES\n\n// ─── Stacks ───\n\nexport const STACKS = ['nuxt', 'next', 'astro', 'sveltekit', 'react', 'node'] as const\nexport type Stack = (typeof STACKS)[number]\n"],"mappings":";;;;;;AAQA,MAAa,cAAc;CACzB;CAAU;CAAQ;CAAS;CAAO;CAAQ;CAAS;CAAS;CAAQ;CACpE;CAAY;CACZ;CAAU;CAAW;CAAW;CAAW;CAC3C;CAAW;CAAQ;CACnB;CAAS;CAAS;CAClB;CAAY;CACZ;CAAU;CAAS;CACpB;AAMD,MAAa,cAAc;CAAC;CAAa;CAAc;CAAY;CAAa;AAKhF,MAAa,YAAY;CACvB;CAAsB;CAAwB;CAC9C;CAAoB;CACpB;CAA0B;CAC1B;CAA4B;CAA8B;CAC1D;CAAoB;CACpB;CAAwB;CACxB;CACD;AAMD,MAAa,wBAAwB;CACnC;CAAmB;CAAa;CAChC;CAAuB;CAAkB;CAC1C;AAED,MAAa,qBAAqB;CAChC;CAAuB;CAAgB;CACvC;CAAkB;CACnB;AAED,MAAa,mBAAmB,CAAC,GAAG,uBAAuB,GAAG,mBAAmB;AAIjF,MAAa,iBAAiB;CAC5B,eAAe;CACf,UAAU;CACV,YAAY;CACZ,WAAW;CACZ;AAMD,MAAa,SAAS;CAAC;CAAQ;CAAQ;CAAS;CAAa;CAAS;CAAO"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @contentrain/rules — AI agent rules for Contentrain\n *\n * Quality standards, architecture conventions, and IDE integration.\n */\n\n// ─── Field Types (27 flat types) ───\n\nexport const FIELD_TYPES = [\n  'string', 'text', 'email', 'url', 'slug', 'color', 'phone', 'code', 'icon',\n  'markdown', 'richtext',\n  'number', 'integer', 'decimal', 'percent', 'rating',\n  'boolean', 'date', 'datetime',\n  'image', 'video', 'file',\n  'relation', 'relations',\n  'select', 'array', 'object',\n] as const\n\nexport type FieldType = (typeof FIELD_TYPES)[number]\n\n// ─── Model Kinds ───\n\nexport const MODEL_KINDS = ['singleton', 'collection', 'document', 'dictionary'] as const\nexport type ModelKind = (typeof MODEL_KINDS)[number]\n\n// ─── MCP Tools (15 tools) ───\n\nexport const MCP_TOOLS = [\n  'contentrain_status', 'contentrain_describe', 'contentrain_describe_format',\n  'contentrain_init', 'contentrain_scaffold',\n  'contentrain_model_save', 'contentrain_model_delete',\n  'contentrain_content_save', 'contentrain_content_delete', 'contentrain_content_list',\n  'contentrain_scan', 'contentrain_apply',\n  'contentrain_validate', 'contentrain_submit',\n  'contentrain_bulk',\n] as const\n\nexport type McpTool = (typeof MCP_TOOLS)[number]\n\n// ─── Essential Rules ───\n\nexport const ESSENTIAL_RULES_FILE = 'essential/contentrain-essentials.md' as const\n\n// ─── Stacks ───\n\nexport const STACKS = ['nuxt', 'next', 'astro', 'sveltekit', 'react', 'node'] as const\nexport type Stack = (typeof STACKS)[number]\n"],"mappings":";;;;;;AAQA,MAAa,cAAc;CACzB;CAAU;CAAQ;CAAS;CAAO;CAAQ;CAAS;CAAS;CAAQ;CACpE;CAAY;CACZ;CAAU;CAAW;CAAW;CAAW;CAC3C;CAAW;CAAQ;CACnB;CAAS;CAAS;CAClB;CAAY;CACZ;CAAU;CAAS;CACpB;AAMD,MAAa,cAAc;CAAC;CAAa;CAAc;CAAY;CAAa;AAKhF,MAAa,YAAY;CACvB;CAAsB;CAAwB;CAC9C;CAAoB;CACpB;CAA0B;CAC1B;CAA4B;CAA8B;CAC1D;CAAoB;CACpB;CAAwB;CACxB;CACD;AAMD,MAAa,uBAAuB;AAIpC,MAAa,SAAS;CAAC;CAAQ;CAAQ;CAAS;CAAa;CAAS;CAAO"}

package/essential/contentrain-essentials.md

@@ -0,0 +1,91 @@
+# Contentrain — Essential Rules
+
+This project uses Contentrain for AI-driven content management. These rules are mandatory.
+
+## Architecture
+
+MCP is **deterministic infrastructure**. The agent (you) is the **intelligence layer**.
+
+- **Agent decides:** what is content vs code, domain grouping, model structure, replacement expressions (stack-aware), content quality
+- **MCP handles:** file I/O, validation, Git transactions (dedicated contentrain branch/worktree/commit/update-ref), project scanning
+- MCP does NOT make content decisions. It is framework-agnostic.
+
+## Four Model Kinds
+
+| Kind | Storage | Use For |
+|------|---------|---------|
+| **singleton** | One JSON object per locale | Page sections, site config, navigation |
+| **collection** | Object-map by entry ID (sorted keys) | Team members, FAQs, products, categories |
+| **document** | Markdown with frontmatter, per slug per locale | Blog posts, docs, changelogs |
+| **dictionary** | Flat key-value (all strings), NO fields, NO id/slug | UI strings, error messages, translations |
+
+## Content Format Rules
+
+- **JSON only** — no YAML (except document frontmatter)
+- **Canonical serialization:** sorted keys, 2-space indent, UTF-8, trailing newline, omit nulls
+- **Collection IDs:** auto-generated 12-char hex, used as object-map keys (NOT stored inside entry)
+- **Dictionary keys:** dot-notation, semantic, English (`auth.login.button`)
+
+## Critical Boundaries
+
+- **NEVER** write to `.contentrain/meta/` — system-managed metadata
+- **NEVER** edit `.contentrain/client/` — auto-generated SDK
+- **NEVER** edit `.contentrain/context.json` — MCP writes, agents read
+- **NEVER** include system fields in content data: `id`, `status`, `source`, `updated_by`, `updated_at`, `createdAt`, `updatedAt`
+- **ALWAYS** use MCP tools — do not write `.contentrain/` JSON files directly
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `contentrain_status` | Full project state (call FIRST in every session) |
+| `contentrain_describe` | Schema + sample for one model |
+| `contentrain_describe_format` | Storage format contract (call BEFORE creating models) |
+| `contentrain_init` | Initialize `.contentrain/` directory |
+| `contentrain_scaffold` | Generate models from template |
+| `contentrain_model_save` | Create/update model definition (upsert) |
+| `contentrain_model_delete` | Delete model (checks referential integrity) |
+| `contentrain_content_save` | Create/update content entries (upsert) |
+| `contentrain_content_delete` | Delete content entry |
+| `contentrain_content_list` | List entries for a model |
+| `contentrain_scan` | Scan project (graph/candidates/summary) |
+| `contentrain_apply` | Apply normalize (extract/reuse) |
+| `contentrain_validate` | Validate content against schemas |
+| `contentrain_submit` | Push branches to remote |
+| `contentrain_bulk` | Batch operations (copy_locale/update_status/delete_entries) |
+
+## Mandatory Protocols
+
+1. **Status first** — ALWAYS call `contentrain_status` before any operation on an existing project
+2. **Describe format first** — ALWAYS call `contentrain_describe_format` before creating models or content
+3. **Dry run first** — ALWAYS use `dry_run: true` before any `contentrain_apply`, review output, then `dry_run: false`
+4. **Validate before submit** — ALWAYS call `contentrain_validate` before `contentrain_submit`
+5. **Batch changes** — group related saves, validate once, submit once
+6. **Normalize = review** — normalize operations ALWAYS use review workflow, never auto-merge
+
+## Git Workflow
+
+- A dedicated `contentrain` branch is the single source of truth for content state, created at init
+- Every write operation creates a temporary worktree on the `contentrain` branch automatically
+- Feature branches (`contentrain/{operation}/{model}/{locale}/{timestamp}`) are created from `contentrain` for each operation
+- **auto-merge** mode: feature branch merges into `contentrain`, then `contentrain` advances baseBranch via update-ref (fast-forward), then `.contentrain/` files are selectively synced to the developer's working tree
+- **review** mode: feature branch pushed to remote for team review
+- Developer's working tree is never mutated during MCP git operations (no stash, no checkout, no merge on the developer's tree)
+- If the developer manually edits `.contentrain/` files, MCP sync skips dirty files and warns
+- The `contentrain` branch is protected from deletion
+- context.json is committed together with content changes, not as a separate commit
+- Never create branches manually, never commit directly to main or the `contentrain` branch
+- 50+ active branches = warning, 80+ = blocked
+
+## Localization
+
+- All supported locales must have entries for every content item
+- Collection entry IDs and dictionary keys must match across all locales
+- IDs and slugs are locale-agnostic — same reference works everywhere
+
+## Security
+
+- No `<script>`, `javascript:`, or event handlers in richtext/markdown
+- No secrets (API keys, tokens, passwords) in any content field
+- URLs must use `https://` (except localhost). No `file://`, no path traversal
+- Media paths must be relative to `assets_path`, no absolute system paths

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/rules",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "license": "MIT",
   "description": "AI agent rules for Contentrain — quality standards, architecture conventions, IDE integration",
   "type": "module",
@@ -34,27 +34,24 @@
       "require": "./dist/index.cjs",
       "default": "./dist/index.mjs"
     },
-    "./shared/*": "./shared/*",
+    "./essential/*": "./essential/*",
     "./prompts/*": "./prompts/*",
-    "./context/*": "./context/*",
-    "./ide/*": "./ide/*"
+    "./context/*": "./context/*"
   },
   "files": [
     "dist",
-    "shared",
+    "essential",
     "prompts",
-    "context",
-    "ide"
+    "context"
   ],
   "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",
+    "build": "tsdown src/index.ts --format esm,cjs --dts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }

package/prompts/generate-mode.md

@@ -173,7 +173,7 @@ Call `contentrain_validate` after all content is created.
 
 Call `contentrain_submit` to finalize.
 
-- In `auto-merge` mode: branch is merged to main, content is published.
+- In `auto-merge` mode: feature branch is merged into `contentrain`, baseBranch is advanced via update-ref, `.contentrain/` files are selectively synced to the developer's working tree, content is published.
 - In `review` mode: branch is pushed to remote for team review.
 - Normalize operations always use review mode regardless of config.