@contentrain/skills 0.3.0 → 0.5.0

package/README.md

@@ -10,10 +10,10 @@ 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)
+- [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).
+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/*.md` (loaded on demand).
 
 ## Install
 
@@ -45,54 +45,71 @@ Works with Claude Code, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, Gemini C
 
 ### Agent Skills (standard format)
 
-Published under `skills/`:
+Published under `skills/` — 15 production skills:
 
 | Skill | Description |
 |-------|-------------|
-| `contentrain` | Core architecture, MCP tools, content formats |
-| `contentrain-normalize` | Two-phase normalize (extract + reuse) |
-| `contentrain-quality` | Content quality, SEO, accessibility, media |
-| `contentrain-sdk` | @contentrain/query SDK usage (local + CDN) |
-| `contentrain-content` | Content CRUD operations |
-| `contentrain-model` | Model creation/update |
-| `contentrain-init` | Project initialization |
-| `contentrain-bulk` | Batch operations |
-| `contentrain-validate-fix` | Validation and auto-fix |
-| `contentrain-review` | Content quality review |
-| `contentrain-translate` | Multi-locale translation |
-| `contentrain-generate` | SDK client generation |
-| `contentrain-serve` | Local review/normalize UI |
-| `contentrain-diff` | Branch content diffs |
-| `contentrain-doctor` | Project health diagnostics |
+| `contentrain` | Core architecture, MCP tools, content formats, i18n, security |
+| `contentrain-normalize` | Two-phase normalize (extract hardcoded strings + patch source files) |
+| `contentrain-quality` | Content quality, SEO, accessibility, media optimization |
+| `contentrain-sdk` | Query SDK usage (#contentrain imports, QueryBuilder, type-safe access) |
+| `contentrain-content` | Create and manage content entries for existing models |
+| `contentrain-model` | Design and save model definitions |
+| `contentrain-init` | Initialize a new Contentrain project |
+| `contentrain-bulk` | Batch operations on content entries |
+| `contentrain-validate-fix` | Validate content and auto-fix structural issues |
+| `contentrain-review` | Review content changes before publishing |
+| `contentrain-translate` | Multi-locale translation workflows |
+| `contentrain-generate` | Generate the typed SDK client from models |
+| `contentrain-serve` | Start the local review and normalize UI |
+| `contentrain-diff` | View content diffs between branches |
+| `contentrain-doctor` | Diagnose project health issues |
 
 Each skill directory contains:
+
 ```
 skills/{name}/
-├── SKILL.md           # Instructions (< 500 lines)
+├── SKILL.md           # Instructions (< 500 lines, quick reference)
 └── references/        # Detailed docs (loaded on demand)
-    └── *.md
+    └── *.md           # Deep dives: architecture, patterns, examples
 ```
 
+Example references: `contentrain/references/mcp-tools.md`, `contentrain-normalize/references/extraction.md`, `contentrain-quality/references/seo.md`.
+
 ### Workflow skills (backward compat)
 
-Published under `workflows/*` — flat markdown files from previous versions. Still functional.
+Published under `workflows/` — flat markdown files retained for compatibility:
+
+- `contentrain-init.md`, `contentrain-model.md`, `contentrain-content.md`, `contentrain-bulk.md`
+- `contentrain-normalize.md`, `contentrain-validate-fix.md`, `contentrain-review.md`
+- `contentrain-diff.md`, `contentrain-doctor.md`, `contentrain-serve.md`
+- `contentrain-generate.md`, `contentrain-translate.md`
+
+Still fully functional; new projects should prefer the `skills/` structure.
 
 ### Framework guides
 
-Published under `frameworks/*`:
+Published under `frameworks/` — per-framework integration patterns:
 
-- `nuxt.md`, `next.md`, `astro.md`, `sveltekit.md`, `vue.md`, `react.md`, `expo.md`, `react-native.md`, `node.md`
+- `nuxt.md`, `next.md`, `astro.md`, `sveltekit.md` (meta frameworks)
+- `react.md`, `vue.md` (UI libraries)
+- `expo.md`, `react-native.md` (mobile)
+- `node.md` (backend)
 
 ## Public Exports
 
 ```ts
 import { AGENT_SKILLS, WORKFLOW_SKILLS, FRAMEWORK_GUIDES } from '@contentrain/skills'
 
-// Agent Skills catalog (name + description for Tier 1 discovery)
-console.log(AGENT_SKILLS)
+// Discover skills: name + description for agent activation
+AGENT_SKILLS.forEach(({ name, description }) => {
+  console.log(`${name}: ${description}`)
+})
+
+// Backward compat: flat workflow list
+console.log(WORKFLOW_SKILLS.length) // 12
 
-// Backward compat
-console.log(WORKFLOW_SKILLS)
+// Framework discovery
 console.log(FRAMEWORK_GUIDES)
 ```
 
@@ -100,15 +117,24 @@ console.log(FRAMEWORK_GUIDES)
 
 | Tier | What's Loaded | When | Token Cost |
 |------|--------------|------|------------|
-| 1. Catalog | `name` + `description` | Session start | ~50 tokens/skill |
+| 1. Catalog | `name` + `description` (AGENT_SKILLS) | Session start | ~50 tokens/skill |
 | 2. Instructions | Full `SKILL.md` body | Skill activated | < 5000 tokens |
-| 3. References | `references/*.md` | Agent needs detail | Varies |
+| 3. References | `references/*.md` files | Agent needs detail | Varies (50-500 tokens/file) |
+
+This reduces always-loaded context from thousands of lines to just the essentials plus catalog.
+
+## Parity with `@contentrain/mcp`
+
+`@contentrain/skills` is kept in lockstep with the MCP tool registry via cross-package parity tests (`tests/mcp-parity.test.ts`):
+
+- `skills/contentrain/references/mcp-tools.md` must have an `### <tool>` heading for every tool in the MCP `TOOL_NAMES` registry (currently 17).
+- Key skills (normalize, translate) must not reference legacy `contentrain/{operation}/...` branch prefixes — MCP now emits `cr/*`.
 
-This reduces always-loaded context from ~4,700 lines to ~86 lines (essential guardrails only).
+When MCP's surface changes, these tests fail until the skill docs catch up.
 
 ## IDE Support
 
-Skills are installed by `contentrain init` for detected IDEs:
+Skills are installed by `contentrain init` (and re-applied with `contentrain skills --update`) for detected IDEs:
 
 | IDE | Rules Dir | Skills Dir |
 |-----|-----------|------------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/skills",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "license": "MIT",
   "description": "AI agent skills for Contentrain — workflow procedures, framework integration guides",
   "type": "module",
@@ -60,7 +60,8 @@
     "@types/node": "^22.0.0",
     "tsdown": "^0.21.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "@contentrain/mcp": "1.5.0"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm,cjs --dts",

package/skills/contentrain/SKILL.md

@@ -16,7 +16,7 @@ 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/mcp | 19 MCP tools (scan, apply, validate, merge, doctor...) | 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'` |

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

@@ -147,7 +147,7 @@ contentrain_submit                              # Push (always review mode)
 
 - 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)
+- Branch naming: `cr/{operation}/{model}/{timestamp}` (locale included when applicable)
 - Do not create branches manually. MCP handles Git transactions
 - 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

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

@@ -269,13 +269,64 @@ Validate project content against model schemas.
 
 ### contentrain_submit
 
-Push contentrain/* branches to remote.
+Push `cr/*` feature branches to remote.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `branches` | string[] | No | Specific branches to push (omit for all contentrain/* branches) |
+| `branches` | string[] | No | Specific branches to push (omit for all `cr/*` branches) |
 | `message` | string | No | Optional message for the push operation |
 
+### contentrain_merge
+
+Merge a single review-mode `cr/*` branch into the content-tracking `contentrain` branch and advance the base branch via `update-ref`. Runs the worktree transaction with selective sync — dirty files in the developer's working tree are preserved rather than overwritten. The merged feature branch is pruned afterward.
+
+Target the branch by exact name, or resolve it by model:
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `branch` | string | No* | Exact feature branch name (must start with `cr/`) |
+| `model` | string | No* | Resolve the branch by model id (e.g. `blog-post`) |
+| `locale` | string | No | Narrow model resolution to a locale |
+| `latest` | boolean | No | When multiple branches match the model, merge the most recently committed one |
+| `confirm` | `true` | Yes | Must be `true` to confirm |
+
+\* Provide either `branch` or `model`. Ambiguous model matches return the candidate branches so you can pick one (or pass `latest: true`).
+
+Returns `{ branch, action, commit, sync }` — `sync.skipped[]` lists files the selective sync skipped because the developer has uncommitted changes. The CLI surfaces this as a warning.
+
+### contentrain_branch_list
+
+List pending `cr/*` branches with their merge status against the `contentrain` branch. Use it to discover branch names for `contentrain_merge` / `contentrain_branch_delete` and to monitor branch-health pressure (warning at 50, blocked at 80 unmerged). Read-only. Local-filesystem only (`localWorktree`).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `unmerged_only` | boolean | No | Only list branches not yet merged into `contentrain`. Default `false` |
+
+Returns `{ total, unmerged, branches: [{ name, sha, merged, lastCommit }], health }`.
+
+### contentrain_branch_delete
+
+Delete a pending `cr/*` branch that will not be merged — e.g. one left by a failed operation, or a superseded draft. Only `cr/*` branches can be deleted; the `contentrain` branch is protected. Destructive: the branch and its unmerged commits are removed.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `branch` | string | Yes | The `cr/*` branch to delete |
+| `confirm` | `true` | Yes | Must be `true` to confirm deletion |
+
+Returns `{ status: 'deleted', branch, was_merged }`. Note: in normal operation Contentrain prunes feature branches automatically after auto-merge / `contentrain_merge`, so this tool is for cleanup of leftover branches only.
+
+## Doctor Tools
+
+### contentrain_doctor
+
+Structured project health report: git install, Node version, `.contentrain/` structure, model parse, orphan content, pending branch pressure, SDK client freshness. Read-only. Local-filesystem only (`localWorktree` capability — unavailable over remote providers).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `usage` | boolean | No | Run the heavier usage-analysis branch (unused content keys, duplicate dictionary values, locale coverage). Default `false` |
+
+Returns `{ checks[], summary: { total, passed, failed, warnings }, usage? }`. Each check carries `name`, `pass`, `detail`, optional `severity: 'error' | 'warning' | 'info'`.
+
 ## Bulk Tools
 
 ### contentrain_bulk

package/skills/contentrain/references/workflow.md

@@ -45,21 +45,21 @@ Contentrain supports two workflow modes, configured in `.contentrain/config.json
 
 ## 2. Branch Naming Convention
 
-All Contentrain branches follow a strict naming pattern:
+All Contentrain feature branches follow a strict naming pattern:
 
 ```
-contentrain/{operation}/{model}/{locale}/{timestamp}
+cr/{operation}/{model}/{locale}/{timestamp}-{suffix}
 ```
 
 ### Examples
 
 | Scenario | Branch Name |
 |----------|-------------|
-| Content update | `contentrain/content/blog-post/en/1710300000` |
-| Model creation | `contentrain/model/team-member/1710300000` |
-| Normalize extraction | `contentrain/normalize/extract/blog/1710300000` |
-| Normalize reuse | `contentrain/normalize/reuse/marketing-hero/en/1710300000` |
-| Scaffold | `contentrain/new/scaffold-landing/en/1710300000` |
+| Content update | `cr/content/blog-post/en/1710300000-a1b2` |
+| Model creation | `cr/model/team-member/1710300000-c3d4` |
+| Normalize extraction | `cr/normalize/extract/blog/1710300000-e5f6` |
+| Normalize reuse | `cr/normalize/reuse/marketing-hero/en/1710300000-0789` |
+| Scaffold | `cr/new/scaffold-landing/en/1710300000-1234` |
 
 ### Rules
 

package/skills/contentrain-content/SKILL.md

@@ -63,6 +63,7 @@ If the user's request does not match an existing model, offer to create one firs
 
 - Check `.contentrain/vocabulary.json` for canonical terms. All content must use these terms consistently across locales. Do not use alternative spellings or synonyms for vocabulary-defined terms.
 - Check `.contentrain/context.json` for tone conventions (professional, casual, technical).
+- **For dictionaries:** Before creating any new key, call `contentrain_content_list` on the target model and scan existing values. If the value you intend to write already exists under a different key, REUSE the existing key instead of creating a new one. MCP will also warn you via `advisories` in the save response if duplicates are detected.
 
 ### 5. Generate Content
 
@@ -124,7 +125,17 @@ contentrain_content_save({
 - Prefer batch mode -- send multiple entries in a single call when possible.
 - Locale defaults to the project's default locale if omitted, but explicit locale is recommended.
 
-### 9. Handle i18n Completeness
+### 9. Review Save Advisories
+
+After `contentrain_content_save`, check the response for an `advisories` field. If present:
+
+- Review each advisory for duplicate value warnings.
+- If a duplicate is flagged, consider whether to:
+  - Remove the new key and reuse the existing one instead.
+  - Keep both keys if they serve semantically different purposes (document the reason).
+- Report any advisories to the user for their decision.
+
+### 10. Handle i18n Completeness
 
 If the project has multiple supported locales and the model has `i18n: true`:
 
@@ -138,7 +149,7 @@ If the project has multiple supported locales and the model has `i18n: true`:
 
 If the user defers translations, note incomplete locales in the final summary.
 
-### 10. Validate
+### 11. Validate
 
 Call `contentrain_validate` to check all changes:
 
@@ -149,7 +160,9 @@ Call `contentrain_validate` to check all changes:
 
 Fix any errors reported. Acknowledge any warnings.
 
-### 11. Submit
+For large content operations (10+ entries), also recommend running `contentrain doctor --usage` to detect unused keys and duplicate values across the project.
+
+### 12. Submit
 
 Call `contentrain_submit` to push branches to remote:
 
@@ -170,7 +183,7 @@ npx contentrain generate
 
 This updates TypeScript types for the new content. See: **contentrain-generate** skill.
 
-### 12. Final Summary
+### 13. Final Summary
 
 Report to the user:
 

package/skills/contentrain-generate/SKILL.md

@@ -54,6 +54,10 @@ Execute the generation command:
 npx contentrain generate
 ```
 
+> **Two ways to invoke the generator:**
+> - `contentrain generate` — via the `contentrain` CLI (recommended; requires the `contentrain` package installed). This is what all examples in this skill use.
+> - `npx contentrain-query generate` — directly via the `@contentrain/query` package's own bin, for projects that depend only on `@contentrain/query` (programmatic / build-tool flows). Both run the same generator.
+
 If the project uses a non-standard root directory, specify it:
 
 ```bash
@@ -170,6 +174,25 @@ For convenience, suggest adding a script to `package.json`:
 }
 ```
 
+### 9b. Wire generate into build/CI (REQUIRED for fresh clones)
+
+`.contentrain/client/` is git-ignored (it is generated output, like Prisma's client). That means a **fresh clone or CI checkout has no client**, so any `#contentrain` import fails at typecheck/build until `generate` runs.
+
+Wire generation into the build lifecycle so it always runs before a build:
+
+```json
+{
+  "scripts": {
+    "prebuild": "contentrain generate",
+    "predev": "contentrain generate"
+  }
+}
+```
+
+- `prebuild`/`predev` run automatically before `build`/`dev` (npm/pnpm lifecycle), so CI and teammates regenerate the client without a manual step.
+- Alternatively use a `postinstall` hook, but `prebuild`/`predev` are preferred (they don't run on every dependency install and stay close to when the client is actually needed).
+- If you only commit content occasionally, the watch script above covers local dev; the `prebuild` hook covers CI and fresh clones.
+
 ### 10. Final Summary
 
 Report to the user:

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

@@ -12,12 +12,12 @@ The `#contentrain` subpath import works natively in Node.js 22+ but **does NOT r
 ### Vite (Vue, React, Svelte, Astro)
 
 ```ts
-// vite.config.ts
-import { resolve } from 'node:path'
+// vite.config.ts (ESM — __dirname is not defined; use import.meta.url)
+import { fileURLToPath } from 'node:url'
 export default defineConfig({
   resolve: {
     alias: {
-      '#contentrain': resolve(__dirname, '.contentrain/client/index.mjs'),
+      '#contentrain': fileURLToPath(new URL('.contentrain/client/index.mjs', import.meta.url)),
     },
   },
 })
@@ -60,9 +60,9 @@ Add the same `tsconfig.json` paths entry:
 }
 ```
 
-### Nuxt 3
+### Nuxt 3 / Nuxt 4
 
-Nuxt provides a top-level `alias` option — no Vite config needed:
+Nuxt provides a top-level `alias` option — no Vite config needed (the relative string avoids `__dirname` entirely):
 
 ```ts
 // nuxt.config.ts

package/skills/contentrain-normalize/SKILL.md

@@ -27,6 +27,30 @@ Phase 1 alone is valuable: content becomes manageable in Studio, translatable, a
 - MUST NOT patch `.contentrain/` files via reuse (content files are read-only for reuse)
 - MUST NOT exceed 100 patches per `contentrain_apply` call
 
+## Transport Requirements
+
+Normalize (`contentrain_scan` and `contentrain_apply`) requires **local
+disk access** — AST scanners walk the source tree and patch files in
+place. It runs only on a `LocalProvider` (stdio transport, or an HTTP
+transport configured with a `LocalProvider`).
+
+Remote providers (`GitHubProvider`, `GitLabProvider`, future
+`BitbucketProvider`) expose `astScan: false`, `sourceRead: false`, and
+`sourceWrite: false`. Calling these tools over a remote provider
+returns a uniform capability error:
+
+```json
+{
+  "error": "contentrain_scan requires local filesystem access.",
+  "capability_required": "astScan",
+  "hint": "This tool is unavailable when MCP is driven by a remote provider. Use a LocalProvider or the stdio transport."
+}
+```
+
+If the agent is driving a remote-only MCP session, normalize must run
+in a separate local-checkout session before the extracted content
+branch is pushed.
+
 ---
 
 ## Two-Phase Architecture
@@ -36,7 +60,7 @@ Phase 1 alone is valuable: content becomes manageable in Studio, translatable, a
 | Purpose | Pull content from source to `.contentrain/` | Patch source files with content references |
 | Scope | Full project scan | Per model or per domain |
 | Source files modified | No | Yes |
-| Branch pattern | `contentrain/normalize/extract/{domain}/{timestamp}` | `contentrain/normalize/reuse/{model}/{locale}/{timestamp}` |
+| Branch pattern | `cr/normalize/extract/{domain}/{timestamp}` | `cr/normalize/reuse/{model}/{locale}/{timestamp}` |
 | Prerequisite | Initialized `.contentrain/` | Completed extraction (content exists in `.contentrain/`) |
 | Workflow mode | Always `review` | Always `review` |
 | Standalone value | Yes -- content is manageable in Studio immediately | Depends on Phase 1 |
@@ -109,7 +133,7 @@ Call `contentrain_apply(mode: "extract", dry_run: true)` to generate a preview.
 
 ### 6. Execute Extraction
 
-After user approval, call `contentrain_apply(mode: "extract", dry_run: false)`. This creates model definitions and content files in `.contentrain/` on a `contentrain/normalize/extract/{timestamp}` branch. Source files are NOT modified.
+After user approval, call `contentrain_apply(mode: "extract", dry_run: false)`. This creates model definitions and content files in `.contentrain/` on a `cr/normalize/extract/{timestamp}` branch. Source files are NOT modified.
 
 ### 7. Validate and Submit
 
@@ -183,7 +207,7 @@ Call `contentrain_apply(mode: "reuse", scope: { model: "<model-id>" }, patches:
 
 ### 4. Execute Reuse
 
-After user confirmation, call `contentrain_apply(mode: "reuse", scope: { model: "<model-id>" }, patches: [...], dry_run: false)`. This patches source files and creates a `contentrain/normalize/reuse/{model}/{timestamp}` branch.
+After user confirmation, call `contentrain_apply(mode: "reuse", scope: { model: "<model-id>" }, patches: [...], dry_run: false)`. This patches source files and creates a `cr/normalize/reuse/{model}/{timestamp}` branch.
 
 ### 5. Validate and Submit
 

package/skills/contentrain-normalize/references/extraction.md

@@ -113,7 +113,7 @@ Returns a preview of what will be created in `.contentrain/` without making chan
 contentrain_apply(mode: "extract", dry_run: false)
 ```
 
-Creates model definitions and content files in `.contentrain/` on a `contentrain/normalize/extract/{timestamp}` branch. `dry_run` defaults to `true`, so you MUST explicitly set `dry_run: false` to execute.
+Creates model definitions and content files in `.contentrain/` on a `cr/normalize/extract/{timestamp}` branch. `dry_run` defaults to `true`, so you MUST explicitly set `dry_run: false` to execute.
 
 ### 7. Validate and Submit
 

package/skills/contentrain-normalize/references/reuse.md

@@ -42,7 +42,7 @@ Review the dry-run output:
 contentrain_apply(mode: "reuse", scope: { model: "<model-id>" }, patches: [...], dry_run: false)
 ```
 
-`dry_run` defaults to `true`, so you MUST explicitly set `dry_run: false` to execute. This patches source files and creates a `contentrain/normalize/reuse/{model}/{timestamp}` branch.
+`dry_run` defaults to `true`, so you MUST explicitly set `dry_run: false` to execute. This patches source files and creates a `cr/normalize/reuse/{model}/{timestamp}` branch.
 
 ### 5. Validate and Submit
 

package/skills/contentrain-quality/references/content-quality.md

@@ -74,6 +74,8 @@ If the agent cannot produce real content, it must leave the entry in `draft` sta
 - Descriptions/excerpts must be unique across all entries in the same collection.
 - If content is shared across entries, extract it to a referenced entry and use a `relation` field.
 - Before writing, query existing entries to confirm no duplication.
+- **Dictionary values:** Different keys must not map to identical values. If "Cancel" exists under `dialog.cancel`, do not create `form.cancel` with the same value — reuse the existing key. MCP warns automatically via `advisories` in the save response.
+- **Cross-model deduplication:** If the same text appears across multiple dictionary models, consider moving it to a shared dictionary or using vocabulary terms for consistency.
 
 ---
 

package/skills/contentrain-sdk/references/bundler-config.md

@@ -20,14 +20,14 @@ The `#contentrain` import requires subpath imports configuration in `package.jso
 ## Vite (Vue, React, Svelte)
 
 ```typescript
-// vite.config.ts
-import { resolve } from 'node:path'
+// vite.config.ts (ESM — __dirname is not defined here)
+import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vite'
 
 export default defineConfig({
   resolve: {
     alias: {
-      '#contentrain': resolve(__dirname, '.contentrain/client/index.mjs')
+      '#contentrain': fileURLToPath(new URL('.contentrain/client/index.mjs', import.meta.url))
     }
   }
 })
@@ -47,20 +47,22 @@ export default {
 }
 ```
 
-## Nuxt 3
+## Nuxt 3 / Nuxt 4
 
 ```typescript
-// nuxt.config.ts
-import { resolve } from 'node:path'
+// nuxt.config.ts (ESM — use import.meta.url, not __dirname)
+import { fileURLToPath } from 'node:url'
 
 export default defineNuxtConfig({
   alias: {
-    '#contentrain': resolve(__dirname, '.contentrain/client/index.mjs')
+    '#contentrain': fileURLToPath(new URL('.contentrain/client/index.mjs', import.meta.url))
   }
 })
 ```
 
-**Important:** Treat `#contentrain` as **server-only** in Nuxt. Use in server routes, server plugins, and `useAsyncData` callbacks only.
+**Important:** Treat `#contentrain` as **server-only** in Nuxt. Use it in server routes (`server/`), server plugins, and `useAsyncData` callbacks only.
+
+**Nuxt 4 note:** Nuxt 4 moves app code under `app/` and keeps server code under `server/`. The alias above is resolved relative to `nuxt.config.ts` (project root), so it is unchanged — but make sure your `#contentrain` calls live in `server/` (e.g. `server/api/*`), never in `app/` components that run on the client.
 
 ## SvelteKit
 

package/skills/contentrain-translate/SKILL.md

@@ -170,7 +170,7 @@ If validation fails, fix issues and re-save.
 
 Call `contentrain_submit` to commit the translations:
 
-- Branch: `contentrain/content/{model}/{targetLocale}/{timestamp}`.
+- Branch: `cr/content/{model}/{targetLocale}/{timestamp}`.
 - Each locale can be submitted independently.
 
 ### 11. Final Summary

package/workflows/contentrain-generate.md

@@ -103,12 +103,12 @@ The `#contentrain` subpath import works natively in Node.js 22+ but **does NOT r
 #### Vite (Vue, React, Svelte, Astro)
 
 ```ts
-// vite.config.ts
-import { resolve } from 'node:path'
+// vite.config.ts (ESM — __dirname is not defined; use import.meta.url)
+import { fileURLToPath } from 'node:url'
 export default defineConfig({
   resolve: {
     alias: {
-      '#contentrain': resolve(__dirname, '.contentrain/client/index.mjs'),
+      '#contentrain': fileURLToPath(new URL('.contentrain/client/index.mjs', import.meta.url)),
     },
   },
 })

package/workflows/contentrain-normalize.md

@@ -134,7 +134,7 @@ Do NOT proceed to apply unless the user approves (either via UI or explicit conf
 
 4. **Detect the user's decision.** After directing the user to the UI, check the plan file to determine the outcome:
    - **Plan file exists** (`status: "pending"`) → user has not decided yet — wait
-   - **Plan file deleted + new `contentrain/normalize/extract/*` branch exists** → user approved, extraction applied
+   - **Plan file deleted + new `cr/normalize/extract/*` branch exists** → user approved, extraction applied
    - **Plan file deleted + no new branch** → user rejected the plan
 
    If rejected, ask the user what to change and iterate from Step 4 (re-evaluate candidates).
@@ -161,7 +161,7 @@ After user approval (via UI or chat), call `contentrain_apply(mode: "extract", d
 
 Note: `dry_run` defaults to `true`, so you MUST explicitly set `dry_run: false` to execute.
 
-This creates model definitions and content files in `.contentrain/` on a `contentrain/normalize/extract/{timestamp}` branch. Source files are NOT modified.
+This creates model definitions and content files in `.contentrain/` on a `cr/normalize/extract/{timestamp}-{suffix}` branch. Source files are NOT modified.
 
 If approved via UI, the UI calls this automatically — no additional agent action needed.
 
@@ -230,7 +230,7 @@ After user confirmation, call `contentrain_apply(mode: "reuse", scope: { model:
 
 Note: `dry_run` defaults to `true`, so you MUST explicitly set `dry_run: false` to execute.
 
-This patches source files and creates a `contentrain/normalize/reuse/{model}/{timestamp}` branch.
+This patches source files and creates a `cr/normalize/reuse/{model}/{timestamp}-{suffix}` branch.
 
 ### Step 5. Validate and Submit
 

package/workflows/contentrain-translate.md

@@ -154,7 +154,7 @@ If validation fails, fix issues and re-save.
 
 Call `contentrain_submit` to commit the translations:
 
-- Branch: `contentrain/content/{model}/{targetLocale}/{timestamp}`.
+- Branch: `cr/content/{model}/{targetLocale}/{timestamp}-{suffix}`.
 - Each locale can be submitted independently.
 
 ### 11. Final Summary