fix(cli): restore Serve UI labels, unify sidebar i18n, correct capabilities transport

.changeset/serve-ui-july-alignment.md

@@ -0,0 +1,12 @@
+---
+"contentrain": patch
+---
+
+fix(cli): restore blank Serve UI labels and correct the capabilities transport badge
+
+The Serve UI's Doctor and Format sidebar labels rendered blank. Two causes, both fixed:
+
+- **Stale generated client.** The committed `#contentrain` client the UI bundles was last generated in March and had drifted 40 keys behind the source `serve-ui-texts` dictionary — including the two nav labels, the entire Doctor page copy (21 keys), the branch-detail merge-preview strings (7), and the Format page (4). Regenerating brings the client current (and also syncs the docs/marketing content the same client mirrors via `content_path`).
+- **Half-migrated sidebar.** `PrimarySidebar` used a `primary-nav.*` namespace for only Doctor/Format while the other six items were hardcoded. All eight nav items now use the single, complete `primary-sidebar.*` namespace, matching `MobileNav`'s dictionary-driven approach.
+
+Also: `/api/capabilities` reported `transport: "stdio"` in Web-UI mode, where the dashboard is actually reached over HTTP (the MCP engine is embedded in-process). The badge now reads `local · http`. `stdio` remains correct only for `serve --stdio`, which does not serve this UI.

.contentrain/client/data/docs-guide--concepts.mjs

@@ -0,0 +1,8 @@
+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"
+}

.contentrain/client/data/docs-guide--demo.mjs

@@ -0,0 +1,8 @@
+export default {
+  "body": "# 2-Minute Demo\n\nThis is the **one demo story** that explains Contentrain fastest:\n\n> You have hardcoded UI text in a real app.  \n> Your agent extracts it into a governed content layer.  \n> Contentrain keeps the process reviewable, typed, and Git-native.\n\n## Before\n\nYour component ships with inline text:\n\n```tsx\nexport default function Hero() {\n  return (\n    <section>\n      <h1>Build faster with AI-powered content</h1>\n      <p>Ship your next project in days, not weeks</p>\n      <button>Get started free</button>\n    </section>\n  )\n}\n```\n\nThis works until:\n\n- marketing wants copy changes\n- you need a second language\n- mobile needs the same content\n- the agent starts editing strings directly in source files\n\n## Step 1. Initialize\n\n```bash\nnpx contentrain init\n```\n\nNow you have a governed `.contentrain/` workspace in your repo.\n\n## Step 2. Connect your agent\n\nRun the local MCP entrypoint:\n\n```bash\nnpx contentrain serve --stdio\n```\n\nThen ask your agent:\n\n> Scan this project and extract the hardcoded strings in the hero section.\n\n## Step 3. Extract\n\nThe agent uses `contentrain_scan` to find strings and `contentrain_apply(mode: \"extract\")` to move them into content files.\n\nGenerated content:\n\n```json\n{\n  \"title\": \"Build faster with AI-powered content\",\n  \"subtitle\": \"Ship your next project in days, not weeks\",\n  \"cta\": \"Get started free\"\n}\n```\n\nExample location:\n\n```text\n.contentrain/content/marketing/hero-section/en.json\n```\n\nAt this stage, **source files are untouched**. You can already review, translate, and validate the extracted content.\n\n## Step 4. Reuse\n\nThen ask your agent:\n\n> Replace the hardcoded hero strings with content references.\n\nThe agent proposes a dry-run patch, then `contentrain_apply(mode: \"reuse\")` updates the source file on a review branch.\n\n## After\n\n```tsx\nimport { singleton } from '#contentrain'\n\nexport default function Hero() {\n  const hero = singleton('hero-section').locale('en').get()\n\n  return (\n    <section>\n      <h1>{hero.title}</h1>\n      <p>{hero.subtitle}</p>\n      <button>{hero.cta}</button>\n    </section>\n  )\n}\n```\n\n## Why this demo matters\n\nThis one flow shows Contentrain's full value:\n\n- **AI agent does the extraction work**\n- **Contentrain enforces schema and Git review**\n- **Your content becomes reusable and translatable**\n- **Your app consumes plain JSON or the typed SDK**\n\n## What to do next\n\n- Follow the full [Getting Started](/getting-started) guide\n- Read the full [Normalize Flow](/guides/normalize)\n- Use [Framework Integration](/guides/frameworks) for your stack\n\n## Ready for Team Collaboration?\n\nThis demo shows extraction and reuse locally. When your team needs role-based review, web-based collaboration, or CDN delivery for mobile and non-web platforms, connect your project to [Contentrain Studio](/studio):\n\n```bash\ncontentrain studio login\ncontentrain studio connect\n```\n\nStudio uses the same `.contentrain/` content model — no changes needed.",
+  "category": "getting-started",
+  "description": "See Contentrain's core value in one flow: extract hardcoded UI text, create structured content, and patch source files through review",
+  "order": 2,
+  "slug": "demo",
+  "title": "2-Minute Demo"
+}

.contentrain/client/data/docs-guide--ecosystem.mjs

@@ -0,0 +1,8 @@
+export default {
+  "body": "# Ecosystem Map\n\nContentrain has two product surfaces operating on the same `.contentrain/` contract:\n\n- **Contentrain AI** — the open-source, local-first operating core: MCP, CLI, SDK, rules, and skills\n- **Contentrain Studio** — the open-core team web surface: chat, review, media, forms, APIs, and CDN delivery\n\nThe format does not change. The operating surface does.\n\n## The Split\n\nUse **Contentrain AI** when you need:\n\n- local-first agent workflows\n- hardcoded-string rescue through normalize\n- direct Git-native content operations from an IDE or terminal\n- package-level adoption through `@contentrain/mcp`, `contentrain`, `@contentrain/query`, `@contentrain/rules`, and `@contentrain/skills`\n\nUse **Contentrain Studio** when you need:\n\n- authenticated team workflows in a web app\n- role-aware review and approval\n- project/workspace management\n- media, forms, conversation APIs, and CDN delivery\n- self-hosted or managed team collaboration on top of the same content model\n\n## Package Bridges\n\n| AI surface | Primary job | Studio bridge | Go deeper |\n|---|---|---|---|\n| `@contentrain/mcp` | Deterministic local content operations and normalize | Studio applies the same `.contentrain/` contract through governed web workflows and review surfaces | [MCP Tools](/packages/mcp), [Studio AI Chat](https://docs.contentrain.io/guide/ai-chat) |\n| `contentrain` CLI | Bootstrap, validate, diff, generate, serve, and local review | Studio takes over when teams need authenticated review, roles, and project management | [CLI](/packages/cli), [Studio Quickstart](https://docs.contentrain.io/guide/quickstart) |\n| `@contentrain/query` | Local typed consumption and CDN client transport | Studio adds remote delivery, API keys, and CDN publishing on top of the same content | [Query SDK](/packages/sdk), [Studio CDN](https://docs.contentrain.io/guide/cdn) |\n| `@contentrain/rules` | Quality standard and schema/content guardrails | Studio should match the same quality standard in chat, review, and content validation | [Rules & Skills](/packages/rules), [Studio Architecture](https://docs.contentrain.io/developer/architecture) |\n| `@contentrain/skills` | Agent playbooks, workflow hints, and normalize/review procedures | Studio mirrors these workflows in chat-led operations, onboarding, and promotion moments | [Rules & Skills](/packages/rules), [Studio AI Chat](https://docs.contentrain.io/guide/ai-chat) |\n\n## MCP Distribution Surfaces\n\n| Surface | What users see | Best fit |\n|---|---|---|\n| MCP Registry | `io.github.Contentrain/contentrain` | Discover and install the local `@contentrain/mcp` server from MCP-compatible clients |\n| OpenAI Codex | `codex mcp add`, `.codex/config.toml`, and future plugin packaging | Developers who want Contentrain tools inside Codex CLI, desktop, or IDE workflows |\n| Claude Desktop | `claude_desktop_config.json` | Local desktop users who want a checkout-scoped Contentrain server |\n| Claude Code | `claude mcp add`, `.mcp.json`, and plugin marketplaces | Coding-agent workflows with project-scoped MCP approval and skills |\n| Studio MCP Cloud | Hosted Streamable HTTP endpoint + API key | Teams that want external agents to operate a Studio project without sharing a local checkout |\n\n## Product Philosophy\n\n- **Governance, not generation** — Contentrain standardizes, validates, and reviews content. Your model provider still does the generation.\n- **Git-native, not database-first** — content stays in Git; branches, commits, diffs, and merge rules stay visible.\n- **Packages drive adoption** — the AI repo is the easiest entry point for developers and agents.\n- **Studio deepens operations** — once content exists, teams need permissions, review, shareable workflows, and delivery surfaces.\n\n## Marketing and Distribution Logic\n\nThe growth loop is intentional:\n\n1. **Normalize is the wedge** — most developers discover Contentrain by rescuing hardcoded strings in an existing codebase.\n2. **Packages create trust** — MCP, CLI, rules, skills, and query are adoptable independently.\n3. **Studio is the expansion surface** — teams move into Studio when review, collaboration, and delivery become operational needs.\n4. **CDN and team workflows monetize naturally** — after the content layer already exists.\n\nThat means AI docs should mention Studio at natural escalation points:\n\n- after `contentrain init`\n- after successful normalize extraction\n- when review branches accumulate\n- when multiple collaborators or locales appear\n- when content must ship beyond web runtime\n\nStudio docs should point back to AI packages whenever they explain:\n\n- where the `.contentrain/` contract comes from\n- how normalize starts the journey\n- how rules and skills shape agent behavior\n- how `@contentrain/query` relates to CDN delivery and consumer apps\n\n## Docs Map\n\n| Need | Canonical surface |\n|---|---|\n| Package contracts and local workflows | `ai.contentrain.io` |\n| Team workflows and product docs | `docs.contentrain.io` |\n| Studio deployment and self-hosting | `docs.contentrain.io/developer/self-hosting` |\n\n## Short Definition\n\nContentrain AI is the package surface that gets structured content into Git. Contentrain Studio is the team surface that helps people review, operate, and deliver that same governed content.",
+  "category": "getting-started",
+  "description": "How Contentrain AI packages and Contentrain Studio fit together across discovery, governance, collaboration, and delivery.",
+  "order": 2,
+  "slug": "ecosystem",
+  "title": "Ecosystem Map"
+}