@contentrain/rules 0.3.0 → 0.3.2

package/README.md

@@ -1,10 +1,17 @@
 # `@contentrain/rules`
 
 [![npm version](https://img.shields.io/npm/v/%40contentrain%2Frules?label=%40contentrain%2Frules)](https://www.npmjs.com/package/@contentrain/rules)
+[![Agent Skills](https://img.shields.io/badge/Agent_Skills-compatible-8B5CF6)](https://agentskills.io)
 [![GitHub source](https://img.shields.io/badge/source-Contentrain%2Fai-181717?logo=github)](https://github.com/Contentrain/ai/tree/main/packages/rules)
+[![Docs](https://img.shields.io/badge/docs-ai.contentrain.io-0f172a)](https://ai.contentrain.io/packages/rules)
 
 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)
+
 This package is the policy layer of the Contentrain ecosystem. It defines how agents should behave when they work with:
 
 - Contentrain MCP tools
@@ -89,6 +96,8 @@ Rule of thumb:
 - `rules` = essential guardrails (always loaded, ~86 lines)
 - `skills` = detailed procedures and reference docs (on-demand)
 
+See [`AGENTS.md`](../../AGENTS.md) at the repo root for agent-level project guidance.
+
 ## Build
 
 From the monorepo root:

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/essential/contentrain-essentials.md

@@ -7,7 +7,7 @@ This project uses Contentrain for AI-driven content management. These rules are
 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 (worktree/branch/commit/merge), project scanning
+- **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
@@ -52,6 +52,7 @@ MCP is **deterministic infrastructure**. The agent (you) is the **intelligence l
 | `contentrain_apply` | Apply normalize (extract/reuse) |
 | `contentrain_validate` | Validate content against schemas |
 | `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) |
 
 ## Mandatory Protocols
@@ -65,13 +66,45 @@ MCP is **deterministic infrastructure**. The agent (you) is the **intelligence l
 
 ## Git Workflow
 
-- Every write operation creates a worktree + branch automatically
-- **auto-merge** mode: branch merges to main after commit
-- **review** mode: branch pushed to remote for team review
-- Branch naming: `contentrain/{operation}/{model}/{locale}/{timestamp}`
-- Never create branches manually, never commit directly to main
+- 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
 
+## CLI Serve — Review & Approval
+
+Normalize and review workflows often need browser-based approval:
+
+```bash
+contentrain serve  # starts http://localhost:3333
+```
+
+Key pages: `/normalize` (extraction approval), `/branches` (merge/delete), `/validate` (error review), `/content` (browse).
+
+Agent should start or ensure serve is running when:
+- Normalize extraction needs user approval
+- Multiple branches await review
+- Validation errors need visual inspection
+
+Branch merge options: CLI serve UI (localhost:3333/branches), `contentrain_merge` MCP tool, or git platform PR.
+
+## SDK Regeneration
+
+After model/content changes or normalize reuse, run:
+
+```bash
+npx contentrain generate
+```
+
+This regenerates `.contentrain/client/` — required for `#contentrain` imports to work.
+
 ## Localization
 
 - All supported locales must have entries for every content item

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/rules",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "license": "MIT",
   "description": "AI agent rules for Contentrain — quality standards, architecture conventions, IDE integration",
   "type": "module",
@@ -9,7 +9,7 @@
     "url": "git+https://github.com/Contentrain/ai.git",
     "directory": "packages/rules"
   },
-  "homepage": "https://github.com/Contentrain/ai/tree/main/packages/rules",
+  "homepage": "https://ai.contentrain.io/packages/rules",
   "bugs": {
     "url": "https://github.com/Contentrain/ai/issues"
   },
@@ -17,11 +17,15 @@
     "contentrain",
     "ai",
     "rules",
+    "agent-skills",
+    "agent-rules",
     "mcp",
     "prompt-engineering",
     "claude-code",
     "cursor",
-    "windsurf"
+    "windsurf",
+    "copilot",
+    "codex"
   ],
   "sideEffects": false,
   "publishConfig": {

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.