@contentrain/skills 0.2.0 → 0.3.0

package/README.md

@@ -1,24 +1,46 @@
 # `@contentrain/skills`
 
 [![npm version](https://img.shields.io/npm/v/%40contentrain%2Fskills?label=%40contentrain%2Fskills)](https://www.npmjs.com/package/@contentrain/skills)
+[![Agent Skills](https://img.shields.io/badge/Agent_Skills-15_skills-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/skills)
+[![Docs](https://img.shields.io/badge/docs-ai.contentrain.io-0f172a)](https://ai.contentrain.io/packages/skills)
 
 Workflow skills and framework guides for Contentrain-aware AI agents.
 
+Start here:
+
+- [2-minute product demo](https://ai.contentrain.io/demo)
+- [Rules & skills docs](https://ai.contentrain.io/packages/rules)
+- [Framework integration guide](https://ai.contentrain.io/guides/frameworks)
+
 This package follows the [Agent Skills standard](https://agentskills.io) for progressive disclosure: each skill has a `SKILL.md` (loaded on activation) and optional `references/` (loaded on demand).
 
 ## Install
 
+### Via npm (programmatic access to catalogs and constants)
+
 ```bash
 pnpm add @contentrain/skills
 ```
 
-Or install directly via the skills CLI:
+### Via skills CLI (install skills into your AI agent)
 
 ```bash
-npx skills add contentrain/contentrain-ai --skill='*'
+# Install all 15 skills
+npx skills add Contentrain/ai/packages/skills
+
+# Install a specific skill
+npx skills add Contentrain/ai/packages/skills --skill contentrain-normalize
+
+# Install to a specific agent
+npx skills add Contentrain/ai/packages/skills --agent claude-code
+
+# List available skills
+npx skills add Contentrain/ai/packages/skills --list
 ```
 
+Works with Claude Code, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, Gemini CLI, and 40+ other agents.
+
 ## What It Contains
 
 ### Agent Skills (standard format)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/skills",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "AI agent skills for Contentrain — workflow procedures, framework integration guides",
   "type": "module",
@@ -9,7 +9,7 @@
     "url": "git+https://github.com/Contentrain/ai.git",
     "directory": "packages/skills"
   },
-  "homepage": "https://github.com/Contentrain/ai/tree/main/packages/skills",
+  "homepage": "https://ai.contentrain.io/packages/rules#skills",
   "bugs": {
     "url": "https://github.com/Contentrain/ai/issues"
   },
@@ -17,8 +17,14 @@
     "contentrain",
     "ai",
     "skills",
+    "agent-skills",
     "mcp",
     "workflow",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "copilot",
+    "codex",
     "vue",
     "react",
     "nuxt",

package/skills/contentrain/SKILL.md

@@ -10,6 +10,34 @@ metadata:
 
 Contentrain is a Git-based, AI-first content management system. Content lives in `.contentrain/` as JSON and Markdown files, managed through MCP tools. This skill covers architecture, content formats, and tool usage.
 
+## Ecosystem Overview
+
+Contentrain consists of 6 packages that work together:
+
+| Package | Role | How agent uses it |
+|---|---|---|
+| @contentrain/mcp | 16 MCP tools (scan, apply, validate, merge...) | MCP tool calls |
+| contentrain (CLI) | init, serve, generate, doctor, diff, status | Shell commands |
+| @contentrain/types | Shared TypeScript contracts | Type safety |
+| @contentrain/query | Generated SDK client (Prisma-pattern) | `import from '#contentrain'` |
+| @contentrain/rules | Behavioral guardrails (~86 lines, always-loaded) | Auto-loaded by IDE |
+| @contentrain/skills | Procedural workflows (this file) | On-demand by agent |
+
+### CLI Serve — Review & Approval Bridge
+
+For workflows requiring human review (normalize, content review):
+
+```bash
+contentrain serve  # http://localhost:3333
+```
+
+| Page | When to use |
+|---|---|
+| /normalize | Extraction/reuse preview and approval |
+| /branches | Merge or delete pending branches |
+| /validate | Review validation errors visually |
+| /content | Browse models and entries |
+
 ## Architecture: Agent vs MCP
 
 The system separates **intelligence** (agent) from **infrastructure** (MCP tools).
@@ -94,6 +122,7 @@ slug: getting-started
 | `contentrain_apply` | Apply normalize operation (extract or reuse) |
 | `contentrain_validate` | Validate content against model schemas |
 | `contentrain_submit` | Push contentrain/* branches to remote |
+| `contentrain_merge` | Merge a review-mode branch into contentrain locally |
 | `contentrain_bulk` | Run batch operations on existing content |
 
 ## Calling Sequences
@@ -121,6 +150,18 @@ apply(reuse, dry_run:true) --> [review] --> apply(reuse, dry_run:false)
   --> validate --> submit --> [repeat per model]
 ```
 
+## MUST Rules
+
+These are enforced by MCP — violating them causes errors. Know them upfront:
+
+- MUST call `contentrain_status` before any write operation on existing projects
+- MUST call `contentrain_describe_format` before creating models or content
+- MUST use `dry_run: true` before `contentrain_apply` execute
+- MUST call `contentrain_validate` before `contentrain_submit`
+- MUST run `npx contentrain generate` after model/content changes that affect SDK
+- MUST NOT write to `.contentrain/meta/`, `.contentrain/client/`, `.contentrain/context.json` directly
+- MUST NOT auto-merge normalize branches (always review mode)
+
 ## Key Guardrails
 
 1. **Always call `contentrain_status` first** when working with an existing project
@@ -147,3 +188,10 @@ apply(reuse, dry_run:true) --> [review] --> apply(reuse, dry_run:false)
 | [i18n](references/i18n.md) | Internationalization quality rules |
 | [Security](references/security.md) | XSS prevention, secret detection, URL validation |
 | [Workflow](references/workflow.md) | Git workflow, branch naming, conflict resolution |
+
+## Related Skills
+
+- **contentrain-normalize** — Two-phase extraction and source patching
+- **contentrain-serve** — Browser-based review and approval UI
+- **contentrain-generate** — SDK client generation
+- **contentrain-sdk** — @contentrain/query usage

package/skills/contentrain/references/mcp-pipelines.md

@@ -145,11 +145,14 @@ contentrain_submit                              # Push (always review mode)
 
 ### Rule 6: Branch and Worktree
 
-- Every write operation automatically creates a worktree and branch
+- A dedicated `contentrain` branch is the single source of truth for content state, created at init and protected from deletion
+- Every write operation creates a temporary worktree on a new feature branch forked from `contentrain`
 - Branch naming: `contentrain/{operation}/{model}/{timestamp}` (locale included when applicable)
 - Do not create branches manually. MCP handles Git transactions
-- `auto-merge` mode: branch merged to base branch after commit
-- `review` mode: branch pushed to remote by `contentrain_submit`
+- Developer's working tree is never mutated during MCP operations (no stash, no checkout, no merge on the developer's tree)
+- context.json is committed together with content changes, not as a separate commit
+- `auto-merge` mode: feature branch merged into `contentrain`, baseBranch advanced via update-ref, `.contentrain/` files selectively synced to developer's working tree (dirty files skipped with warning)
+- `review` mode: feature branch pushed to remote by `contentrain_submit`
 
 ### Rule 7: Branch Health
 

package/skills/contentrain/references/workflow.md

@@ -19,7 +19,7 @@ Contentrain supports two workflow modes, configured in `.contentrain/config.json
 { "workflow": "auto-merge" }
 ```
 
-- Branch is created, changes are committed, branch is **automatically merged to main**.
+- Feature branch is created from the `contentrain` branch, changes are committed, feature branch is **merged into `contentrain`**, then baseBranch is advanced via **update-ref** (fast-forward), and `.contentrain/` files are **selectively synced** to the developer's working tree.
 - No review step -- changes go live immediately.
 - Best for: solo developers, rapid iteration, prototyping, vibe coding.
 - Status flow: `draft` --> `published` (skips `in_review`).
@@ -72,37 +72,55 @@ contentrain/{operation}/{model}/{locale}/{timestamp}
 
 ## 3. Git Workflow
 
-### 3.1 Worktree-Based Transactions
+### 3.1 Dedicated `contentrain` Branch
+
+The `contentrain` branch is the **single source of truth** for content state:
+
+- Created automatically at `contentrain_init`.
+- All content writes happen on feature branches forked from `contentrain`.
+- The `contentrain` branch is **protected from deletion**.
+- context.json is committed together with content changes, not as a separate commit.
+
+### 3.2 Worktree-Based Transactions
 
 Every write operation follows this flow:
 
-1. MCP creates a **Git worktree** on a new branch.
-2. Changes are made in the worktree (content files, model files).
-3. Changes are committed to the branch.
-4. **auto-merge mode:** Branch is merged to main. Worktree is cleaned up.
-5. **review mode:** Branch is pushed to remote. Worktree is cleaned up. Studio notifies reviewers.
+1. MCP creates a **temporary Git worktree** on a new feature branch forked from `contentrain`.
+2. Changes are made in the worktree (content files, model files, context.json).
+3. Changes are committed to the feature branch.
+4. **auto-merge mode:** Feature branch is merged into `contentrain`, then baseBranch is advanced via **update-ref** (fast-forward), then `.contentrain/` files are **selectively synced** to the developer's working tree. Dirty files are skipped with a warning. Worktree is cleaned up.
+5. **review mode:** Feature branch is pushed to remote for team review. Worktree is cleaned up. Studio notifies reviewers.
+
+Developer's working tree is **never mutated** during MCP git operations. There is no stash, no checkout, and no merge on the developer's tree.
+
+### 3.3 Developer Manual Editing
+
+If the developer manually edits `.contentrain/` files in their working tree, MCP selective sync skips those dirty files and issues a warning. The developer must commit or discard their local changes before MCP can sync those files.
 
-### 3.2 Critical Rules
+### 3.4 Critical Rules
 
-- **NEVER commit directly to main.** All changes go through branches.
+- **NEVER commit directly to main or the `contentrain` branch.** All changes go through feature branches.
 - **NEVER create branches manually.** MCP tools handle all Git operations.
 - **NEVER force-push or rebase** Contentrain branches.
+- **NEVER delete the `contentrain` branch.** It is the content state SSOT.
 - Worktrees are temporary. They are created for the operation and cleaned up afterward.
 - Each branch contains a cohesive set of changes (e.g., all entries for one model update).
 
-### 3.3 Branch Lifecycle
+### 3.5 Branch Lifecycle
 
 ```
-Created (worktree) --> Committed --> Merged/Pushed --> Cleaned up
-                                         |
-                                         v
-                            auto-merge: merged to main
-                            review: pushed to remote, awaiting review
+Feature branch created (worktree on contentrain)
+  --> Changes committed
+  --> auto-merge: feature merged into contentrain
+                  --> update-ref advances baseBranch
+                  --> selective sync .contentrain/ to developer's tree
+  --> review: feature pushed to remote, awaiting review
+  --> Worktree cleaned up
 ```
 
-Merged branches are retained for `branchRetention` days (default: 30) for audit trail, then pruned.
+The `contentrain` branch is permanent and protected. Feature branches are retained for `branchRetention` days (default: 30) for audit trail, then pruned.
 
-### 3.4 Branch Health
+### 3.6 Branch Health
 
 MCP enforces branch health limits to prevent branch accumulation:
 
@@ -160,7 +178,7 @@ published --> archived
 |-------|-----------|---------|
 | `draft` | Branch exists, not yet reviewed/merged | Content created or updated |
 | `in_review` | PR/branch open, labeled `contentrain-content` | `contentrain_submit` in review mode |
-| `published` | Content is on main branch | Auto-merge, or PR merged after review |
+| `published` | Content is on `contentrain` branch and synced to baseBranch | Auto-merge, or PR merged after review |
 | `rejected` | PR closed without merge | Studio reviewer rejects changes |
 | `archived` | Metadata-only state | Manual action -- content hidden but retained |
 
@@ -208,8 +226,9 @@ published --> archived
 
 ```
 contentrain_submit
-  --> Merge branch to main
-  --> Update context.json
+  --> Merge feature branch into contentrain
+  --> Advance baseBranch via update-ref (fast-forward)
+  --> Selectively sync .contentrain/ files to developer's working tree
   --> Clean up worktree
   --> Status: published
 ```
@@ -218,8 +237,7 @@ contentrain_submit
 
 ```
 contentrain_submit
-  --> Push branch to remote
-  --> Update context.json
+  --> Push feature branch to remote
   --> Clean up worktree
   --> Status: in_review
   --> Studio notifies reviewers

package/skills/contentrain-bulk/SKILL.md

@@ -97,3 +97,10 @@ Report:
 - locale or entry count affected
 - validation outcome if run
 - submit status
+
+## Related Skills
+
+- **contentrain-content** — Single-entry content operations
+- **contentrain-validate-fix** — Validate after bulk changes
+- **contentrain-generate** — Regenerate SDK after bulk locale copy
+- **contentrain** — Core architecture and MCP tool catalog

package/skills/contentrain-content/SKILL.md

@@ -18,6 +18,16 @@ The user wants to create new content, add entries to a collection, populate a si
 
 ---
 
+## MUST Rules
+
+- MUST call `contentrain_describe` before writing content (know the schema)
+- MUST provide ALL required fields in entries
+- MUST create entries for ALL supported locales when model has `i18n: true`
+- MUST NOT set system fields (id, slug, createdAt, updatedAt, status, source)
+- MUST run `npx contentrain generate` after adding new models or changing fields
+
+---
+
 ## Steps
 
 ### 1. Check Project State
@@ -150,6 +160,16 @@ Call `contentrain_submit` to push branches to remote:
 
 Report the Studio URL if provided in the tool response -- the user can review and approve content there.
 
+### After Save: SDK Regeneration
+
+When new models are created or fields change, regenerate the SDK client:
+
+```bash
+npx contentrain generate
+```
+
+This updates TypeScript types for the new content. See: **contentrain-generate** skill.
+
 ### 12. Final Summary
 
 Report to the user:
@@ -160,3 +180,10 @@ Report to the user:
 - The submission status (auto-merged or pending review).
 - Studio link for visual review (if available).
 - Next steps: run `/contentrain-generate` to update SDK types if models changed.
+
+## Related Skills
+
+- **contentrain-serve** — Browser-based review for content branches
+- **contentrain-generate** — SDK client regeneration after content changes
+- **contentrain-quality** — Content quality, SEO, and accessibility rules
+- **contentrain** — Core architecture and MCP tool catalog

package/skills/contentrain-diff/SKILL.md

@@ -60,3 +60,18 @@ Summarize:
 - action taken
 - base branch affected
 - any follow-up branch still pending
+
+## Browser Alternative
+
+For visual branch review, use CLI serve:
+
+```bash
+contentrain serve
+```
+
+Navigate to http://localhost:3333/branches to see all pending branches with diffs, and merge or delete them visually.
+
+## Related Skills
+
+- **contentrain-serve** — Browser-based branch review and merge
+- **contentrain** — Core architecture and MCP tool catalog

package/skills/contentrain-doctor/SKILL.md

@@ -60,3 +60,10 @@ Recommended order:
 ### 5. Re-run Doctor
 
 After changes, run `contentrain doctor` again to confirm the project is healthy.
+
+## Related Skills
+
+- **contentrain-init** — Re-initialize if project structure is broken
+- **contentrain-validate-fix** — Fix content/model validation errors
+- **contentrain-generate** — Regenerate SDK if client is stale
+- **contentrain** — Core architecture and MCP tool catalog

package/skills/contentrain-generate/SKILL.md

@@ -181,3 +181,10 @@ Report to the user:
 - TypeScript types: available via `index.d.ts`.
 - Next steps: import `query` from `#contentrain` and start querying content.
 - Reminder: re-run `contentrain generate` after model or content changes.
+
+## Related Skills
+
+- **contentrain** — Core architecture and MCP tool catalog
+- **contentrain-normalize** — Normalize workflow requires SDK regen after Phase 2
+- **contentrain-content** — Content changes require SDK regen for type updates
+- **contentrain-sdk** — @contentrain/query usage after generation

package/skills/contentrain-generate/references/generated-client.md

@@ -110,11 +110,13 @@ import { query, singleton, dictionary, document } from '#contentrain'
 ```ts
 const posts = query('blog-post')
   .locale('en')               // set locale
-  .where('status', 'published') // exact match filter
+  .where('status', 'published') // equality filter (shorthand)
+  .where('views', 'gt', 100)  // operator filter: eq|ne|gt|gte|lt|lte|in|contains
   .sort('date', 'desc')       // sort by field
   .limit(10)                  // limit results
   .offset(5)                  // skip results
   .include('author', 'tags')  // resolve relation fields (1 level deep)
+  .count()                    // --> number (count of matches)
   .all()                      // --> T[] (returns array)
   .first()                    // --> T | undefined (first match)
 ```
@@ -143,22 +145,22 @@ Parameterized templates use `{placeholder}` syntax in dictionary values. The `ge
 ```ts
 const article = document('blog-article')
   .locale('en')
-  .where('category', 'tech')
+  .where('category', 'tech')           // equality shorthand
+  .where('title', 'contains', 'Guide') // operator syntax
   .include('author')          // resolve relations in frontmatter
   .bySlug('getting-started')  // --> T | undefined (find by slug)
 
-const docs = document('doc-page').locale('en').all()    // --> T[]
-const first = document('doc-page').locale('en').first()  // --> T | undefined
+const docs = document('doc-page').locale('en').all()     // --> T[]
+const first = document('doc-page').locale('en').first()   // --> T | undefined
+const total = document('doc-page').locale('en').count()   // --> number
 ```
 
 ### DOES NOT EXIST -- never use these
 
-- `.filter()` -- use `.where(field, value)` instead
+- `.filter()` -- use `.where(field, value)` or `.where(field, op, value)` instead
 - `.byId()` -- use `.where('id', value).first()` instead
-- `.count()` -- use `.all().length` instead
 - `dictionary().all()` -- use `.get()` instead
 - Queries are SYNC -- do not use `await` with `query()`, `singleton()`, `dictionary()`, or `document()`
-- `.where('field', 'eq', value)` -- just `.where('field', value)`
 - `.get()` on QueryBuilder -- use `.all()` or `.first()`
 
 ---

package/skills/contentrain-init/SKILL.md

@@ -96,4 +96,21 @@ Report to the user:
 - What was created in `.contentrain/`.
 - Which models were set up.
 - How to import content in their code (show the `#contentrain` import).
-- Next steps: create content, run `npx contentrain generate`, start the dev server.
+- **Next step: Run `npx contentrain generate` to create the typed SDK client.** Without this, `#contentrain` imports won't work. See: **contentrain-generate** skill.
+- Start the dev server and verify imports work.
+
+### Post-Init: Start Review UI
+
+After initialization, start the local review UI to explore the project:
+
+```bash
+contentrain serve
+```
+
+This opens http://localhost:3333 where you can browse models, content, and validation results.
+
+## Related Skills
+
+- **contentrain-serve** — Local review UI
+- **contentrain-generate** — SDK client generation
+- **contentrain** — Core architecture and MCP tool catalog

package/skills/contentrain-model/SKILL.md

@@ -139,3 +139,10 @@ Report:
 - field count
 - any relation targets
 - whether content migration is needed next
+
+## Related Skills
+
+- **contentrain-content** — Create content for this model after defining it
+- **contentrain-validate-fix** — Validate model and content after changes
+- **contentrain-generate** — Regenerate SDK after model changes
+- **contentrain** — Core architecture and MCP tool catalog

package/skills/contentrain-normalize/SKILL.md

@@ -17,6 +17,18 @@ Phase 1 alone is valuable: content becomes manageable in Studio, translatable, a
 
 ---
 
+## MUST Rules
+
+- MUST scan before extract (`contentrain_scan` → `contentrain_apply`)
+- MUST `dry_run: true` before `dry_run: false` for every `contentrain_apply` call
+- MUST merge Phase 1 branch before starting Phase 2
+- MUST run `npx contentrain generate` after Phase 2 completes
+- MUST NOT reuse without scoped model or domain (whole-project patching is blocked)
+- MUST NOT patch `.contentrain/` files via reuse (content files are read-only for reuse)
+- MUST NOT exceed 100 patches per `contentrain_apply` call
+
+---
+
 ## Two-Phase Architecture
 
 | Aspect | Phase 1: Extraction | Phase 2: Reuse |
@@ -105,6 +117,52 @@ Call `contentrain_validate` to check schema compliance, i18n completeness, and d
 
 Tell the user: "Phase 1 complete. Content is now in Contentrain and can be managed, translated, and published from Studio. When ready, proceed with Phase 2 to update source files."
 
+### Step 5: User Review
+
+Two paths — agent chooses based on context:
+
+**Path A — Browser Review (recommended for visual diff):**
+1. Ensure `contentrain serve` is running (or ask user to start it)
+2. Summarize the dry_run output to the user
+3. Direct user to http://localhost:3333/normalize
+4. Explain: "On this page you can review the extraction plan and Approve or Reject it."
+5. Wait for user decision
+
+**Path B — Terminal Review:**
+1. Show dry_run output to user
+2. Ask for explicit approval
+3. If approved: `contentrain_apply(mode: 'extract', dry_run: false)` → execute
+4. `contentrain_validate` → `contentrain_submit`
+5. `contentrain_merge(branch: 'cr/normalize/extract/...', confirm: true)` to merge locally
+
+### Step 6: Merge Phase 1 Branch
+
+Phase 2 CANNOT start until Phase 1 branch is merged. Three options:
+- **Browser:** localhost:3333/branches → click Merge
+- **MCP Tool:** `contentrain_merge(branch: 'cr/normalize/extract/...', confirm: true)`
+- **Git platform:** Create PR → review → merge
+
+Verify with `contentrain_status` — check that extract branch is no longer in unmerged list.
+
+### Step 7: Phase 2 Prerequisite Check
+
+Before starting reuse:
+1. Call `contentrain_status` and verify extract branch is merged
+2. If not merged → inform user and wait
+3. If merged → proceed to Phase 2 reuse
+
+### Step 8: SDK Regeneration (after Phase 2)
+
+After all reuse operations are complete, source files now use `#contentrain` imports.
+The SDK client MUST be regenerated:
+
+```bash
+npx contentrain generate
+```
+
+Without this, `#contentrain` imports will fail at build time.
+See: **contentrain-generate** skill for details.
+
 ---
 
 ## Phase 2: Reuse (Step-by-Step)
@@ -183,3 +241,10 @@ Ask the user which model or domain to process next. Repeat steps 1-5 for each re
 - [Extraction Details](references/extraction.md) -- Phase 1 extraction rules, parameters, and examples
 - [Reuse Details](references/reuse.md) -- Phase 2 replacement expressions by stack and patching rules
 - [What Is Content](references/what-is-content.md) -- Heuristics for identifying content vs code strings
+
+## Related Skills
+
+- **contentrain-serve** — Browser-based review UI for extraction approval
+- **contentrain-generate** — SDK client regeneration (required after reuse)
+- **contentrain-sdk** — @contentrain/query usage in source code
+- **contentrain** — Core architecture and full MCP tool catalog

package/skills/contentrain-quality/SKILL.md

@@ -178,3 +178,10 @@ Noun or noun phrase, sentence case, no trailing colons. Helper text: one sentenc
 - [SEO Rules](references/seo.md) -- SEO optimization rules for content fields, meta tags, and structured data
 - [Accessibility](references/accessibility.md) -- Accessibility rules for content: alt text, ARIA, color contrast, reading level
 - [Media Rules](references/media.md) -- Media asset rules: image optimization, video handling, file naming conventions
+
+## Related Skills
+
+- **contentrain-review** — Apply quality checks during content review
+- **contentrain-content** — Content creation following quality rules
+- **contentrain-translate** — Translation quality and i18n rules
+- **contentrain** — Core architecture and MCP tool catalog

package/skills/contentrain-review/SKILL.md

@@ -168,3 +168,9 @@ Only make changes after user approval.
 If fixes were applied, call `contentrain_validate` again to confirm all issues are resolved.
 
 Report the final status: "All checks passed" or list remaining issues that require manual attention.
+
+## Related Skills
+
+- **contentrain-serve** — Visual review at http://localhost:3333/content
+- **contentrain-quality** — Quality checklist reference
+- **contentrain** — Core architecture and MCP tool catalog

package/skills/contentrain-sdk/SKILL.md

@@ -43,7 +43,9 @@ const doc = document('blog-post').bySlug('getting-started')
 |--------|-------------|
 | `.all()` | Get all entries |
 | `.first()` | Get first entry |
-| `.where(field, op, value)` | Filter (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`) |
+| `.count()` | Return count of matching entries |
+| `.where(field, value)` | Equality filter (shorthand for `eq`) |
+| `.where(field, op, value)` | Operator filter: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains` |
 | `.sort(field, direction?)` | Sort (`asc`/`desc`, default `asc`) |
 | `.limit(n)` | Limit results |
 | `.offset(n)` | Skip results |
@@ -71,7 +73,9 @@ const doc = document('blog-post').bySlug('getting-started')
 | `.all()` | Get all documents |
 | `.bySlug(slug)` | Get document by slug |
 | `.first()` | Get first document |
-| `.where(field, op, value)` | Filter by frontmatter field |
+| `.count()` | Return count of matching documents |
+| `.where(field, value)` | Equality filter (shorthand) |
+| `.where(field, op, value)` | Operator filter (same ops as QueryBuilder) |
 | `.include(relation)` | Resolve relation fields |
 
 ## CDN Mode (Remote Data)
@@ -107,6 +111,28 @@ const doc = await client.document('docs').locale('en').bySlug('intro')
 | `in` | `.where('category', 'in', ['a','b'])` | In array |
 | `contains` | `.where('tags', 'contains', 'vue')` | String/array contains |
 
+### CDN Entry Metadata, Media & Forms
+
+```typescript
+// Entry metadata (status, publish_at, expire_at)
+const posts = await client.collection('blog').locale('en').withMeta().all()
+
+// Media manifest & variant URLs
+const media = client.media()
+const asset = await media.asset('hero.jpg')
+const url = media.url(asset, 'thumb')
+
+// Forms (config fetch + submit)
+const form = client.form()
+const config = await form.config('contact')
+const result = await form.submit('contact', { name: 'Alice' })
+
+// Conversation API (external AI content operations)
+const conv = client.conversation()
+const response = await conv.send('Create a blog post about Vue 4')
+const history = await conv.history(response.conversationId)
+```
+
 ### CDN vs Local
 
 | Aspect | Local (`#contentrain`) | CDN (`createContentrain()`) |
@@ -143,3 +169,9 @@ const doc = await client.document('docs').locale('en').bySlug('intro')
 | Reference | Description |
 |-----------|-------------|
 | [Bundler Configuration](references/bundler-config.md) | Vite, Next.js, Nuxt, SvelteKit, Metro alias setup |
+
+## Related Skills
+
+- **contentrain-generate** — Generate the SDK client before using it
+- **contentrain-quality** — Content quality rules for entries you query
+- **contentrain** — Core architecture and MCP tool catalog

package/skills/contentrain-serve/SKILL.md

@@ -94,3 +94,10 @@ The serve UI is a **monitoring + approval surface**, not an action trigger:
 - **Prompts**: every page shows copyable agent prompts that developers paste into their AI agent
 
 All mutations (create, edit, delete, scan, fix, normalize) are **agent-driven via MCP tools**. The UI never triggers these directly.
+
+## Related Skills
+
+- **contentrain-normalize** — Normalize workflow uses serve for extraction/reuse review and approval
+- **contentrain-diff** — Terminal-based branch review alternative to serve /branches page
+- **contentrain-review** — Content review workflow uses serve for visual inspection
+- **contentrain** — Core architecture and MCP tool catalog

package/skills/contentrain-translate/SKILL.md

@@ -135,6 +135,14 @@ After all translations are saved, re-generate the SDK client so the application
 npx contentrain generate
 ```
 
+### After Translation: SDK Regeneration
+
+New locale data requires SDK client regeneration:
+
+```bash
+npx contentrain generate
+```
+
 ### 8. Save Translations
 
 After approval, call `contentrain_content_save` for each model and target locale:
@@ -178,3 +186,10 @@ Report to the user:
 - Submission status.
 - Reminder to review translations for nuance that automated checks cannot catch.
 - Suggestion: run `/contentrain-review` to verify overall i18n coverage.
+
+## Related Skills
+
+- **contentrain-serve** — Review translated content in browser
+- **contentrain-generate** — SDK regeneration for new locale data
+- **contentrain-quality** — Translation quality rules
+- **contentrain** — Core architecture and MCP tool catalog

package/skills/contentrain-validate-fix/SKILL.md

@@ -90,3 +90,9 @@ If validation still fails:
 
 - summarize remaining blockers precisely
 - tell the user which model/entry needs manual attention
+
+## Related Skills
+
+- **contentrain-review** — Full content review workflow
+- **contentrain-content** — Fix content entries after validation errors
+- **contentrain** — Core architecture and MCP tool catalog