@contentrain/skills 0.1.1 → 0.2.0

package/skills/contentrain-review/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: contentrain-review
+description: "Review content changes for quality, accuracy, and compliance before publishing. Use when reviewing content, checking quality, or approving changes."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Review Pending Content Changes
+
+> Review content changes on Contentrain branches, apply quality checks, and recommend approval or rejection.
+
+---
+
+## When to Use
+
+The user wants to review content quality, audit existing entries, check pending changes, or run a pre-publish checklist. Triggers: "review content", "check pending changes", "review the contentrain branch", "content QA", "audit content", "pre-publish check".
+
+---
+
+## Steps
+
+### 1. Check Project State
+
+Call `contentrain_status` to understand the current project:
+
+- All models, their kinds, domains, and entry counts.
+- Configured locales and source locale.
+- Pending branches or unsubmitted changes.
+- Workflow mode (auto-merge or review).
+
+### 2. List Content for Review
+
+For each model (or the user-specified scope), call `contentrain_content_list(model: "<modelId>", locale: "<locale>")`:
+
+- Retrieve entries for the source locale first.
+- For i18n models, also retrieve entries for each target locale.
+- Note entry counts per locale to identify i18n coverage gaps.
+
+If reviewing a specific branch, list the `contentrain/*` branches and show:
+
+- Branch name (indicates operation type: extract, reuse, content-save, model-save).
+- Number of changed files.
+- Last commit date.
+
+### 3. Run Automated Validation
+
+Call `contentrain_validate` to get the automated validation report:
+
+- Schema compliance errors (missing required fields, type mismatches).
+- Referential integrity issues (broken relation references).
+- i18n completeness gaps (missing locale entries).
+- Content policy violations.
+
+### 4. Apply Quality Checklist
+
+Go through each category and report findings:
+
+#### 4.1 Content Quality (from content-quality.md)
+
+- [ ] All required fields are populated with real, non-placeholder values.
+- [ ] Text fields respect `min`/`max` constraints.
+- [ ] No placeholder text (lorem ipsum, TODO, TBD, [insert here]).
+- [ ] Tone is consistent with `context.json` → `conventions.tone`.
+- [ ] Vocabulary terms from `vocabulary.json` are used consistently.
+- [ ] Collection entries have no duplicate `unique` field values.
+- [ ] Content follows the correct content type pattern (blog post, landing page, docs, etc.).
+- [ ] No duplicate content across entries.
+
+#### 4.2 SEO (from seo-rules.md)
+
+- [ ] Page titles: 50-60 characters (max 70), primary keyword in first 30 characters.
+- [ ] Meta descriptions: 120-160 characters, complete sentences.
+- [ ] Slugs: kebab-case, descriptive, 3-5 words, no stop words.
+- [ ] Heading hierarchy in markdown/richtext: h1 → h2 → h3 (no skips).
+- [ ] Image alt text is present and descriptive (under 125 characters).
+- [ ] No orphan pages (content exists but is not linked/referenced).
+
+#### 4.3 Accessibility (from accessibility-rules.md)
+
+- [ ] Image fields have corresponding alt text fields (or the alt is embedded).
+- [ ] Color contrast: text color values meet WCAG AA ratio if paired colors are in the model.
+- [ ] Link text is descriptive (no raw URLs, "click here", or "read more" without context).
+- [ ] Media content has text alternatives where applicable.
+- [ ] Heading hierarchy is sequential (no skipped levels).
+- [ ] Color is not used as the sole means of conveying information.
+
+#### 4.4 Security (from security-rules.md)
+
+- [ ] No hardcoded secrets, API keys, or credentials in content fields.
+- [ ] No internal URLs or staging domains in production content.
+- [ ] User-generated or external URLs use HTTPS.
+- [ ] No inline JavaScript or script injection vectors in richtext/markdown fields.
+- [ ] No user-supplied HTML that could enable XSS.
+- [ ] Email fields contain valid, non-internal addresses (unless intended).
+
+#### 4.5 i18n Completeness (from i18n-quality.md)
+
+- [ ] All models with `i18n: true` have entries for every supported locale.
+- [ ] Entry counts match across locales (no missing translations).
+- [ ] Required fields are populated in every locale.
+- [ ] Dictionary keys are identical across all locale files.
+- [ ] Vocabulary terms are translated in all locales.
+- [ ] Translations are idiomatic (not word-for-word).
+- [ ] Translated text fits within field `max` constraints.
+- [ ] No source-locale text left untranslated in target locales.
+
+#### 4.6 Referential Integrity
+
+- [ ] All `relation` fields point to existing entries.
+- [ ] All `relations` arrays contain valid references.
+- [ ] No circular relations that could cause infinite loops.
+- [ ] Referenced entries are in a publishable state.
+
+### 5. Generate Review Report
+
+Present a structured report:
+
+```
+## Content Review Report
+
+### Summary
+- Models reviewed: X
+- Total entries: X
+- Locales checked: X
+
+### Issues Found
+
+#### Critical (must fix before publish)
+- [list of blocking issues with field references]
+
+#### Warning (should fix)
+- [list of non-blocking issues]
+
+#### Info (suggestions)
+- [list of improvements]
+
+### Per-Model Breakdown
+| Model | Kind | Entries | Issues | Status |
+|---|---|---|---|---|
+
+### i18n Coverage
+| Locale | Coverage | Missing Entries |
+|---|---|---|
+```
+
+### 6. Make a Recommendation
+
+Based on the findings:
+
+- **Approve:** No errors, few or no warnings. Changes are ready to merge.
+- **Request changes:** Errors or significant warnings found. List the specific changes needed.
+- **Reject:** Fundamental issues (wrong model structure, placeholder-only content, security violations). Explain why and suggest starting over.
+
+### 7. Offer Fixes
+
+For each fixable issue, offer to resolve it:
+
+- Missing translations: offer to run `/contentrain-translate`.
+- Schema violations: offer to update entries with `contentrain_content_save`.
+- Missing required fields: draft content for empty fields.
+- SEO issues: suggest improved titles, descriptions, slugs.
+
+Only make changes after user approval.
+
+### 8. Re-validate
+
+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.

package/skills/contentrain-sdk/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: contentrain-sdk
+description: "Use the @contentrain/query SDK to query Contentrain content with type safety. Use when importing from #contentrain, using QueryBuilder, SingletonAccessor, DictionaryAccessor, or DocumentQuery."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Contentrain Query SDK
+
+## Overview
+
+`@contentrain/query` is a Prisma-pattern generated client that provides type-safe access to Contentrain content. Generated output lives in `.contentrain/client/` — never edit it manually.
+
+## Quick Start
+
+```bash
+npx contentrain generate     # Generate client from models
+```
+
+```typescript
+import { query, singleton, dictionary, document } from '#contentrain'
+
+// Collection
+const posts = query('blog-post').where('category', 'eq', 'engineering').sort('published_at', 'desc').limit(10).all()
+
+// Singleton
+const hero = singleton('hero').get()
+
+// Dictionary
+const t = dictionary('ui-texts').get()
+const loginLabel = t['auth.login.button']
+
+// Document
+const doc = document('blog-post').bySlug('getting-started')
+```
+
+## Runtime API
+
+### QueryBuilder (collections)
+
+| Method | Description |
+|--------|-------------|
+| `.all()` | Get all entries |
+| `.first()` | Get first entry |
+| `.where(field, op, value)` | 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 |
+| `.include(relation)` | Resolve relation (1 level deep) |
+
+### SingletonAccessor
+
+| Method | Description |
+|--------|-------------|
+| `.get()` | Get the singleton data |
+| `.include(relation)` | Resolve relation fields |
+
+### DictionaryAccessor
+
+| Method | Description |
+|--------|-------------|
+| `.get()` | Get all key-value pairs |
+| `.get(key)` | Get single value by key |
+| `.get(key, params)` | Get with interpolation: `{placeholder}` → value |
+
+### DocumentQuery
+
+| Method | Description |
+|--------|-------------|
+| `.all()` | Get all documents |
+| `.bySlug(slug)` | Get document by slug |
+| `.first()` | Get first document |
+| `.where(field, op, value)` | Filter by frontmatter field |
+| `.include(relation)` | Resolve relation fields |
+
+## CDN Mode (Remote Data)
+
+For server-side or client-side apps that fetch content from Contentrain Studio CDN:
+
+```typescript
+import { createContentrain } from '@contentrain/query/cdn'
+
+const client = createContentrain({
+  projectId: '350696e8-...',
+  apiKey: 'crn_live_xxx',
+  // baseUrl: 'https://studio.contentrain.io/api/cdn/v1'  (default)
+})
+
+// All CDN queries are async (return Promise)
+const posts = await client.collection('faq').locale('en').all()
+const hero = await client.singleton('hero').locale('en').get()
+const t = await client.dictionary('ui').locale('en').get()
+const doc = await client.document('docs').locale('en').bySlug('intro')
+```
+
+### CDN Collection Query Operators
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| `eq` | `.where('status', 'eq', 'published')` | Equals |
+| `ne` | `.where('status', 'ne', 'draft')` | Not equals |
+| `gt` | `.where('order', 'gt', 5)` | Greater than |
+| `gte` | `.where('order', 'gte', 5)` | Greater than or equal |
+| `lt` | `.where('price', 'lt', 100)` | Less than |
+| `lte` | `.where('price', 'lte', 100)` | Less than or equal |
+| `in` | `.where('category', 'in', ['a','b'])` | In array |
+| `contains` | `.where('tags', 'contains', 'vue')` | String/array contains |
+
+### CDN vs Local
+
+| Aspect | Local (`#contentrain`) | CDN (`createContentrain()`) |
+|--------|----------------------|---------------------------|
+| Data source | Bundled `.mjs` files | HTTP fetch from CDN |
+| Return type | Sync (`T[]`) | Async (`Promise<T[]>`) |
+| Auth | None | API key required |
+| Caching | In-memory (embedded) | ETag-based HTTP cache |
+| Use case | SSG, build-time | SSR, client-side, serverless |
+
+## Key Rules
+
+- **Local mode** queries are **synchronous** — no `await` needed
+- **CDN mode** queries are **async** — always `await`
+- Relation resolution is **1 level deep** — no recursive resolution
+- Locale fallback chain: explicit → config default → first available
+- Generated files in `.contentrain/client/` are **immutable** — always regenerate, never edit
+- Run `contentrain generate` after any model change
+
+## Framework Integration
+
+| Framework | Import | Notes |
+|-----------|--------|-------|
+| Nuxt 3 | `import { query } from '#contentrain'` | Server-only (server routes, plugins) |
+| Next.js | `import { query } from '#contentrain'` | Works in RSC and API routes |
+| Astro | `import { query } from '#contentrain'` | Works in `.astro` frontmatter |
+| SvelteKit | `import { query } from '#contentrain'` | Works in `+page.server.ts` |
+| Vue + Vite | `import { query } from '#contentrain'` | Requires Vite alias config |
+| React + Vite | `import { query } from '#contentrain'` | Requires Vite alias config |
+| Node.js | `import { query } from '#contentrain'` | ESM with subpath imports |
+
+## References
+
+| Reference | Description |
+|-----------|-------------|
+| [Bundler Configuration](references/bundler-config.md) | Vite, Next.js, Nuxt, SvelteKit, Metro alias setup |

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

@@ -0,0 +1,135 @@
+---
+name: bundler-config
+description: "Framework-specific bundler configuration for #contentrain subpath imports"
+---
+
+# Bundler Configuration for #contentrain
+
+The `#contentrain` import requires subpath imports configuration in `package.json` and bundler-specific aliases.
+
+## package.json (all frameworks)
+
+```json
+{
+  "imports": {
+    "#contentrain": "./.contentrain/client/index.mjs"
+  }
+}
+```
+
+## Vite (Vue, React, Svelte)
+
+```typescript
+// vite.config.ts
+import { resolve } from 'node:path'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '#contentrain': resolve(__dirname, '.contentrain/client/index.mjs')
+    }
+  }
+})
+```
+
+## Next.js
+
+```javascript
+// next.config.mjs
+import { resolve } from 'node:path'
+
+export default {
+  webpack(config) {
+    config.resolve.alias['#contentrain'] = resolve(process.cwd(), '.contentrain/client/index.mjs')
+    return config
+  }
+}
+```
+
+## Nuxt 3
+
+```typescript
+// nuxt.config.ts
+import { resolve } from 'node:path'
+
+export default defineNuxtConfig({
+  alias: {
+    '#contentrain': resolve(__dirname, '.contentrain/client/index.mjs')
+  }
+})
+```
+
+**Important:** Treat `#contentrain` as **server-only** in Nuxt. Use in server routes, server plugins, and `useAsyncData` callbacks only.
+
+## SvelteKit
+
+```javascript
+// svelte.config.js
+import { resolve } from 'node:path'
+
+export default {
+  kit: {
+    alias: {
+      '#contentrain': resolve('.contentrain/client/index.mjs')
+    }
+  }
+}
+```
+
+## Expo / React Native (Metro)
+
+```javascript
+// metro.config.js
+const { getDefaultConfig } = require('expo/metro-config')
+const path = require('path')
+
+const config = getDefaultConfig(__dirname)
+config.resolver.extraNodeModules = {
+  '#contentrain': path.resolve(__dirname, '.contentrain/client/index.cjs')
+}
+module.exports = config
+```
+
+**Bootstrap required:**
+```javascript
+// App.js (before any #contentrain import)
+require('#contentrain').init()
+```
+
+## Node.js (pure ESM)
+
+No alias needed — Node.js natively supports `#imports` in `package.json`:
+
+```json
+{
+  "type": "module",
+  "imports": {
+    "#contentrain": "./.contentrain/client/index.mjs"
+  }
+}
+```
+
+## Node.js (CJS)
+
+```json
+{
+  "imports": {
+    "#contentrain": "./.contentrain/client/index.cjs"
+  }
+}
+```
+
+Bootstrap required:
+```javascript
+const contentrain = require('#contentrain')
+await contentrain.init()
+```
+
+## Watch Mode
+
+For development, run the generator in watch mode to auto-regenerate on model/content changes:
+
+```bash
+npx contentrain generate --watch
+```

package/skills/contentrain-serve/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: contentrain-serve
+description: "Start the local Contentrain review and normalize UI. Use when launching the serve interface, reviewing changes visually, or managing normalize plans."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Review the Project with `contentrain serve`
+
+> Start the local review UI as a bridge between agent and developer.
+
+---
+
+## When to Use
+
+Use this when:
+
+- a normalize plan, branch, or validation result needs developer review
+- the developer wants to browse models, content, or history visually
+- another skill needs to hand off to the UI for approval (normalize, review)
+
+---
+
+## Steps
+
+### 1. Check if Serve is Already Running
+
+Before starting a new instance, check if port 3333 is already in use:
+
+```bash
+lsof -ti:3333
+```
+
+If a process is running, serve is already up — skip to Step 3.
+
+### 2. Start Serve
+
+Run from the project root (where `.contentrain/` lives):
+
+```bash
+contentrain serve
+```
+
+Optional flags:
+
+- `--port` (default: 3333)
+- `--host` (default: localhost)
+- `--open=false` (prevent auto-opening browser)
+- `--stdio` (MCP stdio transport for IDE integration — no web UI)
+
+Wait for the "Contentrain Serve" banner confirming the server is ready.
+
+### 3. Direct the Developer to the Right Page
+
+Based on the current context, tell the developer exactly where to go:
+
+| Context | URL | What to do |
+|---|---|---|
+| Normalize plan ready | `http://localhost:3333/normalize` | Review extractions, approve or reject |
+| Pending branches | `http://localhost:3333/branches` | Review and merge branches |
+| Validation issues | `http://localhost:3333/validate` | Inspect errors and warnings |
+| Content browsing | `http://localhost:3333/content` | Browse entries and models |
+| General overview | `http://localhost:3333` | Dashboard with project stats |
+
+### 4. Wait for Developer Action
+
+After directing the developer to the UI:
+
+- **Normalize flow:** Check `.contentrain/normalize-plan.json` — if deleted, check for new branches to determine approve vs reject
+- **Branch flow:** Check branch list — if branch was merged or deleted, proceed accordingly
+- **Validation flow:** Re-read validation results after developer reviews
+
+The UI communicates back through filesystem changes (plan files, branches, context.json). Poll these to detect the developer's decision.
+
+### 5. Resume the Workflow
+
+After the developer acts in the UI:
+
+- If **approved**: continue with the next step in the calling skill (validate, submit, Phase 2)
+- If **rejected**: ask the developer what to change and iterate
+- If **merged**: confirm and report the final state
+
+Do NOT leave the developer hanging — always follow up after UI interaction.
+
+---
+
+## UI Philosophy
+
+The serve UI is a **monitoring + approval surface**, not an action trigger:
+
+- **Monitoring**: models, content, validation, history, branches — read-only browsing
+- **Approval**: approve/reject normalize plans, merge/delete branches — human decisions
+- **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.