export default { "body": "# Core Concepts\n\n## The Big Idea\n\n**Governance, not generation.**\n\nContentrain is not an AI content generator — there are dozens of those. Contentrain is the infrastructure that governs what happens _after_ AI generates content: validation, structure, review, approval, and delivery.\n\nMost content tools ask you to learn their system — their dashboard, their API, their markup syntax. Contentrain inverts this: **your AI agent already understands your codebase**, so let it manage your content. Contentrain provides the deterministic infrastructure (MCP tools, validation, Git transactions) while the agent provides the intelligence (what to extract, how to structure, where to replace).\n\n> Agent generates. Human approves. System standardizes.\n\nThe result is a content pipeline with full auditability:\n\n```\nAgent generates → MCP validates → Human reviews → Git commits → Content delivered\n```\n\nEvery step is a git diff. Nothing reaches production without your approval.\n\n## The Agent-Driven Content Model\n\nContentrain AI inverts the traditional CMS workflow:\n\n| Traditional CMS | Contentrain AI |\n|---|---|\n| Human opens dashboard | Human talks to AI agent |\n| Human creates schema manually | Agent creates models via MCP |\n| Human types content in forms | Agent writes content to Git |\n| Content stored in database | Content stored as files in `.contentrain/` |\n| API calls to read content | Plain JSON files — read from any language, optional typed SDK |\n| Deploys need API availability | Static files — works offline, zero runtime deps, any platform |\n\n## Three Layers\n\n### 1. MCP (Infrastructure)\n\n24 tools (19 core + 5 media) that AI agents call to manage content:\n\n- **Read:** `contentrain_status`, `contentrain_describe`, `contentrain_describe_format`, `contentrain_doctor`, `contentrain_content_list`\n- **Project setup:** `contentrain_init`, `contentrain_scaffold`\n- **Content and schema writes:** `contentrain_model_save`, `contentrain_model_delete`, `contentrain_content_save`, `contentrain_content_delete`\n- **Normalize:** `contentrain_scan`, `contentrain_apply`\n- **Workflow and operations:** `contentrain_validate`, `contentrain_submit`, `contentrain_merge`, `contentrain_bulk`\n\nMCP is **deterministic infrastructure** — it doesn't make content decisions. The agent decides what to create; MCP executes it.\n\nMCP runs over two transports (stdio for IDE agents, HTTP for Studio / CI / remote drivers) and three provider backends: **Local** (simple-git + worktree), **GitHub** (Octokit over the Git Data API), and **GitLab** (gitbeaker over the REST API). The tool surface is identical across all three; some tools require `LocalProvider` — see [Providers and transports](/guides/providers) for the capability matrix.\n\n### 2. Agent (Intelligence)\n\nThe AI agent (Claude, GPT, etc.) is the intelligence layer:\n\n- Understands your codebase structure\n- Evaluates which strings are user-facing content\n- Chooses the right model kind for each content group\n- Determines framework-specific replacement patterns\n- Manages the review workflow with the developer\n\n### 3. Serve UI (Review Surface)\n\nA local web UI for developers to:\n\n- **Monitor:** browse models, content, validation, history\n- **Approve:** review and merge agent-created branches\n- **Prompt:** copy pre-built prompts to paste into their agent\n\nThe UI never triggers mutations directly — all actions go through the agent.\n\n## Model Kinds\n\nContentrain supports four content model kinds:\n\n### Collection\n\nMultiple entries with the same field schema. Each entry has an auto-generated ID.\n\n```json\n// .contentrain/content/marketing/faq/en.json\n{\n \"abc123\": { \"question\": \"What is Contentrain?\", \"answer\": \"...\" },\n \"def456\": { \"question\": \"How does it work?\", \"answer\": \"...\" }\n}\n```\n\n**Use for:** blog posts, FAQ items, team members, testimonials, pricing plans.\n\n### Singleton\n\nA single entry per locale with structured fields.\n\n```json\n// .contentrain/content/marketing/hero/en.json\n{ \"title\": \"Build Faster\", \"subtitle\": \"With AI\", \"cta_text\": \"Get Started\" }\n```\n\n**Use for:** hero sections, site settings, navigation config, footer content.\n\n### Dictionary\n\nFlat key-value pairs — all values are strings. No field schema.\n\n```json\n// .contentrain/content/system/ui-labels/en.json\n{ \"nav.home\": \"Home\", \"nav.about\": \"About\", \"error.required\": \"This field is required\" }\n```\n\n**Use for:** UI labels, button text, error messages, validation messages, i18n strings.\n\n::: tip Parameterized Templates\nDictionary values support `{placeholder}` syntax:\n```ts\ndictionary('ui-labels').locale('en').get('welcome', { name: 'Ahmet' })\n// \"Hello, {name}!\" → \"Hello, Ahmet!\"\n```\n:::\n\n### Document\n\nMarkdown files with frontmatter metadata.\n\n```markdown\n---\ntitle: Getting Started\ncategory: guides\n---\n\n# Getting Started\n\nThis is the markdown body content...\n```\n\n**Use for:** blog articles, documentation pages, changelogs, legal pages.\n\n## Domains\n\nModels are organized by domain — a logical grouping:\n\n```\n.contentrain/content/\n marketing/ ← hero, pricing, testimonials\n blog/ ← blog-post, author\n system/ ← navigation, ui-labels\n```\n\nDomains are configured in `.contentrain/config.json`.\n\n## Locales & i18n\n\nEvery model can be i18n-enabled (`i18n: true`). Content is stored per locale:\n\n```\n.contentrain/content/marketing/hero/\n en.json ← English\n tr.json ← Turkish\n```\n\nAny platform can read the locale files directly. The TypeScript SDK adds convenience:\n\n```ts\n// Option 1: Read JSON directly (any language)\n// Just read .contentrain/content/marketing/hero/tr.json\n\n// Option 2: TypeScript SDK (optional)\nsingleton('hero').locale('tr').get() // typed, with query API\n```\n\n## Git Workflow\n\nEvery write operation creates a Git commit on a namespaced branch:\n\n```\ncr/model/hero-section ← model changes\ncr/content/blog-post ← content changes\ncr/normalize/extract/... ← normalize extraction\ncr/normalize/reuse/... ← source patching\n```\n\nBranches are auto-merged or held for review depending on your workflow config. When a review branch is merged or rejected, its remote copy is deleted too, so merged branches don't linger as phantom pending reviews — run `contentrain prune` to drain any existing backlog, or set `remoteBranchCleanup: false` to opt out.\n\n## How It Compares\n\n| | Contentrain AI | Headless CMS (Sanity, Strapi) | Git CMS (Tina, Decap) |\n|---|---|---|---|\n| **Content source** | Your codebase or agent-created from scratch | External dashboard | Markdown/JSON in repo |\n| **AI integration** | Native (MCP tools) | Manual API calls | None |\n| **Extract from code** | Yes (normalize flow) | No | No |\n| **Vendor lock-in** | None (plain files + Git) | API dependency | Editor dependency |\n| **Type safety** | Generated SDK (optional) | Manual types | Manual types |\n| **i18n** | Built-in (per-locale files) | Plugin/addon | Plugin/addon |\n| **Review workflow** | Git branches + local UI | Dashboard roles | PR-based |\n| **Runtime dependency** | Zero (static files) | API availability | Build-time |\n\n::: tip No Lock-In\nContentrain stores everything as plain JSON and Markdown files in your Git repo. If you stop using Contentrain tomorrow, your content is still there — readable, portable, yours.\n:::\n\n## Beyond Web: Content CDN\n\nWeb projects deploy content with `git push` — no extra infrastructure needed. But non-web platforms (iOS, Android, React Native, Flutter, desktop apps, game engines, IoT) can't read from a git repo at runtime.\n\nFor these use cases, Contentrain publishes merged content to a CDN (`cdn.contentrain.io`), delivering the same structured JSON your SDK queries — just over HTTP instead of the filesystem.\n\n```\nGit repo → merge → CDN publish → iOS/Android/Flutter fetch → typed response\n```\n\nThis means one content source powers your website, mobile app, and any other platform — all governed by the same review workflow.\n\n## Contentrain Studio\n\n[Contentrain Studio](/studio) is the open-core team operations panel for Git-native structured content. Teams can self-host the AGPL core or use a managed Pro/Enterprise offering on top of the same model.\n\nThe local open-source stack gives you:\n\n- MCP tools\n- CLI workflows\n- local review UI\n- generated SDK\n- rules and skills\n\nStudio adds the multi-user operating layer on top of that:\n\n- **Workspace and project management** — organize repos, teams, and environments\n- **Chat-first operations** — run bounded content workflows through a web app\n- **Permissioned collaboration** — owners, admins, editors, reviewers, and viewers\n- **Branch and diff review** — inspect, merge, reject, and track content changes\n- **Media and submissions** — manage assets and inbound content workflows\n- **CDN delivery** — publish merged content to apps that cannot read from Git at runtime\n\nThe local tools and Studio share the same Git-native content model. The difference is not the content format — it is the operating surface.", "category": "getting-started", "description": "Understand the architecture: models, content kinds, domains, locales, and the agent-driven workflow", "order": 2, "slug": "concepts", "title": "Core Concepts" }