@contentrain/skills 0.1.1 → 0.2.0

package/skills/contentrain-content/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: contentrain-content
+description: "Create and manage content entries for existing Contentrain models. Use when adding entries to collections, populating singletons, writing documents, or managing dictionary keys."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Create Content for Existing Models
+
+> Generate and save content entries for models already defined in the project.
+
+---
+
+## When to Use
+
+The user wants to create new content, add entries to a collection, populate a singleton, or says something like "add a blog post", "create content", "fill in the hero section".
+
+---
+
+## Steps
+
+### 1. Check Project State
+
+Call `contentrain_status` to get the full project context:
+
+- Confirm the project is initialized.
+- List available models, their kinds, domains, and field counts.
+- Note supported locales and the source locale.
+- Check for any pending changes or validation errors.
+
+If `.contentrain/` does not exist, stop and suggest running `/contentrain-init` first.
+
+### 2. Identify the Target Model
+
+If the user specified a model, use it. Otherwise:
+
+- Present the list of available models from status.
+- Ask the user which model to create content for.
+- If the user describes content without naming a model (e.g., "write a blog post about X"), infer the model from context.
+
+### 3. Read the Model Definition
+
+Call `contentrain_describe(model: "<model-id>", include_sample: true)` to get:
+
+- All field definitions (name, type, required, constraints).
+- A sample entry if one exists (use it as a structural reference).
+- Relation fields and their target models.
+
+If the user's request does not match an existing model, offer to create one first with `contentrain_model_save`.
+
+### 4. Read Vocabulary and Context
+
+- 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).
+
+### 5. Generate Content
+
+Create content following the rules in `content-quality.md`:
+
+- **Required fields:** Every required field must have a real, non-placeholder value.
+- **Field constraints:** Respect `min`, `max`, `pattern`, and `options` constraints.
+- **Unique fields:** Verify `unique` field values do not collide with existing entries.
+- **Tone:** Match the tone defined in `.contentrain/context.json` → `conventions.tone`.
+- **Vocabulary:** Use terms from `.contentrain/vocabulary.json` if it exists.
+- **Content patterns:** Follow the appropriate content type pattern (blog post, landing page, documentation, etc.) from `content-quality.md` Section 3.
+- **Consistency:** If existing entries exist, read 2-3 via `contentrain_content_list` to match the established style and structure.
+
+**Relation integrity:** For `relation` and `relations` fields, verify referenced entries exist by calling `contentrain_content_list` on the target model.
+
+### 6. Apply SEO Rules
+
+For fields that affect SEO (from `seo-rules.md`):
+
+- **Title:** 50-60 characters optimal, max 70. Primary keyword in the first 30 characters.
+- **Slug:** Lowercase, hyphen-separated, 3-5 words, no stop words.
+- **Description/excerpt:** 120-160 characters, complete sentence, summarizes value.
+- **Alt text:** Descriptive, includes context, under 125 characters.
+- **Heading hierarchy:** In markdown/richtext content: h1 → h2 → h3 (no skips).
+
+### 7. Present Draft for Approval
+
+Show the user the content draft before writing. Include:
+
+- The model name and kind.
+- The content for each locale (if i18n).
+- Any relations being set.
+- A summary of which quality rules were applied.
+
+Wait for user confirmation before proceeding.
+
+### 8. Save Content
+
+Call `contentrain_content_save` with the approved content. The tool takes `model` and an `entries` array:
+
+```json
+contentrain_content_save({
+  "model": "<model-id>",
+  "entries": [
+    { "locale": "en", "data": { "field": "value" } }
+  ]
+})
+```
+
+**Kind-specific entry format:**
+
+- **singleton:** `{ "locale": "en", "data": { "title": "My Site", "cta": "Get Started" } }` -- no `id` or `slug`.
+- **collection:** `{ "id": "optional-id", "locale": "en", "data": { "name": "John", "role": "CEO" } }` -- omit `id` to auto-generate, provide `id` to update.
+- **document:** `{ "slug": "getting-started", "locale": "en", "data": { "title": "Getting Started", "body": "# Welcome\n..." } }` -- `slug` is required, use `"body"` key for markdown content.
+- **dictionary:** `{ "locale": "en", "data": { "auth.login": "Log In", "auth.logout": "Log Out" } }` -- flat key-value pairs, no `id` or `slug`.
+
+**Critical rules:**
+- NEVER include system fields (`status`, `source`, `updated_by`, `approved_by`) in `data`. These are managed in meta files, not content. Temporal data (created/updated timestamps) comes from git history.
+- 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
+
+If the project has multiple supported locales and the model has `i18n: true`:
+
+- Ask the user if they want translations created now.
+- If yes, generate translations following `i18n-quality.md` rules:
+  - Translate meaning, not words.
+  - Respect string expansion ratios.
+  - Preserve tone across locales.
+  - Check `vocabulary.json` for approved term translations.
+- Call `contentrain_content_save` for each target locale.
+
+If the user defers translations, note incomplete locales in the final summary.
+
+### 10. Validate
+
+Call `contentrain_validate` to check all changes:
+
+- Schema compliance (all required fields, correct types).
+- Referential integrity (relations point to existing entries).
+- i18n completeness (all locales have matching keys).
+- Content policy compliance.
+
+Fix any errors reported. Acknowledge any warnings.
+
+### 11. Submit
+
+Call `contentrain_submit` to push branches to remote:
+
+- Write operations already create branches and commit changes automatically.
+- `contentrain_submit` pushes unmerged `contentrain/*` branches to the remote.
+- In `auto-merge` mode, branches are already merged to the base branch during the write operation.
+- In `review` mode, branches are pushed for team review.
+
+Report the Studio URL if provided in the tool response -- the user can review and approve content there.
+
+### 12. Final Summary
+
+Report to the user:
+
+- How many entries were created/updated.
+- Which locales were covered.
+- The validation result.
+- 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.

package/skills/contentrain-diff/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: contentrain-diff
+description: "View content diffs between Contentrain branches. Use when comparing changes, reviewing branch differences, or checking what changed."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Review Pending Branches with `contentrain diff`
+
+> Inspect pending Contentrain branches and decide whether to merge, reject, or defer them.
+
+---
+
+## When to Use
+
+Use this when:
+
+- the project has pending `contentrain/*` branches
+- the user asks to review or merge changes
+- branch pressure is growing and cleanup is needed
+
+---
+
+## Steps
+
+### 1. Check Branch Pressure
+
+Start with `contentrain status`.
+
+If many `contentrain/*` branches are active, move into review immediately.
+
+### 2. Run `contentrain diff`
+
+Use the CLI to:
+
+- list pending branches
+- inspect the diff summary
+- review full patch output
+
+### 3. Evaluate the Change
+
+Check:
+
+- which model/content files changed
+- whether the change matches the intended operation
+- whether validation/normalize work was completed properly
+
+### 4. Choose an Outcome
+
+- merge when the diff is correct and complete
+- delete when the change is wrong or should be rejected
+- defer only when more human input is required
+
+### 5. Report the Decision
+
+Summarize:
+
+- branch reviewed
+- action taken
+- base branch affected
+- any follow-up branch still pending

package/skills/contentrain-doctor/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: contentrain-doctor
+description: "Diagnose Contentrain project health issues. Use when troubleshooting setup problems, checking configuration, or verifying project integrity."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Diagnose Project Health with `contentrain doctor`
+
+> Run health checks and turn failures into actionable fixes.
+
+---
+
+## When to Use
+
+Use this when:
+
+- setup seems broken
+- generated client may be stale
+- Git/content structure may be inconsistent
+- the user asks "what is wrong with this project?"
+
+---
+
+## Steps
+
+### 1. Run `contentrain doctor`
+
+Use the CLI health check as the first diagnostic pass.
+
+### 2. Group Findings
+
+Interpret failures by category:
+
+- Git problems
+- missing `.contentrain/` structure
+- bad config/model parsing
+- orphan content
+- too many pending branches
+- stale SDK client
+
+### 3. Fix in Priority Order
+
+Recommended order:
+
+1. Git / initialization blockers
+2. config/model parse failures
+3. orphan content or missing paths
+4. branch pressure
+5. stale generated client
+
+### 4. Apply the Correct Follow-up
+
+- not initialized → `contentrain init`
+- stale client → `contentrain generate`
+- branch pressure → `contentrain diff`
+- invalid content/model state → `contentrain validate`
+
+### 5. Re-run Doctor
+
+After changes, run `contentrain doctor` again to confirm the project is healthy.

package/skills/contentrain-generate/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: contentrain-generate
+description: "Generate the typed @contentrain/query SDK client from models. Use when running contentrain generate, setting up SDK, configuring bundler aliases, or integrating #contentrain imports."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Generate SDK Client
+
+> Generate the typed Contentrain query client from model definitions using the Prisma-pattern codegen.
+
+---
+
+## When to Use
+
+The user wants to generate or regenerate the SDK client, or says something like "generate client", "regenerate types", "set up contentrain imports", "run contentrain generate", "update SDK types".
+
+---
+
+## Steps
+
+### 1. Check Project State
+
+Call `contentrain_status` to verify:
+
+- `.contentrain/` directory exists with `config.json`.
+- At least one model exists in `.contentrain/models/`.
+- Content files exist for the configured locales.
+
+If the project is not initialized, stop and suggest running `/contentrain-init` first. If no models exist, suggest `/contentrain-content` to create content first.
+
+### 2. Verify Prerequisites
+
+Check that the required packages are available:
+
+- `@contentrain/query` must be installed in the project's `package.json` (as a dependency).
+- The `contentrain` CLI must be available (via `npx contentrain` or globally installed).
+
+If `@contentrain/query` is not installed, install it using the project's package manager:
+
+```bash
+# Use whichever package manager the project uses
+pnpm add @contentrain/query
+# or: npm install @contentrain/query
+# or: yarn add @contentrain/query
+```
+
+### 3. Run the Generator
+
+Execute the generation command:
+
+```bash
+npx contentrain generate
+```
+
+If the project uses a non-standard root directory, specify it:
+
+```bash
+npx contentrain generate --root .
+```
+
+This reads `.contentrain/models/` and `.contentrain/content/` to produce:
+
+```
+.contentrain/client/
+  index.mjs          — ESM entry (query runtime + re-exports)
+  index.cjs          — CJS entry (NestJS, Express, legacy tooling)
+  index.d.ts         — Generated types (from model schemas)
+  data/
+    {model}.{locale}.mjs   — Static data modules per model/locale
+```
+
+### 4. Verify package.json Imports
+
+The generator should have added `#contentrain` subpath imports to `package.json`. Verify the full import map:
+
+```json
+{
+  "imports": {
+    "#contentrain": {
+      "types": "./.contentrain/client/index.d.ts",
+      "import": "./.contentrain/client/index.mjs",
+      "require": "./.contentrain/client/index.cjs",
+      "default": "./.contentrain/client/index.mjs"
+    },
+    "#contentrain/*": {
+      "types": "./.contentrain/client/*.d.ts",
+      "import": "./.contentrain/client/*.mjs",
+      "require": "./.contentrain/client/*.cjs",
+      "default": "./.contentrain/client/*.mjs"
+    }
+  }
+}
+```
+
+If the imports entry is missing or incomplete, update `package.json` manually to match the full structure above.
+
+### 5. Verify TypeScript Configuration
+
+Ensure `tsconfig.json` does not block the generated client:
+
+- `paths` should not conflict with `#contentrain`.
+- `rootDir` or `include` should not exclude `.contentrain/client/`.
+- If using `moduleResolution: "bundler"` or `"node16"`, subpath imports resolve natively.
+
+### 6. Configure Bundler Alias
+
+The `#contentrain` subpath import works natively in Node.js 22+ but **does NOT resolve in browser bundlers**. If the project uses a bundler, configure an alias so `#contentrain` resolves to the generated client.
+
+See `references/generated-client.md` for framework-specific bundler configuration patterns (Vite, Next.js, Nuxt 3, SvelteKit, Expo/React Native, Pure Node.js).
+
+### 7. Verify Imports Work
+
+Run a quick verification that the imports resolve correctly.
+
+**Node.js / SSR-only projects:**
+
+```bash
+node -e "import('#contentrain').then(m => console.log('OK:', Object.keys(m)))"
+```
+
+**Browser / bundler projects:** run the framework's build command instead, since the Node.js check does not exercise the bundler alias:
+
+```bash
+# Vite-based (Vue, React, Svelte, Astro)
+npx vite build
+
+# Next.js
+npx next build
+
+# Nuxt 3
+npx nuxi build
+
+# Expo
+npx expo export
+```
+
+A successful build confirms the `#contentrain` alias resolves correctly through the bundler pipeline.
+
+If verification fails, check:
+- Node.js version >= 22 (required for native subpath imports).
+- `package.json` has `"type": "module"` (for ESM projects).
+- The `.contentrain/client/` directory was generated successfully.
+- The bundler alias is configured (see Step 6) for browser projects.
+
+### 8. Show Usage Examples
+
+Based on the detected stack and available models, show relevant examples using actual model IDs and field names from the project — not generic placeholders.
+
+See `references/generated-client.md` for the complete SDK API reference, relation patterns, and framework-specific usage patterns.
+
+### 9. Offer Watch Mode
+
+Suggest setting up watch mode for development:
+
+```bash
+npx contentrain generate --watch
+```
+
+This re-generates the client automatically whenever models or content change under `.contentrain/`. Recommend running it alongside the framework's dev server.
+
+For convenience, suggest adding a script to `package.json`:
+
+```json
+{
+  "scripts": {
+    "contentrain:watch": "contentrain generate --watch"
+  }
+}
+```
+
+### 10. Final Summary
+
+Report to the user:
+
+- Models processed: list each model and its kind.
+- Generated files: list the `.contentrain/client/` contents.
+- Locales included: list data files per locale.
+- Import path: `#contentrain` is ready to use.
+- 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.

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

@@ -0,0 +1,198 @@
+---
+name: generated-client
+description: "Generated client structure, framework bundler configs, and API patterns"
+---
+
+# Generated Client Reference
+
+## Bundler Alias Configuration
+
+The `#contentrain` subpath import works natively in Node.js 22+ but **does NOT resolve in browser bundlers**. Configure an alias for your framework.
+
+### Vite (Vue, React, Svelte, Astro)
+
+```ts
+// vite.config.ts
+import { resolve } from 'node:path'
+export default defineConfig({
+  resolve: {
+    alias: {
+      '#contentrain': resolve(__dirname, '.contentrain/client/index.mjs'),
+    },
+  },
+})
+```
+
+Also add a `paths` entry to `tsconfig.json` so the TypeScript language server resolves the alias:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "#contentrain": ["./.contentrain/client/index.d.ts"]
+    }
+  }
+}
+```
+
+### Next.js (webpack)
+
+```js
+// next.config.js
+const path = require('path')
+module.exports = {
+  webpack: (config) => {
+    config.resolve.alias['#contentrain'] = path.resolve(__dirname, '.contentrain/client/index.mjs')
+    return config
+  },
+}
+```
+
+Add the same `tsconfig.json` paths entry:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "#contentrain": ["./.contentrain/client/index.d.ts"]
+    }
+  }
+}
+```
+
+### Nuxt 3
+
+Nuxt provides a top-level `alias` option — no Vite config needed:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  alias: {
+    '#contentrain': './.contentrain/client/index.mjs',
+  },
+})
+```
+
+Add the `tsconfig.json` paths entry as above. Nuxt auto-extends `tsconfig.json` via `.nuxt/tsconfig.json`, so ensure the paths entry is in the project root `tsconfig.json`.
+
+### SvelteKit
+
+SvelteKit uses Vite internally. Add the alias in `vite.config.ts` as shown in the Vite section above.
+
+### Expo / React Native (Metro)
+
+```js
+// metro.config.js
+const path = require('path')
+module.exports = {
+  resolver: {
+    extraNodeModules: {
+      '#contentrain': path.resolve(__dirname, '.contentrain/client/index.mjs'),
+    },
+  },
+}
+```
+
+### Pure Node.js / SSR-only
+
+No alias needed. Node.js 22+ resolves `#contentrain` from `package.json` imports natively.
+
+---
+
+## Complete SDK API Reference
+
+```ts
+import { query, singleton, dictionary, document } from '#contentrain'
+```
+
+### QueryBuilder (for collection models) -- SYNC, no await needed
+
+```ts
+const posts = query('blog-post')
+  .locale('en')               // set locale
+  .where('status', 'published') // exact match filter
+  .sort('date', 'desc')       // sort by field
+  .limit(10)                  // limit results
+  .offset(5)                  // skip results
+  .include('author', 'tags')  // resolve relation fields (1 level deep)
+  .all()                      // --> T[] (returns array)
+  .first()                    // --> T | undefined (first match)
+```
+
+### SingletonAccessor (for singleton models)
+
+```ts
+const hero = singleton('hero')
+  .locale('en')
+  .include('featured_post')   // resolve relations on singletons too
+  .get()                      // --> T (single object)
+```
+
+### DictionaryAccessor (for dictionary models)
+
+```ts
+const allLabels = dictionary('ui-labels').locale('en').get()       // --> Record<string, string>
+const oneLabel = dictionary('ui-labels').locale('en').get('key')   // --> string | undefined
+const withParams = dictionary('ui-labels').locale('en').get('add-entry', { model: 'blog' })  // --> "Add a new entry to blog"
+```
+
+Parameterized templates use `{placeholder}` syntax in dictionary values. The `get(key, params)` overload replaces `{name}` with the provided value. Unmatched placeholders are left as-is.
+
+### DocumentQuery (for document models -- markdown + frontmatter)
+
+```ts
+const article = document('blog-article')
+  .locale('en')
+  .where('category', 'tech')
+  .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
+```
+
+### DOES NOT EXIST -- never use these
+
+- `.filter()` -- use `.where(field, 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()`
+
+---
+
+## With Relations
+
+```ts
+// Relations are resolved 1 level deep via .include()
+const posts = query('blog-post')
+  .locale('en')
+  .include('author', 'tags')
+  .all()
+// posts[0].author --> { id: '...', name: 'John', ... } (resolved object)
+
+// Without include:
+const raw = query('blog-post').locale('en').all()
+// raw[0].author --> 'author-id-123' (raw string ID, NOT resolved)
+
+// Singletons support include too:
+const hero = singleton('hero').locale('en').include('featured_post').get()
+
+// Documents support include too:
+const article = document('blog-article').locale('en').include('author').bySlug('my-post')
+```
+
+---
+
+## Framework-Specific Patterns
+
+| Stack | Usage Pattern | Alias Setup |
+|---|---|---|
+| Nuxt 3 | `useAsyncData(() => singleton('hero').locale(locale).get())` | `nuxt.config.ts` alias |
+| Next.js | In RSC: `const data = singleton('hero').locale('en').get()` | `next.config.js` webpack alias |
+| Astro | In frontmatter: `const posts = query('blog-post').locale('en').all()` | `vite.config.ts` alias |
+| SvelteKit | In `+page.server.ts`: `export const load = () => ({ hero: singleton('hero').locale('en').get() })` | `vite.config.ts` alias |
+| Expo / RN | `const hero = singleton('hero').locale('en').get()` | `metro.config.js` resolver |
+| Node.js / SSR | Direct import — no alias needed | Native subpath imports |