@contentrain/skills 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/skills",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "description": "AI agent skills for Contentrain — workflow procedures, framework integration guides",
   "type": "module",
@@ -61,7 +61,7 @@
     "tsdown": "^0.21.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@contentrain/mcp": "1.3.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 | 17 MCP tools (scan, apply, validate, merge, doctor...) | 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-tools.md

@@ -278,13 +278,42 @@ Push `cr/*` feature branches to remote.
 
 ### 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.
+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 | Feature branch name (must start with `cr/`) |
+| `branch` | string | Yes | The `cr/*` branch to delete |
+| `confirm` | `true` | Yes | Must be `true` to confirm deletion |
 
-Returns `{ action, commit, sync }` — `sync.skipped[]` lists files the selective sync skipped because the developer has uncommitted changes. The CLI surfaces this as a warning.
+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
 

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-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/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)),
     },
   },
 })