@contentrain/rules 0.3.2 → 0.4.0

package/README.md

@@ -10,15 +10,16 @@ Shared AI-agent rules for Contentrain.
 Start here:
 
 - [2-minute product demo](https://ai.contentrain.io/demo)
-- [Rules & skills docs](https://ai.contentrain.io/packages/rules)
+- [Rules & skills docs](https://ai.contentrain.io/packages/rules)
 
-This package is the policy layer of the Contentrain ecosystem. It defines how agents should behave when they work with:
+This package is the **policy layer** of the Contentrain ecosystem. It defines how agents should behave when they work with:
 
-- Contentrain MCP tools
+- Contentrain MCP tools (17 operations)
 - schema and model design
-- content quality
-- normalize workflows
+- content quality (SEO, accessibility, media, i18n)
+- normalize workflows (extraction + reuse)
 - git-backed review flows
+- security guardrails
 
 If `@contentrain/mcp` is the deterministic execution layer, `@contentrain/rules` is the behavioral contract.
 
@@ -32,71 +33,100 @@ pnpm add @contentrain/rules
 
 ### Essential guardrails
 
-Published under `essential/*`:
+Published under `essential/`:
 
-- `contentrain-essentials.md` — compact, always-loaded rules (~86 lines) covering architecture, model kinds, MCP tools, mandatory protocols, and security basics
+- `contentrain-essentials.md` — compact, always-loaded rules covering architecture, model kinds, MCP tools, mandatory protocols, git workflow, and security basics.
+
+### Shared quality rules
+
+Published under `shared/` — detailed standards per domain:
+
+- `content-quality.md` — structure, required fields, content completeness
+- `seo-rules.md` — meta optimization, keywords, canonical URLs
+- `accessibility-rules.md` — alt text, ARIA labels, color contrast
+- `media-rules.md` — image optimization, responsive sizing, asset naming
+- `schema-rules.md` — model design, field types, relations, inheritance
+- `i18n-quality.md` — translation completeness, locale parity
+- `security-rules.md` — sensitive data patterns, secret detection, XSS prevention
+- `mcp-usage.md` — tool invocation patterns, git workflows, trust levels
+- `normalize-rules.md` — extraction and reuse constraints, scope safety
+- `workflow-rules.md` — review mode, approval flows, branch lifecycle
+- `content-conventions.md` — naming, slug generation, status conventions
 
 ### Prompt layers
 
-Published under `prompts/*`:
+Published under `prompts/` — mode-specific context the agent loads per task:
 
-- `common.md`
-- `generate-mode.md`
-- `normalize-mode.md`
-- `review-mode.md`
+- `common.md` — shared preamble for all agent modes
+- `generate-mode.md` — content creation constraints
+- `normalize-mode.md` — string extraction and patching workflows
+- `review-mode.md` — content validation and change review
 
 ### Context bridge
 
-Published under `context/*`:
+Published under `context/`:
 
-- `context-bridge.md`
+- `context-bridge.md` — how to integrate rules into agent context systems
+- `templates/` — framework-specific context JSON for `nuxt`, `next`, `astro`, `sveltekit`
 
 ## Public Exports
 
-The package root exports constants that can be used by tooling:
+The package root exports constants for tooling:
 
 - `FIELD_TYPES` — 27 flat field types
-- `MODEL_KINDS` — singleton, collection, document, dictionary
-- `MCP_TOOLS` — 15 MCP tool names
+- `MODEL_KINDS` — `singleton`, `collection`, `document`, `dictionary`
+- `MCP_TOOLS` — 17 MCP tool names (includes `contentrain_merge` and `contentrain_doctor`)
 - `ESSENTIAL_RULES_FILE` — path to essential guardrails markdown
 - `STACKS` — supported framework stacks
 
-## Example
+## Quick Example
 
 ```ts
 import { MCP_TOOLS, ESSENTIAL_RULES_FILE, FIELD_TYPES } from '@contentrain/rules'
 
-console.log(MCP_TOOLS.includes('contentrain_validate'))
-console.log(ESSENTIAL_RULES_FILE) // 'essential/contentrain-essentials.md'
-console.log(FIELD_TYPES.length)   // 27
+console.log(MCP_TOOLS.length)                            // 17
+console.log(MCP_TOOLS.includes('contentrain_merge'))     // true
+console.log(MCP_TOOLS.includes('contentrain_doctor'))    // true
+console.log(ESSENTIAL_RULES_FILE)                        // 'essential/contentrain-essentials.md'
+console.log(FIELD_TYPES.length)                          // 27
 ```
 
 ## Design Role
 
 `@contentrain/rules` exists to keep agent behavior aligned across tools and environments.
 
-It should answer questions like:
+Typical questions it answers:
+
+- What is acceptable content quality? (shared quality rules)
+- How should an agent use MCP tools safely? (mcp-usage + tool reference)
+- What is the normalize contract? (normalize-rules)
+- What workflow and review constraints exist? (workflow-rules)
+
+Detailed procedures and step-by-step guides live in `@contentrain/skills` (Agent Skills standard format).
+
+## Parity with `@contentrain/mcp`
+
+`@contentrain/rules` is kept in lockstep with the MCP tool registry via cross-package parity tests. When a new MCP tool is registered in `@contentrain/mcp`:
 
-- What is acceptable content quality?
-- How should an agent use MCP tools?
-- What is the normalize contract?
-- What workflow and review constraints exist?
+- `MCP_TOOLS` must include it (otherwise `tests/mcp-parity.test.ts` fails)
+- the essentials document must mention it
+- the skills reference must have a `### <tool>` section
 
-Detailed reference material and step-by-step procedures live in `@contentrain/skills` (Agent Skills standard format).
+When MCP's branch-naming convention changes (e.g. `contentrain/*` → `cr/*`), the rules prose must follow — the parity test scans the rules for the legacy prefix and fails if it reappears.
 
 ## Relationship To Other Packages
 
 - `@contentrain/mcp` enforces file, validation, and git behavior
 - `@contentrain/skills` provides Agent Skills with progressive disclosure (SKILL.md + references/)
-- `contentrain` exposes CLI and serve UX
+- `contentrain` (CLI) installs rules + skills into the IDE during `contentrain init`
 - `@contentrain/query` is the generated runtime consumption layer
 
 Rule of thumb:
 
-- `rules` = essential guardrails (always loaded, ~86 lines)
-- `skills` = detailed procedures and reference docs (on-demand)
+- `rules` = policy layer (quality standards, constraints, essentials)
+- `skills` = procedural layer (workflows, detailed reference docs)
 
-See [`AGENTS.md`](../../AGENTS.md) at the repo root for agent-level project guidance.
+See [`AGENTS.md`](../../AGENTS.md) at the repo root for project-level agent guidance.
 
 ## Build
 

package/dist/index.cjs

@@ -55,7 +55,9 @@ const MCP_TOOLS = [
 	"contentrain_apply",
 	"contentrain_validate",
 	"contentrain_submit",
-	"contentrain_bulk"
+	"contentrain_merge",
+	"contentrain_bulk",
+	"contentrain_doctor"
 ];
 const ESSENTIAL_RULES_FILE = "essential/contentrain-essentials.md";
 const STACKS = [

package/dist/index.d.cts

@@ -8,7 +8,7 @@ declare const FIELD_TYPES: readonly ["string", "text", "email", "url", "slug", "
 type FieldType = (typeof FIELD_TYPES)[number];
 declare const MODEL_KINDS: readonly ["singleton", "collection", "document", "dictionary"];
 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"];
+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_merge", "contentrain_bulk", "contentrain_doctor"];
 type McpTool = (typeof MCP_TOOLS)[number];
 declare const ESSENTIAL_RULES_FILE: "essential/contentrain-essentials.md";
 declare const STACKS: readonly ["nuxt", "next", "astro", "sveltekit", "react", "node"];

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,oBAAA;AAAA,cAIA,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,KAYD,OAAA,WAAkB,SAAA;AAAA,cAIjB,oBAAA;AAAA,cAIA,MAAA;AAAA,KACD,KAAA,WAAgB,MAAA"}

package/dist/index.d.mts

@@ -8,7 +8,7 @@ declare const FIELD_TYPES: readonly ["string", "text", "email", "url", "slug", "
 type FieldType = (typeof FIELD_TYPES)[number];
 declare const MODEL_KINDS: readonly ["singleton", "collection", "document", "dictionary"];
 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"];
+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_merge", "contentrain_bulk", "contentrain_doctor"];
 type McpTool = (typeof MCP_TOOLS)[number];
 declare const ESSENTIAL_RULES_FILE: "essential/contentrain-essentials.md";
 declare const STACKS: readonly ["nuxt", "next", "astro", "sveltekit", "react", "node"];

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,oBAAA;AAAA,cAIA,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,KAYD,OAAA,WAAkB,SAAA;AAAA,cAIjB,oBAAA;AAAA,cAIA,MAAA;AAAA,KACD,KAAA,WAAgB,MAAA"}

package/dist/index.mjs

@@ -54,7 +54,9 @@ const MCP_TOOLS = [
 	"contentrain_apply",
 	"contentrain_validate",
 	"contentrain_submit",
-	"contentrain_bulk"
+	"contentrain_merge",
+	"contentrain_bulk",
+	"contentrain_doctor"
 ];
 const ESSENTIAL_RULES_FILE = "essential/contentrain-essentials.md";
 const STACKS = [

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// ─── 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"}
+{"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 (17 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_merge',\n  'contentrain_bulk',\n  'contentrain_doctor',\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;CACA;CACA;CACD;AAMD,MAAa,uBAAuB;AAIpC,MAAa,SAAS;CAAC;CAAQ;CAAQ;CAAS;CAAa;CAAS;CAAO"}

package/essential/contentrain-essentials.md

@@ -54,6 +54,7 @@ MCP is **deterministic infrastructure**. The agent (you) is the **intelligence l
 | `contentrain_submit` | Push branches to remote |
 | `contentrain_merge` | Merge a review-mode branch into contentrain locally |
 | `contentrain_bulk` | Batch operations (copy_locale/update_status/delete_entries) |
+| `contentrain_doctor` | Project health report (env + structure + orphan content + branch pressure + SDK freshness) |
 
 ## Mandatory Protocols
 
@@ -68,7 +69,7 @@ MCP is **deterministic infrastructure**. The agent (you) is the **intelligence l
 
 - 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
+- Feature branches (`cr/{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)
@@ -76,7 +77,7 @@ MCP is **deterministic infrastructure**. The agent (you) is the **intelligence l
 - 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
+- 50+ active `cr/*` branches = warning, 80+ = blocked
 
 ## CLI Serve — Review & Approval
 
@@ -111,6 +112,13 @@ This regenerates `.contentrain/client/` — required for `#contentrain` imports
 - Collection entry IDs and dictionary keys must match across all locales
 - IDs and slugs are locale-agnostic — same reference works everywhere
 
+## Content Governance
+
+- **No duplicate values** — before creating a dictionary key, check if the value already exists under another key (MCP warns automatically via advisories)
+- **Vocabulary first** — check `.contentrain/vocabulary.json` for canonical terms before creating content. Use approved terms exactly, do not invent synonyms
+- **Run validation** — after bulk content operations, call `contentrain_validate` to catch duplicate values, missing translations, and schema issues
+- **Periodic health check** — run `contentrain doctor --usage` to detect unused keys, duplicate values, and locale coverage gaps
+
 ## Security
 
 - No `<script>`, `javascript:`, or event handlers in richtext/markdown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/rules",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "license": "MIT",
   "description": "AI agent rules for Contentrain — quality standards, architecture conventions, IDE integration",
   "type": "module",
@@ -39,12 +39,14 @@
       "default": "./dist/index.mjs"
     },
     "./essential/*": "./essential/*",
+    "./shared/*": "./shared/*",
     "./prompts/*": "./prompts/*",
     "./context/*": "./context/*"
   },
   "files": [
     "dist",
     "essential",
+    "shared",
     "prompts",
     "context"
   ],
@@ -52,7 +54,8 @@
     "@types/node": "^22.0.0",
     "tsdown": "^0.21.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "@contentrain/mcp": "1.3.0"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm,cjs --dts",

package/prompts/normalize-mode.md

@@ -12,7 +12,7 @@ This mode converts a codebase with hardcoded strings into a Contentrain-managed
 |--------|---------------------|----------------|
 | 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}` |
+| Branch pattern | `cr/normalize/extract/{domain}/{timestamp}` | `cr/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 |

package/prompts/review-mode.md

@@ -2,14 +2,14 @@
 
 > **Prerequisites:** Read `prompts/common.md` first. All shared rules apply.
 
-This mode is for reviewing content changes on pending `contentrain/*` branches before they are merged. You act as a content quality reviewer, applying all Contentrain rules systematically.
+This mode is for reviewing content changes on pending `cr/*` branches before they are merged. You act as a content quality reviewer, applying all Contentrain rules systematically.
 
 ---
 
 ## Pipeline
 
 ```
-Step 1: List open contentrain/* branches
+Step 1: List open cr/* branches
 Step 2: Show diffs for selected branch
 Step 3: Apply review checklist
 Step 4: Recommend action
@@ -19,19 +19,19 @@ Step 4: Recommend action
 
 ## Step 1: List Pending Branches
 
-Call `contentrain_status` to see pending changes and open branches. Identify branches with the `contentrain/` prefix that are awaiting review.
+Call `contentrain_status` to see pending changes and open branches. Identify branches with the `cr/` prefix that are awaiting review.
 
 Branch naming convention:
 ```
-contentrain/{operation}/{model}/{locale}/{timestamp}
+cr/{operation}/{model}/{locale}/{timestamp}
 ```
 
 Common branch types:
-- `contentrain/content/...` — content updates
-- `contentrain/model/...` — model changes
-- `contentrain/normalize/extract/...` — normalize extraction
-- `contentrain/normalize/reuse/...` — normalize reuse (source patching)
-- `contentrain/new/scaffold-...` — scaffold operations
+- `cr/content/...` — content updates
+- `cr/model/...` — model changes
+- `cr/normalize/extract/...` — normalize extraction
+- `cr/normalize/reuse/...` — normalize reuse (source patching)
+- `cr/new/scaffold-...` — scaffold operations
 
 ---
 

package/shared/accessibility-rules.md

@@ -0,0 +1,155 @@
+# Accessibility Rules
+
+These rules are MANDATORY for all AI agents creating or editing content in Contentrain projects.
+Violations will be flagged during validation. No exceptions unless explicitly overridden by `context.json` configuration.
+
+---
+
+## Image Accessibility
+
+1. Every `image` type field MUST have a corresponding alt text value. If the model defines an `image_alt` field, populate it. If not, include alt text guidance in the image field's `description` metadata.
+
+2. Alt text MUST describe the image's **content and function**, not its appearance.
+   - GOOD: `"CEO Jane Doe speaking at the 2024 product launch"`
+   - BAD: `"A photo with blue tones and a person on stage"`
+
+3. Decorative images (visual separators, background textures) MUST have alt text set to an empty string `""`. Never leave alt text undefined or null — explicitly set it to `""`.
+
+4. Complex images (charts, infographics, diagrams) MUST have a short alt text summarizing the conclusion, plus a detailed description in an adjacent text field or in the body content.
+   - Example alt: `"Bar chart showing Q3 revenue grew 22% year-over-year"`
+   - Example adjacent text: full data table or written summary
+
+5. Alt text MUST NOT exceed **125 characters**. Screen readers may truncate longer text.
+
+6. Icon images used as interactive elements MUST have alt text describing the **action**, not the icon.
+   - GOOD: `"Search"`, `"Close menu"`, `"Open settings"`
+   - BAD: `"Magnifying glass icon"`, `"X icon"`
+
+7. Do not begin alt text with "Image of" or "Photo of" — the screen reader already announces it as an image.
+
+---
+
+## Language & Readability
+
+1. Target a **grade 8-10 reading level** (Flesch-Kincaid) for general content.
+
+2. Target **grade 6-8** for public-facing critical content: legal notices, safety information, error messages, onboarding flows.
+
+3. Use plain language. Prefer common words over formal synonyms:
+   - "use" not "utilize"
+   - "start" not "commence"
+   - "help" not "facilitate"
+   - "buy" not "purchase"
+   - "end" not "terminate"
+
+4. Define every acronym and abbreviation on first use: `"Content Management System (CMS)"`. After the first definition, use the acronym freely.
+
+5. Do not use jargon unless the content targets a technical audience. Check `context.json > tone` to determine the audience. When `tone` is `"technical"`, domain-specific terms are acceptable without definitions.
+
+6. Keep sentences short: **15-20 words average**. Break long sentences at natural clause boundaries.
+
+7. Keep paragraphs short: **3-5 sentences maximum**. Use line breaks between paragraphs.
+
+8. Use active voice. Passive voice is acceptable only when the actor is unknown or irrelevant.
+   - GOOD: `"The system saves your changes automatically."`
+   - BAD: `"Your changes are saved automatically by the system."`
+
+---
+
+## Link Text
+
+1. Link text MUST be descriptive and self-explanatory. It must make sense **out of context** because screen readers present links in an isolated list.
+   - GOOD: `"Download the 2024 Annual Report"`
+   - BAD: `"Click here"`
+
+2. NEVER use these as standalone link text: `"click here"`, `"read more"`, `"learn more"`, `"here"`, `"link"`, `"this"`.
+
+3. For file downloads, include the file type and size in the link text:
+   - `"Download the Q3 Budget (PDF, 2.4 MB)"`
+
+4. Do not use the raw URL as link text unless the content is specifically listing URLs.
+
+5. Keep link text concise — describe the destination or action in 2-8 words.
+
+---
+
+## Heading Semantics
+
+1. Headings MUST describe the content of their section. Never use headings purely for visual styling (font size, bold).
+
+2. Heading levels MUST reflect **document hierarchy**:
+   - `h2` for top-level sections within the page
+   - `h3` for subsections of an `h2`
+   - `h4` for subsections of an `h3`
+   - Never skip levels (e.g., `h2` directly to `h4`)
+
+3. Every distinct content section SHOULD have a heading.
+
+4. Headings MUST NOT be empty or contain only whitespace.
+
+5. Do not duplicate heading text within the same page unless sections are genuinely distinct (e.g., "Overview" under two different parent headings is acceptable).
+
+---
+
+## Content Structure
+
+1. Use **semantic markup** appropriate to the content type:
+   - Unordered lists (`ul`) for items without sequence
+   - Ordered lists (`ol`) for steps or ranked items
+   - Headings for section titles
+   - Paragraphs for body text
+   - Blockquotes for quoted material
+
+2. Tables MUST include a header row or header column. Keep table structure simple — avoid merged cells and nested tables.
+
+3. Provide a text alternative for every piece of non-text content (images, charts, embedded media).
+
+4. Sequential content (steps, instructions, timelines) MUST follow logical reading order. Do not rely on CSS or layout to reorder content.
+
+5. Lists MUST have at least two items. A single-item list should be rewritten as a paragraph or inline text.
+
+---
+
+## Color & Visual References
+
+1. NEVER use color alone to convey meaning.
+   - BAD: `"Required fields are highlighted in red."`
+   - GOOD: `"Required fields are marked with an asterisk (*)."`
+
+2. Do not reference visual position in content text.
+   - BAD: `"Click the button on the right."`
+   - GOOD: `"Click the Submit button."`
+
+3. Ensure all text content is meaningful without any visual context. Content must be understandable when read aloud or rendered in plain text.
+
+---
+
+## Error Messages & Forms
+
+1. Error messages MUST identify **which field** has the error.
+
+2. Error messages MUST describe **what the error is** and how to fix it.
+   - GOOD: `"Enter a valid email address (e.g., name@example.com)."`
+   - BAD: `"Invalid input."`
+
+3. Use **positive framing** — tell the user what to do, not what they did wrong.
+   - GOOD: `"Enter a date in YYYY-MM-DD format."`
+   - BAD: `"Wrong date format."`
+
+4. Group related form fields with descriptive labels. Every input field MUST have a label.
+
+5. Do not use placeholder text as a substitute for labels.
+
+---
+
+## Multimedia
+
+1. Video content MUST reference a transcript — either as inline content, a URL, or a relation to a document entry.
+
+2. Audio content MUST have a text transcript available.
+
+3. If content auto-plays, note this in metadata so the frontend can provide pause/stop controls. Auto-playing media with audio is strongly discouraged.
+
+4. Time-based media (video, audio, animations) MUST include duration information when the model supports it.
+
+5. Animated content (GIFs, auto-playing videos) should be flagged if longer than 5 seconds — provide a mechanism to pause.