Contentrain · ABB65 · Apr 14, 2026 · Apr 14, 2026 · Apr 14, 2026 · Apr 14, 2026
diff --git a/.changeset/studio-tips.md b/.changeset/studio-tips.md
@@ -0,0 +1,20 @@
+---
+"contentrain": patch
+"@contentrain/mcp": minor
+"@contentrain/skills": minor
+"@contentrain/rules": patch
+"@contentrain/query": patch
+"@contentrain/types": patch
+---
+
+feat(cli): Add contextual Studio tips to CLI commands (init, generate, diff, status) with branding and clickable links. New setup and skills commands with IDE integration utilities.
+
+feat(mcp): Redesign scan pipeline with confidence scoring, deduplication, and pre-filter improvements. Add tool annotations, git transaction manager, and MCP best practices from Playwright/Engram/DBHub.
+
+feat(skills): Add Agent Skills ecosystem integration across all 15 skills with workflow handoff protocols, cross-references, and normalize guardrails.
+
+feat(rules): Add essential guardrails and shared normalize/workflow rules.
+
+feat(sdk): Add contentrain-query skill with bundler config references.
+
+fix(types): Expand shared type definitions for new scan and workflow features.
diff --git a/.gitignore b/.gitignore
@@ -46,6 +46,6 @@ docs/.vitepress/dist/
 
 .tmp
 .mcpregistry_*
-
+tmp/
 # Symlinked projects
 /studio
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,125 +1,101 @@
-# AGENTS.md — contentrain-ai
+# AGENTS.md — Contentrain AI
 
-## Project Overview
+> Git-based, AI-first content governance infrastructure.
+> Agent extracts or updates content → Contentrain standardizes → Human reviews → Any platform consumes.
 
-MIT-licensed monorepo for Contentrain's open-source packages: MCP tools, CLI, TypeScript types, AI rules, and universal query SDK.
+## What this repo is
 
-**Vision:** "AI-generated content governance infrastructure — Agent üretir, insan onaylar, sistem standardize eder."
+MIT-licensed monorepo for Contentrain's open-source packages: MCP tools, CLI, TypeScript types, AI rules, universal query SDK, and agent skills.
 
-## Monorepo Structure
+## Agent Skills
 
-```
-contentrain-ai/
-├── packages/
-│   ├── mcp/          — 15 MCP tools (simple-git + zod + MCP SDK)
-│   ├── cli/          — citty + tsdown (init/serve/validate/normalize/connect)
-│   ├── types/        — Shared TypeScript types (@contentrain/types)
-│   ├── rules/        — AI agent quality rules & conventions
-│   ├── skills/       — AI agent workflow procedures & framework guides
-│   └── sdk/
-│       └── js/       — Universal query SDK (@contentrain/query)
-├── docs/
-│   └──              — Reserved for the public VitePress docs site
-```
+This repo ships 15 Agent Skills following the [Agent Skills standard](https://agentskills.io). Install them with:
 
-## Documentation Sources
-
-The old `docs/internal/*` spec set is no longer the source of truth.
-
-Use these references instead:
-- root [README.md](README.md) for monorepo overview
-- package `README.md` files for public package contracts
-- [RELEASING.md](RELEASING.md) for versioning and publish flow
-- `packages/rules/` and `packages/skills/` for agent behavior guidance
-
-## Tech Stack
-
-- **Runtime:** Node.js 22 LTS
-- **Package manager:** pnpm 9+
-- **Build:** tsdown (pnpm workspace scripts for orchestration)
-- **Lint:** oxlint (NOT ESLint)
-- **Format:** oxfmt
-- **Test:** Vitest
-- **Git hooks:** lefthook
-- **MCP validation:** Zod ^3.24 (MCP SDK requirement)
-
-## Key Decisions
-
-- **JSON only** — no YAML
-- **Git mandatory** — `contentrain init` auto `git init`
-- **Octokit YOK in MCP** — MCP = local-first, platform-agnostic. GitHub API = Studio/CLI only
-- **Every write uses worktree + dedicated contentrain branch + update-ref** — model_save and content_save alike
-- **Collection storage = object-map** — `{ entryId: { fields } }`, sorted by ID
-- **Canonical serialization** — deterministic JSON output, sorted keys, 2-space indent, trailing newline
-- **Dedicated contentrain branch** — content state SSOT, created at init, auto-synced with baseBranch via update-ref. Developer's working tree is never mutated during MCP operations
-- **context.json** — committed with content changes (not separately), Studio/IDE reads
-- **Workflow config** — `"auto-merge"` or `"review"` in config.json
-- **Agent-MCP split** — MCP = deterministic infra, Agent = intelligence. MCP does NOT make content decisions
-- **Normalize two phases** — Phase 1: Extraction (content-only), Phase 2: Reuse (source patching). Separate branches, separate reviews
-- **Graph-based scan** — scan tool builds import/component graph for project intelligence, reducing token usage dramatically
-- **Top 5+ stack support** — Not limited to Vue/Nuxt. Agent handles stack-specific logic, MCP stays framework-agnostic
-- **Replacement by agent** — In reuse phase, the agent determines replacement expressions (e.g., `{t('key')}` vs `{{ $t('key') }}`), not MCP
-- **SDK = generated client** — Prisma pattern: `contentrain generate` → `.contentrain/client/` with full types. `#contentrain` subpath import (Node.js native). No node_modules generation. Base SDK is framework-agnostic MIT, community builds framework SDKs on top
-
-## npm Packages
-
-| Package | Name | Description |
-|---|---|---|
-| packages/mcp | @contentrain/mcp | 15 MCP tools |
-| packages/cli | contentrain | CLI (npx contentrain) |
-| packages/types | @contentrain/types | Shared TypeScript types |
-| packages/rules | @contentrain/rules | AI agent quality rules & conventions |
-| packages/skills | @contentrain/skills | AI agent workflow procedures & guides |
-| packages/sdk/js | @contentrain/query | Universal query SDK (generated client) |
-
-## Mandatory Quality Gates
-
-**Every agent MUST pass ALL gates before considering work complete.** No exceptions.
-
-### 1. oxlint (zero errors, zero warnings)
 ```bash
-npx oxlint packages/<package>/src/ packages/<package>/tests/
+npx skills add contentrain/contentrain-ai --skill='*'
 ```
-- `sort()` → `toSorted()` (immutable)
-- `no-await-in-loop` → use `Promise.all()` for parallel I/O
-- No unused imports/variables
-- Fix ALL warnings, not just errors
 
-### 2. TypeScript (zero errors)
-```bash
-cd packages/<package> && npx tsc --noEmit
-```
-- Strict mode — no `any` escapes without justification
-- All types must compile cleanly
+Or install a specific skill:
 
-### 3. Tests (all pass, meaningful coverage)
 ```bash
-cd packages/<package> && npx vitest run
+npx skills add contentrain/contentrain-ai --skill='contentrain-normalize'
 ```
-- Every public module MUST have tests
-- Runtime classes: test all methods + edge cases (empty data, unknown locale, etc.)
-- Generator modules: test output correctness + canonical format
-- Integration test: end-to-end flow verification
-- Test assertions must be specific (not just `.toBeDefined()`)
 
-### 4. Documentation Updates
-After changing public behavior:
-- Update the affected package `README.md`
-- Update root `README.md` if the monorepo contract changed
-- Update `RELEASING.md` if release/versioning behavior changed
+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)
+- 16 MCP tools with mandatory calling protocols
+- Git workflow (dedicated contentrain branch, worktree isolation)
+- Security boundaries
+
+## Packages
 
-### 5. Commit Standards
-- Conventional commits: `feat(scope)`, `fix(scope)`, `refactor(scope)`
-- Scope = package name: `sdk`, `mcp`, `cli`, `types`, `rules`, `skills`
-- Commit message body: what was built, key decisions, test coverage summary
+| Directory | npm | What it does |
+|-----------|-----|-------------|
+| `packages/mcp` | `@contentrain/mcp` | 16 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 |
 
-## Commands
+## 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
-pnpm install
-pnpm dev              # All packages in watch mode (pnpm -r --parallel)
-pnpm build            # Build all packages (pnpm -r run build)
-pnpm test             # Vitest all packages
-pnpm lint             # oxlint
-lefthook install      # Git hooks
+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
diff --git a/README.md b/README.md
@@ -3,6 +3,7 @@
 [![npm: @contentrain/mcp](https://img.shields.io/npm/v/%40contentrain%2Fmcp?label=%40contentrain%2Fmcp)](https://www.npmjs.com/package/@contentrain/mcp)
 [![npm: contentrain](https://img.shields.io/npm/v/contentrain?label=contentrain)](https://www.npmjs.com/package/contentrain)
 [![npm: @contentrain/query](https://img.shields.io/npm/v/%40contentrain%2Fquery?label=%40contentrain%2Fquery)](https://www.npmjs.com/package/@contentrain/query)
+[![Agent Skills](https://img.shields.io/badge/Agent_Skills-15_skills-8B5CF6)](https://agentskills.io)
 [![Docs](https://img.shields.io/badge/docs-ai.contentrain.io-0f172a)](https://ai.contentrain.io)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
@@ -150,6 +151,26 @@ Works with Nuxt, Next.js, Astro, SvelteKit, Vue, React, Node, Go, Python, Swift,
 - **Serve UI** — local web dashboard for browsing models, content, validation, and normalize status
 - **Framework-agnostic** — MCP doesn't know your framework. Agent + skills handle stack-specific logic
 
+## Agent Skills
+
+This repo ships 15 [Agent Skills](https://agentskills.io) — reusable workflow procedures that any AI coding agent can load on demand.
+
+Install all skills to your agent:
+
+```bash
+npx skills add Contentrain/ai/packages/skills
+```
+
+Or install a specific skill:
+
+```bash
+npx skills add Contentrain/ai/packages/skills --skill contentrain-normalize
+```
+
+Skills work with Claude Code, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, Gemini CLI, and 40+ other agents.
+
+See [`AGENTS.md`](AGENTS.md) for the full skill catalog and agent guidance.
+
 ## Packages
 
 | Package | npm | Role |

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -4,6 +4,10 @@ export default defineConfig({
   title: 'Contentrain AI',
   description: 'Extract, govern, and ship structured content from your codebase.',
 
+  ignoreDeadLinks: [
+    /localhost/,
+  ],
+
   sitemap: {
     hostname: 'https://ai.contentrain.io',
   },
@@ -99,16 +103,10 @@ export default defineConfig({
 
     socialLinks: [
       { icon: 'github', link: 'https://github.com/Contentrain/ai' },
-      { icon: 'discord', link: 'https://discord.gg/8XbFKfgeZx' },
-      { icon: 'x', link: 'https://x.com/Contentrain_io' },
-      { icon: 'linkedin', link: 'https://www.linkedin.com/company/contentrain' },
-      { icon: 'youtube', link: 'https://www.youtube.com/@contentrain' },
-      { icon: 'instagram', link: 'https://www.instagram.com/contentrain_' },
-      { icon: 'facebook', link: 'https://www.facebook.com/Contentrain.io' },
     ],
 
     footer: {
-      message: 'Released under the MIT License.',
+      message: 'Released under the MIT License.<br><div class="footer-social-links"><a href="https://discord.gg/8XbFKfgeZx" target="_blank" rel="noopener" aria-label="Discord">Discord</a> · <a href="https://x.com/Contentrain_io" target="_blank" rel="noopener" aria-label="X">X</a> · <a href="https://www.linkedin.com/company/contentrain" target="_blank" rel="noopener" aria-label="LinkedIn">LinkedIn</a> · <a href="https://www.youtube.com/@contentrain" target="_blank" rel="noopener" aria-label="YouTube">YouTube</a> · <a href="https://www.instagram.com/contentrain_" target="_blank" rel="noopener" aria-label="Instagram">Instagram</a> · <a href="https://www.facebook.com/Contentrain.io" target="_blank" rel="noopener" aria-label="Facebook">Facebook</a></div>',
       copyright: 'Copyright © 2024-present Contentrain',
     },
 

diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
@@ -69,3 +69,21 @@
 .VPFeatures .VPFeature {
   backdrop-filter: blur(8px);
 }
+
+/* Footer social links */
+.footer-social-links {
+  display: flex;
+  justify-content: center;
+  gap: 8px;
+  margin-top: 8px;
+  font-size: 13px;
+}
+
+.footer-social-links a {
+  color: var(--vp-c-text-2);
+  transition: color 0.2s;
+}
+
+.footer-social-links a:hover {
+  color: var(--vp-c-brand-1);
+}
diff --git a/docs/demo.md b/docs/demo.md
@@ -117,3 +117,14 @@ This one flow shows Contentrain's full value:
 - Follow the full [Getting Started](/getting-started) guide
 - Read the full [Normalize Flow](/guides/normalize)
 - Use [Framework Integration](/guides/frameworks) for your stack
+
+## Ready for Team Collaboration?
+
+This 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):
+
+```bash
+contentrain studio login
+contentrain studio connect
+```
+
+Studio uses the same `.contentrain/` content model — no changes needed.
-Original file line number
+Diff line change
@@ Expand Up / @@ -46,6 +46,6 @@ docs/.vitepress/dist/ @@
     .tmp
     .mcpregistry_*
+    tmp/
     # Symlinked projects
     /studio