@contentrain/skills 0.1.2 → 0.2.1

package/skills/contentrain-bulk/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: contentrain-bulk
+description: "Batch operations on Contentrain content: copy locales, update status, delete multiple entries. Use when performing bulk content operations."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Run Bulk Content Operations
+
+> Apply safe batch operations to existing content entries.
+
+---
+
+## When to Use
+
+Use this when the user wants to:
+
+- copy one locale to another
+- update status on many entries
+- delete multiple collection entries
+
+This skill is for existing content, not for schema design.
+
+---
+
+## Steps
+
+### 1. Inspect the Model
+
+Call `contentrain_status` and `contentrain_describe(model: "<model-id>")` first.
+
+Confirm:
+
+- model kind
+- whether `i18n` is enabled
+- which locales are supported
+
+### 2. Pick the Correct Bulk Operation
+
+- `copy_locale`: clone one locale to another for i18n-enabled `collection`, `singleton`, or `dictionary` models
+- `update_status`: update metadata state for many collection entries
+- `delete_entries`: remove many collection entries at once
+
+### 3. Apply Safety Rules
+
+- never use `copy_locale` on non-i18n models
+- `update_status` and `delete_entries` are collection-only
+- confirm entry IDs before delete operations
+- batch only related entries together
+
+### 4. Execute with `contentrain_bulk`
+
+Examples:
+
+```json
+{
+  "operation": "copy_locale",
+  "model": "ui-labels",
+  "source_locale": "en",
+  "target_locale": "tr"
+}
+```
+
+```json
+{
+  "operation": "update_status",
+  "model": "blog-post",
+  "entry_ids": ["post_001", "post_002"],
+  "status": "in_review"
+}
+```
+
+```json
+{
+  "operation": "delete_entries",
+  "model": "faq-items",
+  "entry_ids": ["faq_01", "faq_02"],
+  "confirm": true
+}
+```
+
+### 5. Validate When Needed
+
+After `copy_locale` or status-heavy cleanup, call `contentrain_validate` if content correctness may have changed.
+
+### 6. Submit
+
+Bulk operations still create branches/commits. Call `contentrain_submit` if the project is in review flow.
+
+### 7. Final Summary
+
+Report:
+
+- operation performed
+- model affected
+- locale or entry count affected
+- validation outcome if run
+- submit status

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.