@contentrain/rules 0.3.1 → 0.3.3

package/shared/seo-rules.md

@@ -0,0 +1,224 @@
+# SEO Rules
+
+These rules govern search engine optimization for all content managed through Contentrain.
+Apply these rules to every content entry that produces a public-facing page.
+
+---
+
+## 1. Page Titles
+
+### 1.1 Length and Format
+
+- Length: 50-60 characters including spaces. Google truncates titles beyond ~60 characters.
+- Measure character count before saving. Truncated titles harm click-through rates.
+- No ALL CAPS titles. Use sentence case or title case per project convention.
+- No excessive punctuation: no `!!!`, no `???`, no `...` in titles.
+- No emoji in titles unless explicitly configured in `context.json`.
+
+### 1.2 Keyword Placement
+
+- Place the primary keyword within the first 30 characters.
+- Structure: `Primary Keyword Phrase | Brand Name` or `Primary Keyword Phrase — Brand Name`.
+- Acceptable separators: ` | `, ` — `, ` - `. Pick one and use it consistently across all entries.
+- The keyword must read naturally — no keyword stuffing.
+  - GOOD: "Deploy Node.js to Production | Acme Docs"
+  - BAD: "Node.js Deploy Node Production Deployment | Acme"
+
+### 1.3 Uniqueness
+
+- Every entry in a collection MUST have a unique title.
+- Before saving, query existing entries and confirm no title collision.
+- Titles across collections should also be unique when they produce public pages.
+
+---
+
+## 2. Meta Descriptions
+
+### 2.1 Length and Format
+
+- Length: 120-155 characters including spaces.
+- Must be a complete sentence or two short sentences.
+- End with a period.
+- No keyword stuffing — write for humans, not crawlers.
+
+### 2.2 Content Requirements
+
+- Include a clear value proposition or call-to-action.
+  - GOOD: "Learn how to set up CI/CD for your Node.js project in 10 minutes. Step-by-step guide with examples."
+  - BAD: "CI/CD Node.js setup guide tutorial deployment continuous integration."
+- Must differ from the page title — do not repeat the title as the description.
+- Must be unique per entry. No two entries may share the same meta description.
+
+### 2.3 What to Avoid
+
+- No quotes or special characters that break HTML meta tags: avoid `"`, `<`, `>`.
+- No "Click here to learn more" — search engines ignore generic CTAs.
+- No date references that will become stale (prefer "latest" over "2024").
+
+---
+
+## 3. Slugs
+
+### 3.1 Format
+
+- Lowercase only. No uppercase characters.
+- Words separated by hyphens (`-`). No underscores, no spaces, no dots.
+- No special characters: only `a-z`, `0-9`, and `-`.
+- No consecutive hyphens (`--`). No leading or trailing hyphens.
+
+### 3.2 Length and Content
+
+- Optimal: 3-5 words.
+- Maximum: 60 characters.
+- Remove stop words (`the`, `a`, `an`, `is`, `of`, `and`, `or`, `in`, `to`) unless removing them changes meaning.
+  - "how-to-deploy-node" → "deploy-node" is acceptable.
+  - "state-of-the-art" → keep as-is because meaning changes if shortened.
+
+### 3.3 Stability
+
+- NEVER change a slug on a published entry. Changing slugs breaks existing links, bookmarks, and search engine indexing.
+- If a slug must change, the human must set up a redirect. The agent must not change published slugs without explicit human instruction.
+- Draft entries may have their slugs changed freely before first publication.
+
+### 3.4 Locale Consistency
+
+- Use the same slug value across all locales for the same entry.
+- Do NOT translate slugs. Slugs are identifiers, not content.
+- Example: the slug `deploy-node` remains `deploy-node` in `en`, `tr`, `de`, and all other locales.
+
+---
+
+## 4. Heading Structure
+
+### 4.1 H1 Rule
+
+- Exactly one H1 per page. The H1 is the entry title or the primary heading.
+- The H1 should contain the primary keyword naturally.
+- Do not duplicate the H1 text elsewhere on the page.
+
+### 4.2 Subheading Keywords
+
+- Include relevant keywords in H2 and H3 headings where natural.
+- Do not force keywords into every heading. Clarity takes priority over keyword density.
+- Use question-format headings for FAQ-style content: "How do I reset my password?"
+
+### 4.3 Hierarchy Reflects Content
+
+- Heading levels must reflect the logical structure of the content.
+- Do not use H3 because it renders smaller — use CSS for styling, headings for structure.
+- Every heading must have content beneath it. No empty sections.
+- Do not place two headings consecutively without content between them.
+
+---
+
+## 5. Images and Alt Text
+
+### 5.1 Alt Text Requirements
+
+- Every `image` field that displays on a public page MUST have corresponding alt text.
+- Describe the image content and its context: "Dashboard showing monthly revenue chart with 15% growth indicator."
+- Maximum length: 125 characters.
+- Do not start with "Image of", "Photo of", "Picture of" — describe directly.
+
+### 5.2 Decorative Images
+
+- If an image is purely decorative (visual separator, background pattern), set alt text to an empty string (`""`).
+- Do not omit the alt field entirely — explicitly set it to empty.
+
+### 5.3 Keywords in Alt Text
+
+- Include relevant keywords naturally when they describe the image.
+- Do not stuff keywords: "Node.js Node deployment Node server Node production" is forbidden.
+- The alt text must accurately describe what is in the image.
+
+### 5.4 Image File Names
+
+- When the agent controls the image file name, use descriptive, hyphenated names.
+  - GOOD: `revenue-dashboard-chart.png`
+  - BAD: `IMG_2847.png`, `screenshot.png`, `image1.png`
+
+---
+
+## 6. Open Graph and Social Media
+
+### 6.1 Open Graph Tags
+
+When OG fields exist in the model, populate them:
+
+| Field | Max Length | Requirement |
+|---|---|---|
+| `og:title` | 60 characters | Concise version of the page title |
+| `og:description` | 200 characters | Slightly longer than meta description, conversational |
+| `og:image` | — | 1200x630 pixels recommended, must be absolute URL |
+| `og:type` | — | `article` for blog/docs, `website` for landing pages |
+
+### 6.2 Twitter Card
+
+- Use `summary_large_image` for content with strong visual elements.
+- Use `summary` for text-focused content.
+- Twitter title and description may differ from OG — optimize for each platform.
+
+### 6.3 Fallback
+
+- If OG-specific fields are absent, the system uses the standard title and description.
+- Ensure the standard title and description are suitable for social sharing.
+
+---
+
+## 7. Internal Linking
+
+### 7.1 Relation Fields
+
+- Use Contentrain `relation` and `relations` model fields for cross-references between entries.
+- Prefer structured relations over hardcoded links in body content.
+- Structured relations are maintainable — if a slug changes, relations still resolve.
+
+### 7.2 Bidirectional Relations
+
+- When Entry A references Entry B, check if Entry B should reference Entry A.
+- Example: if a blog post links to a product, the product's "related articles" should include that blog post.
+- The agent should suggest bidirectional relations but not create them without confirmation.
+
+### 7.3 Manual Links in Body Content
+
+- If the model does not have relation fields and links must be in body text, use relative paths.
+- Verify that linked entries exist before saving.
+- Do not link to draft or archived entries from published content.
+
+---
+
+## 8. URL and Canonical Rules
+
+### 8.1 Slug Patterns
+
+- All entries in a collection must follow the same slug pattern.
+- If existing entries use `verb-noun` format (e.g., `deploy-app`, `configure-server`), new entries must follow the same pattern.
+- Check existing entries before generating a slug for a new entry.
+
+### 8.2 Multi-Locale URLs
+
+- Same slug across all locales (see Section 3.4).
+- Locale prefix is handled by the frontend routing, not by the content slug.
+- Example: `/en/deploy-node` and `/tr/deploy-node` share the slug `deploy-node`.
+
+### 8.3 Trailing Slashes
+
+- The agent does not control trailing slash behavior — this is a frontend routing concern.
+- Ensure slug values do not include leading or trailing slashes.
+
+---
+
+## Validation Checklist
+
+Before committing any content with SEO impact, verify:
+
+- [ ] Title is 50-60 characters, primary keyword near start, unique
+- [ ] Meta description is 120-155 characters, complete sentence, unique
+- [ ] Slug is lowercase, hyphenated, 3-5 words, no special characters
+- [ ] Published slugs have not been changed
+- [ ] Slugs are identical across all locales for the same entry
+- [ ] One H1 per page, sequential heading hierarchy
+- [ ] All images have descriptive alt text (max 125 chars) or empty string for decorative
+- [ ] OG fields populated if model supports them
+- [ ] Relation fields used for internal cross-references
+- [ ] No keyword stuffing in titles, descriptions, headings, or alt text

package/shared/workflow-rules.md

@@ -0,0 +1,317 @@
+# Contentrain Workflow Rules
+
+> These rules govern how content changes flow through the Git-based workflow, including branching, validation, review, and status management.
+
+---
+
+## 1. Two Workflow Modes
+
+Contentrain supports two workflow modes, configured in `.contentrain/config.json` under the `workflow` field.
+
+### 1.1 auto-merge
+
+```json
+{ "workflow": "auto-merge" }
+```
+
+- Feature branch is created from the `contentrain` branch, changes are committed, feature branch is **merged into `contentrain`**, then baseBranch is advanced via **update-ref** (fast-forward), and `.contentrain/` files are **selectively synced** to the developer's working tree.
+- No review step -- changes go live immediately.
+- Best for: solo developers, rapid iteration, prototyping, vibe coding.
+- Status flow: `draft` --> `published` (skips `in_review`).
+
+### 1.2 review
+
+```json
+{ "workflow": "review" }
+```
+
+- Branch is created, changes are committed, branch is **pushed to remote**.
+- Studio or team reviews the changes before merging.
+- Best for: teams, content governance, production environments.
+- Status flow: `draft` --> `in_review` --> `published` | `rejected`.
+
+### 1.3 Mode Selection Rules
+
+- Default is `auto-merge` -- minimal friction for getting started.
+- Switch to `review` as the project or team grows and governance becomes important.
+- **Normalize operations ALWAYS use `review` mode** regardless of the config setting. Normalize changes are never auto-merged.
+
+---
+
+## 2. Branch Naming Convention
+
+All Contentrain branches follow a strict naming pattern:
+
+```
+contentrain/{operation}/{model}/{locale}/{timestamp}
+```
+
+### Examples
+
+| Scenario | Branch Name |
+|----------|-------------|
+| Content update | `contentrain/content/blog-post/en/1710300000` |
+| Model creation | `contentrain/model/team-member/1710300000` |
+| Normalize extraction | `contentrain/normalize/extract/blog/1710300000` |
+| Normalize reuse | `contentrain/normalize/reuse/marketing-hero/en/1710300000` |
+| Scaffold | `contentrain/new/scaffold-landing/en/1710300000` |
+
+### Rules
+
+- Branches are created automatically by MCP tools. Do NOT create them manually.
+- The `{timestamp}` component ensures uniqueness.
+- `{locale}` is included when the operation is locale-specific.
+- `{model}` is included when the operation targets a specific model.
+
+---
+
+## 3. Git Workflow
+
+### 3.1 Dedicated `contentrain` Branch
+
+The `contentrain` branch is the **single source of truth** for content state:
+
+- Created automatically at `contentrain_init`.
+- All content writes happen on feature branches forked from `contentrain`.
+- The `contentrain` branch is **protected from deletion**.
+- context.json is committed together with content changes, not as a separate commit.
+
+### 3.2 Worktree-Based Transactions
+
+Every write operation follows this flow:
+
+1. MCP creates a **temporary Git worktree** on a new feature branch forked from `contentrain`.
+2. Changes are made in the worktree (content files, model files, context.json).
+3. Changes are committed to the feature branch.
+4. **auto-merge mode:** Feature branch is merged into `contentrain`, then baseBranch is advanced via **update-ref** (fast-forward), then `.contentrain/` files are **selectively synced** to the developer's working tree. Dirty files are skipped with a warning. Worktree is cleaned up.
+5. **review mode:** Feature branch is pushed to remote for team review. Worktree is cleaned up. Studio notifies reviewers.
+
+Developer's working tree is **never mutated** during MCP git operations. There is no stash, no checkout, and no merge on the developer's tree.
+
+### 3.3 Developer Manual Editing
+
+If the developer manually edits `.contentrain/` files in their working tree, MCP selective sync skips those dirty files and issues a warning. The developer must commit or discard their local changes before MCP can sync those files.
+
+### 3.4 Critical Rules
+
+- **NEVER commit directly to main or the `contentrain` branch.** All changes go through feature branches.
+- **NEVER create branches manually.** MCP tools handle all Git operations.
+- **NEVER force-push or rebase** Contentrain branches.
+- **NEVER delete the `contentrain` branch.** It is the content state SSOT.
+- Worktrees are temporary. They are created for the operation and cleaned up afterward.
+- Each branch contains a cohesive set of changes (e.g., all entries for one model update).
+
+### 3.5 Branch Lifecycle
+
+```
+Feature branch created (worktree on contentrain)
+  --> Changes committed
+  --> auto-merge: feature merged into contentrain
+                  --> update-ref advances baseBranch
+                  --> selective sync .contentrain/ to developer's tree
+  --> review: feature pushed to remote, awaiting review
+  --> Worktree cleaned up
+```
+
+The `contentrain` branch is permanent and protected. Feature branches are retained for `branchRetention` days (default: 30) for audit trail, then pruned.
+
+### 3.6 Branch Health
+
+MCP enforces branch health limits to prevent branch accumulation:
+
+- **50+ active branches**: Warning. Operations continue but the user is alerted.
+- **80+ active branches**: Blocked. No new write operations until branches are merged or deleted.
+- `contentrain_status` reports branch health automatically (total, merged, unmerged counts).
+- Merged branches are cleaned up lazily during status checks and submit operations.
+
+---
+
+## 4. Conflict Resolution
+
+### 4.1 How Conflicts Are Minimized
+
+Contentrain's storage format is designed to minimize Git merge conflicts:
+
+- **Object-map storage** for collections: each entry is a separate key-value pair. Two branches adding different entries rarely conflict.
+- **Canonical serialization**: sorted keys and deterministic formatting prevent artificial diffs.
+- **Review mode for normalize**: separate branches for extraction and reuse reduce concurrent editing conflicts.
+
+### 4.2 When Conflicts Occur
+
+| Scenario | Likelihood | Resolution |
+|----------|-----------|------------|
+| Different fields on the same entry | Low | Auto-merge succeeds (JSON field-level merge) |
+| Same field changed by two branches | Medium | Studio conflict resolution UI |
+| Two entries added with adjacent IDs | Very low | Auto-merge usually succeeds |
+| Concurrent normalize operations | Avoided | Always review mode, sequential per model |
+
+### 4.3 Conflict Resolution Rules
+
+- Field-level merge for JSON: if the same entry has different fields changed in two branches, Git auto-merges.
+- Same field changed by multiple branches creates a conflict requiring Studio resolution.
+- When a conflict occurs, the agent should NOT attempt to resolve it. Inform the user and direct them to Studio.
+- Collection object-map format with sorted keys means ~0.3% chance of conflict for two new entries in a 350-entry collection.
+
+---
+
+## 5. Workflow States
+
+Content entries move through these states:
+
+```
+draft --> in_review --> published
+              |
+              v
+          rejected (with feedback)
+
+published --> archived
+```
+
+### 5.1 State Definitions
+
+| State | Git State | Trigger |
+|-------|-----------|---------|
+| `draft` | Branch exists, not yet reviewed/merged | Content created or updated |
+| `in_review` | PR/branch open, labeled `contentrain-content` | `contentrain_submit` in review mode |
+| `published` | Content is on `contentrain` branch and synced to baseBranch | Auto-merge, or PR merged after review |
+| `rejected` | PR closed without merge | Studio reviewer rejects changes |
+| `archived` | Metadata-only state | Manual action -- content hidden but retained |
+
+### 5.2 State Rules
+
+- **State is tracked in `.contentrain/meta/`, NOT in content files.** Agents never read or write state directly.
+- **auto-merge mode:** `draft` --> `published` (no `in_review` step).
+- **review mode:** `draft` --> `in_review` --> `published` or `rejected`.
+- **Git is the source of truth.** States are derived from Git state (branch existence, merge status, PR status).
+- Rejected content includes reviewer feedback. The agent can address feedback and resubmit.
+
+---
+
+## 6. Validation Rules
+
+### 6.1 When to Validate
+
+- ALWAYS call `contentrain_validate` before `contentrain_submit`.
+- `contentrain_submit` will fail if validation errors exist.
+- Run validation after completing all changes in a batch, not after every individual save.
+
+### 6.2 What Validation Checks
+
+| Check | Severity | Description |
+|-------|----------|-------------|
+| Schema compliance | Error | Field values match their type definitions |
+| Required fields | Error | All `required: true` fields have values |
+| Unique constraints | Error | `unique: true` fields have no duplicates within the model |
+| Locale completeness | Error/Warning | All supported locales have corresponding files and entries |
+| Referential integrity | Error | Relation targets (IDs/slugs) exist in the target model |
+| Canonical format | Warning | Files follow canonical serialization rules |
+| Vocabulary usage | Warning | Content uses vocabulary terms when available |
+
+### 6.3 Handling Validation Results
+
+- **Errors:** MUST be fixed before submitting. Fix the content and re-validate.
+- **Warnings:** Acceptable but should be addressed when possible. Acknowledge them before submitting.
+- If validation returns zero errors, proceed with `contentrain_submit`.
+
+---
+
+## 7. Submit Behavior
+
+### 7.1 auto-merge Mode
+
+```
+contentrain_submit
+  --> Merge feature branch into contentrain
+  --> Advance baseBranch via update-ref (fast-forward)
+  --> Selectively sync .contentrain/ files to developer's working tree
+  --> Clean up worktree
+  --> Status: published
+```
+
+### 7.2 review Mode
+
+```
+contentrain_submit
+  --> Push feature branch to remote
+  --> Clean up worktree
+  --> Status: in_review
+  --> Studio notifies reviewers
+```
+
+### 7.3 Submit Rules
+
+- Submit operates on the current pending branch. There must be pending changes.
+- If no changes are pending, submit is a no-op.
+- After submit, the agent can continue with other operations (new branch will be created for new changes).
+- Normalize operations ALWAYS submit in review mode, regardless of project workflow setting.
+
+### 7.4 Branch Merge Mechanisms
+
+Review-mode branches can be merged three ways:
+
+**1. CLI Serve UI (Browser — recommended for normalize)**
+
+```bash
+contentrain serve
+```
+
+Navigate to http://localhost:3333/branches → select branch → click Merge.
+
+**2. MCP Tool (Programmatic — for agent-driven workflows)**
+
+```
+contentrain_merge(branch: "cr/normalize/extract/...", confirm: true)
+```
+
+Local git merge: feature → contentrain → update-ref → selective sync.
+No external platform required. Agent can continue immediately.
+
+**3. Git Platform (GitHub/GitLab — for team governance)**
+
+```
+contentrain_submit  # pushes to remote
+```
+
+Then create PR on platform → review → merge.
+
+**Agent Decision Guide:**
+
+| Workflow | Recommended Merge Method |
+|----------|--------------------------|
+| Normalize (extract/reuse) | CLI serve UI (visual review of content) |
+| Content CRUD | `contentrain_merge` (programmatic, fast) |
+| Team with code review | Git platform PR |
+
+---
+
+## 8. Metadata Structure
+
+Metadata files track governance information. They are system-managed -- agents NEVER write to them.
+
+### File Paths
+
+| Kind | Path |
+|------|------|
+| Singleton / Dictionary | `.contentrain/meta/{modelId}/{locale}.json` |
+| Collection | `.contentrain/meta/{modelId}/{locale}.json` (object-map: `{ entryId: meta }`) |
+| Document | `.contentrain/meta/{modelId}/{slug}/{locale}.json` |
+
+### Metadata Fields
+
+```json
+{
+  "status": "published",
+  "source": "agent",
+  "updated_by": "claude",
+  "approved_by": "ahmet@contentrain.io",
+  "version": "1"
+}
+```
+
+| Field | Values | Description |
+|-------|--------|-------------|
+| `status` | `draft`, `in_review`, `published`, `rejected`, `archived` | Current workflow state |
+| `source` | `agent`, `human`, `import` | How the content was created |
+| `updated_by` | string | Agent name or user email |
+| `approved_by` | string or null | Who approved (review mode only) |
+| `version` | string | Content version identifier |