# AGENTS.md — Contentrain AI

> Git-based, AI-first content governance infrastructure.
> Agent extracts or updates content → Contentrain standardizes → Human reviews → Any platform consumes.

## What this repo is

MIT-licensed monorepo for Contentrain's open-source packages: MCP tools, CLI, TypeScript types, AI rules, universal query SDK, and agent skills.

## Agent Skills

This repo ships 15 Agent Skills following the [Agent Skills standard](https://agentskills.io). Install them with:

```bash
npx skills add contentrain/contentrain-ai --skill='*'
```

Or install a specific skill:

```bash
npx skills add contentrain/contentrain-ai --skill='contentrain-normalize'
```

Skills are located at `packages/skills/skills/*/SKILL.md`:

| Skill | When to use |
|-------|------------|
| `contentrain` | Working with .contentrain/ directory, MCP tools, content formats |
| `contentrain-normalize` | Extracting hardcoded strings, patching source files with content refs |
| `contentrain-quality` | Content quality checks, SEO, accessibility, media rules |
| `contentrain-sdk` | Using @contentrain/query, #contentrain imports, QueryBuilder |
| `contentrain-content` | Creating/updating content entries for existing models |
| `contentrain-model` | Designing and saving model definitions |
| `contentrain-init` | Initializing a new Contentrain project |
| `contentrain-bulk` | Batch operations on content entries |
| `contentrain-validate-fix` | Validating content and auto-fixing structural issues |
| `contentrain-review` | Reviewing content changes before publishing |
| `contentrain-translate` | Translating content across supported locales |
| `contentrain-generate` | Generating the typed SDK client from models |
| `contentrain-serve` | Starting the local review UI |
| `contentrain-diff` | Viewing content diffs between branches |
| `contentrain-doctor` | Diagnosing project health issues |

## Essential rules (always-loaded)

Load `packages/rules/essential/contentrain-essentials.md` (~120 lines) for compact guardrails covering:

- Architecture (MCP = deterministic infra, Agent = intelligence)
- Four model kinds (singleton, collection, document, dictionary)
- Content format rules (JSON only, canonical serialization)
- 19 MCP tools with mandatory calling protocols
- Git workflow (dedicated contentrain branch, worktree isolation)
- Security boundaries

## Packages

| Directory | npm | What it does |
|-----------|-----|-------------|
| `packages/mcp` | `@contentrain/mcp` | 19 MCP tools — content operations engine |
| `packages/cli` | `contentrain` | CLI + Serve UI + MCP stdio entrypoint |
| `packages/sdk/js` | `@contentrain/query` | Generated TypeScript query SDK |
| `packages/types` | `@contentrain/types` | Shared type definitions |
| `packages/rules` | `@contentrain/rules` | Agent quality rules for IDE integration |
| `packages/skills` | `@contentrain/skills` | Workflow procedures + framework guides |

## Key constraints for agents

1. **MCP does NOT make content decisions** — it is deterministic infrastructure. The agent decides what is content, how to group it, what quality standards apply.
2. **Always `contentrain_status` first** — call it before any operation on an existing project.
3. **Always `contentrain_describe_format` before creating models** — understand storage format before writing.
4. **Always `dry_run: true` first** — preview before applying normalize or bulk operations.
5. **Never write to `.contentrain/` directly** — always use MCP tools.
6. **Never edit `.contentrain/client/`** — it is auto-generated by `npx contentrain generate`.
7. **Normalize uses review workflow** — never auto-merge normalize branches.

## Tech stack

- Node.js 22 LTS, pnpm 9+, tsdown, oxlint, Vitest, lefthook
- MCP validation: Zod ^3.24
- JSON only — no YAML (except markdown frontmatter)

## Framework guides

Framework-specific integration guides are at `packages/skills/frameworks/`:

`nuxt.md` · `next.md` · `astro.md` · `sveltekit.md` · `vue.md` · `react.md` · `expo.md` · `react-native.md` · `node.md`

## Getting started

```bash
npx contentrain init        # create .contentrain/ workspace
npx contentrain serve       # open the local review UI
npx contentrain generate    # generate typed SDK client
```

## Documentation

- [Full docs](https://ai.contentrain.io)
- [2-minute demo](https://ai.contentrain.io/demo)
- [Normalize guide](https://ai.contentrain.io/guides/normalize)
- [Package READMEs](packages/) for detailed API reference