@contentrain/rules 0.2.0 → 0.3.1

package/ide/claude-code/rules/contentrain-accessibility-rules.md

@@ -1,155 +0,0 @@
-# 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.

package/ide/claude-code/rules/contentrain-content-conventions.md

@@ -1,314 +0,0 @@
-# Contentrain Content Conventions
-
-> These rules govern how content is structured, stored, and serialized in the `.contentrain/` directory. Follow them exactly when creating or modifying content through MCP tools.
-
----
-
-## 1. Directory Structure
-
-All Contentrain data lives under the `.contentrain/` directory at the project root. Understand every subdirectory's purpose before reading or writing.
-
-```
-.contentrain/
-  config.json               # Project configuration (stack, workflow, locales, domains)
-  vocabulary.json            # Canonical terms for consistent terminology
-  context.json               # Project intelligence — MCP writes after every write op, agents READ ONLY
-  assets.json                # Media asset registry
-  models/
-    {model-id}.json          # Model definitions (one file per model)
-  content/
-    {domain}/
-      {model-id}/
-        en.json              # Content per locale (i18n: true)
-        tr.json
-        data.json            # Content without locale (i18n: false)
-        {slug}/              # Document kind only
-          en.md
-          tr.md
-  meta/
-    {model-id}/
-      {locale}.json          # System-managed metadata
-      {slug}/                # Document kind only
-        {locale}.json
-  client/                    # SDK generated client — auto-generated, NEVER edit
-  assets/                    # Media files (images, videos, documents)
-```
-
-### Critical Boundaries
-
-- **NEVER write to `.contentrain/meta/`** -- metadata is system-managed (status, source, updated_by, approved_by).
-- **NEVER edit `.contentrain/client/`** -- this is auto-generated by `contentrain generate`.
-- **NEVER edit `.contentrain/context.json`** -- MCP writes it; agents read it for project intelligence.
-- **ALWAYS use MCP tools** to create/update content and models. Do not write JSON files directly.
-
----
-
-## 2. config.json Structure
-
-The project configuration file controls global behavior. It is created by `contentrain_init`.
-
-```json
-{
-  "version": 1,
-  "stack": "nuxt",
-  "workflow": "auto-merge",
-  "repository": {
-    "provider": "github",
-    "owner": "contentrain",
-    "name": "demo",
-    "default_branch": "main"
-  },
-  "locales": {
-    "default": "en",
-    "supported": ["en", "tr"]
-  },
-  "domains": ["blog", "marketing", "system"],
-  "assets_path": ".contentrain/assets",
-  "branchRetention": 30
-}
-```
-
-### Field Reference
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `version` | `number` | Config schema version. Always `1`. |
-| `stack` | `string` | Detected or set framework: `"nuxt"`, `"next"`, `"astro"`, `"sveltekit"`, `"react"`, `"node"` |
-| `workflow` | `string` | `"auto-merge"` (solo dev) or `"review"` (team governance) |
-| `repository` | `object` | Git remote info. Provider is always `"github"` in v1. |
-| `locales.default` | `string` | Primary locale (ISO 639-1) |
-| `locales.supported` | `string[]` | All locales including default |
-| `domains` | `string[]` | Organizational groups for content (e.g., `"blog"`, `"marketing"`, `"system"`) |
-| `assets_path` | `string` | Path for media files |
-| `branchRetention` | `number` | Days to keep merged branches |
-
----
-
-## 3. Content File Formats by Model Kind
-
-Each of the 4 model kinds has a distinct storage format. Know them precisely.
-
-### 3.1 Singleton
-
-One JSON object per locale file. No `id` field.
-
-**Path:** `.contentrain/content/{domain}/{model-id}/{locale}.json`
-
-```json
-{
-  "cta": "Get Started",
-  "subtitle": "The modern content platform",
-  "title": "Build faster"
-}
-```
-
-**Use for:** Hero sections, navigation, site config, form labels -- anything with exactly one instance per locale.
-
-### 3.2 Collection
-
-Object-map on disk: keys are entry IDs, sorted lexicographically. The `id` field is the key itself and is NOT stored inside the entry object.
-
-**Path:** `.contentrain/content/{domain}/{model-id}/{locale}.json`
-
-```json
-{
-  "a1b2c3d4e5f6": {
-    "avatar": "assets/ahmet.jpg",
-    "name": "Ahmet",
-    "role": "CEO"
-  },
-  "f6e5d4c3b2a1": {
-    "avatar": "assets/jane.jpg",
-    "name": "Jane",
-    "role": "CTO"
-  }
-}
-```
-
-**MCP output format differs from storage:** MCP tools return collections as arrays with `id` injected:
-
-```json
-[
-  { "id": "a1b2c3d4e5f6", "name": "Ahmet", "role": "CEO", "avatar": "assets/ahmet.jpg" },
-  { "id": "f6e5d4c3b2a1", "name": "Jane", "role": "CTO", "avatar": "assets/jane.jpg" }
-]
-```
-
-**Why object-map?**
-- Sorted keys produce predictable diffs and minimize Git merge conflicts.
-- No ID duplication -- key IS the ID.
-- Consistent structure with metadata files.
-
-### 3.3 Document
-
-Markdown file with YAML-like frontmatter. One file per slug per locale.
-
-**Path:** `.contentrain/content/{domain}/{model-id}/{slug}/{locale}.md`
-
-```markdown
----
-title: Getting Started
-slug: getting-started
-author: a1b2c3d4e5f6
-tags: [tutorial, intro]
----
-# Getting Started with Contentrain
-
-Your markdown body content here...
-```
-
-**Use for:** Blog posts, documentation pages, changelogs -- long-form content with typed metadata.
-
-### 3.4 Dictionary
-
-Flat key-value JSON per locale. No `fields` in the model definition -- all values are strings.
-
-**Path:** `.contentrain/content/{domain}/{model-id}/{locale}.json`
-
-```json
-{
-  "auth.expired": "Session expired",
-  "auth.failed": "Authentication failed",
-  "validation.required": "{field} is required"
-}
-```
-
-**Use for:** Error messages, UI strings, i18n translation files, mobile app strings.
-
----
-
-## 4. Canonical Serialization Rules
-
-ALL JSON files in `.contentrain/` MUST follow these rules for deterministic, git-friendly output:
-
-1. **Keys sorted lexicographically** within every object (including nested objects).
-2. **2-space indent** for all nesting levels.
-3. **UTF-8 encoding** without BOM.
-4. **Trailing newline** at end of file (single `\n` after closing brace/bracket).
-5. **Omit null values** -- do not write `"field": null`.
-6. **Omit default values** -- if `required` is `false`, do not include it. If `default` is `null`, do not include it.
-7. **Field key order in content entries** follows the model definition insertion order for readability, but storage uses lexicographic sort for determinism.
-
-### Why This Matters
-
-- Deterministic output means identical data always produces identical files.
-- Sorted keys prevent artificial Git diffs from key reordering.
-- Clean diffs enable meaningful code review of content changes.
-
----
-
-## 5. System Fields
-
-Several fields are managed by the platform. Agents MUST NOT set or modify them.
-
-| Field | Where | Managed By |
-|-------|-------|------------|
-| `id` | Collection entry key | Auto-generated 12-char hex UUID |
-| `slug` | Document directory name | Derived from content or set by agent via `slug` field |
-| `createdAt` | Not stored | Derived from Git commit history |
-| `updatedAt` | Not stored | Derived from Git commit history |
-| `status` | `.contentrain/meta/` | Platform workflow engine |
-| `source` | `.contentrain/meta/` | Set by MCP: `"agent"`, `"human"`, or `"import"` |
-| `updated_by` | `.contentrain/meta/` | Set by MCP: agent name or user email |
-| `approved_by` | `.contentrain/meta/` | Set by Studio on review approval |
-
-**Rule:** When creating content via `contentrain_content_save`, provide only the content fields defined in the model. Do not include `id`, `createdAt`, `updatedAt`, `status`, or any metadata fields.
-
----
-
-## 6. Localization Rules
-
-| Rule | Detail |
-|------|--------|
-| `i18n: true` on model | Each locale gets its own file: `en.json`, `tr.json`, etc. |
-| `i18n: false` on model | Single file: `data.json` (or `{slug}.md` for documents) |
-| Locale code | ISO 639-1: `en`, `tr`, `de`, `fr`, `ja`, `ar` |
-| ID/slug are locale-agnostic | The same entry ID or document slug is used across all locales |
-| Entry parity (collections) | All locales MUST have the same set of entry IDs |
-| Key parity (dictionaries) | All locales MUST have the same set of keys |
-
-### Validation Checks
-
-| Check | Severity | Example |
-|-------|----------|---------|
-| Missing locale file | Error | `hero: tr.json missing` |
-| Collection entry ID mismatch | Error | `team-members: entry "member-2" missing in tr` |
-| Dictionary key missing | Warning | `error-messages: tr missing 5 keys` |
-| Document missing translation | Warning | `blog-post: "getting-started" has no tr translation` |
-
----
-
-## 7. Vocabulary
-
-The `vocabulary.json` file provides canonical terms for consistent content.
-
-```json
-{
-  "version": 1,
-  "terms": {
-    "email": { "en": "Email", "tr": "E-posta" },
-    "sign-up": { "en": "Sign Up", "tr": "Kayit Ol" }
-  }
-}
-```
-
-### Rules
-
-- **Check vocabulary FIRST** before writing any content. Use existing terms when they match.
-- **Add new terms** to the vocabulary when creating content with reusable terminology.
-- **Term keys** are kebab-case identifiers.
-- **Each term** maps to locale-specific approved strings.
-- Vocabulary ensures consistency across models, locales, and agent sessions.
-
----
-
-## 8. context.json
-
-MCP writes `context.json` after every write operation. It provides project intelligence for agents and Studio synchronization.
-
-```json
-{
-  "version": "1.0",
-  "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"
-  }
-}
-```
-
-### Rules
-
-- **Read only** -- agents MUST NOT write to this file.
-- **Use it for awareness** -- check last operation, entry counts, locale coverage.
-- `source` values: `"mcp-local"` (IDE), `"mcp-studio"` (Studio server-side), `"studio-ui"` (Studio direct).
-- Updated only on write operations (not reads).
-- Git-tracked within `.contentrain/`.
-
----
-
-## 9. Assets
-
-Media files are stored in the configured `assets_path`. The `assets.json` file tracks registered assets.
-
-```json
-[
-  { "path": "assets/hero.webp", "type": "image/webp", "size": 245680, "alt": "Hero background" }
-]
-```
-
-### Rules for Media References
-
-- Use relative paths from the `.contentrain/` root in content fields.
-- Media field types (`image`, `video`, `file`) store string path references.
-- In v1, media fields are URL/path strings only. Upload and processing are out of scope.
-- Always provide `alt` text for images when the information is available.