@contentrain/skills 0.1.2 → 0.2.1

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

@@ -0,0 +1,229 @@
+---
+name: seo
+description: "SEO optimization rules for content fields, meta tags, and structured data"
+---
+
+# SEO Rules
+
+These rules govern search engine optimization for all content managed through Contentrain.
+Apply these rules to every content entry that produces a public-facing page.
+
+---
+
+## 1. Page Titles
+
+### 1.1 Length and Format
+
+- Length: 50-60 characters including spaces. Google truncates titles beyond ~60 characters.
+- Measure character count before saving. Truncated titles harm click-through rates.
+- No ALL CAPS titles. Use sentence case or title case per project convention.
+- No excessive punctuation: no `!!!`, no `???`, no `...` in titles.
+- No emoji in titles unless explicitly configured in `context.json`.
+
+### 1.2 Keyword Placement
+
+- Place the primary keyword within the first 30 characters.
+- Structure: `Primary Keyword Phrase | Brand Name` or `Primary Keyword Phrase -- Brand Name`.
+- Acceptable separators: ` | `, ` -- `, ` - `. Pick one and use it consistently across all entries.
+- The keyword must read naturally -- no keyword stuffing.
+  - GOOD: "Deploy Node.js to Production | Acme Docs"
+  - BAD: "Node.js Deploy Node Production Deployment | Acme"
+
+### 1.3 Uniqueness
+
+- Every entry in a collection MUST have a unique title.
+- Before saving, query existing entries and confirm no title collision.
+- Titles across collections should also be unique when they produce public pages.
+
+---
+
+## 2. Meta Descriptions
+
+### 2.1 Length and Format
+
+- Length: 120-155 characters including spaces.
+- Must be a complete sentence or two short sentences.
+- End with a period.
+- No keyword stuffing -- write for humans, not crawlers.
+
+### 2.2 Content Requirements
+
+- Include a clear value proposition or call-to-action.
+  - GOOD: "Learn how to set up CI/CD for your Node.js project in 10 minutes. Step-by-step guide with examples."
+  - BAD: "CI/CD Node.js setup guide tutorial deployment continuous integration."
+- Must differ from the page title -- do not repeat the title as the description.
+- Must be unique per entry. No two entries may share the same meta description.
+
+### 2.3 What to Avoid
+
+- No quotes or special characters that break HTML meta tags: avoid `"`, `<`, `>`.
+- No "Click here to learn more" -- search engines ignore generic CTAs.
+- No date references that will become stale (prefer "latest" over "2024").
+
+---
+
+## 3. Slugs
+
+### 3.1 Format
+
+- Lowercase only. No uppercase characters.
+- Words separated by hyphens (`-`). No underscores, no spaces, no dots.
+- No special characters: only `a-z`, `0-9`, and `-`.
+- No consecutive hyphens (`--`). No leading or trailing hyphens.
+
+### 3.2 Length and Content
+
+- Optimal: 3-5 words.
+- Maximum: 60 characters.
+- Remove stop words (`the`, `a`, `an`, `is`, `of`, `and`, `or`, `in`, `to`) unless removing them changes meaning.
+  - "how-to-deploy-node" -> "deploy-node" is acceptable.
+  - "state-of-the-art" -> keep as-is because meaning changes if shortened.
+
+### 3.3 Stability
+
+- NEVER change a slug on a published entry. Changing slugs breaks existing links, bookmarks, and search engine indexing.
+- If a slug must change, the human must set up a redirect. The agent must not change published slugs without explicit human instruction.
+- Draft entries may have their slugs changed freely before first publication.
+
+### 3.4 Locale Consistency
+
+- Use the same slug value across all locales for the same entry.
+- Do NOT translate slugs. Slugs are identifiers, not content.
+- Example: the slug `deploy-node` remains `deploy-node` in `en`, `tr`, `de`, and all other locales.
+
+---
+
+## 4. Heading Structure
+
+### 4.1 H1 Rule
+
+- Exactly one H1 per page. The H1 is the entry title or the primary heading.
+- The H1 should contain the primary keyword naturally.
+- Do not duplicate the H1 text elsewhere on the page.
+
+### 4.2 Subheading Keywords
+
+- Include relevant keywords in H2 and H3 headings where natural.
+- Do not force keywords into every heading. Clarity takes priority over keyword density.
+- Use question-format headings for FAQ-style content: "How do I reset my password?"
+
+### 4.3 Hierarchy Reflects Content
+
+- Heading levels must reflect the logical structure of the content.
+- Do not use H3 because it renders smaller -- use CSS for styling, headings for structure.
+- Every heading must have content beneath it. No empty sections.
+- Do not place two headings consecutively without content between them.
+
+---
+
+## 5. Images and Alt Text
+
+### 5.1 Alt Text Requirements
+
+- Every `image` field that displays on a public page MUST have corresponding alt text.
+- Describe the image content and its context: "Dashboard showing monthly revenue chart with 15% growth indicator."
+- Maximum length: 125 characters.
+- Do not start with "Image of", "Photo of", "Picture of" -- describe directly.
+
+### 5.2 Decorative Images
+
+- If an image is purely decorative (visual separator, background pattern), set alt text to an empty string (`""`).
+- Do not omit the alt field entirely -- explicitly set it to empty.
+
+### 5.3 Keywords in Alt Text
+
+- Include relevant keywords naturally when they describe the image.
+- Do not stuff keywords: "Node.js Node deployment Node server Node production" is forbidden.
+- The alt text must accurately describe what is in the image.
+
+### 5.4 Image File Names
+
+- When the agent controls the image file name, use descriptive, hyphenated names.
+  - GOOD: `revenue-dashboard-chart.png`
+  - BAD: `IMG_2847.png`, `screenshot.png`, `image1.png`
+
+---
+
+## 6. Open Graph and Social Media
+
+### 6.1 Open Graph Tags
+
+When OG fields exist in the model, populate them:
+
+| Field | Max Length | Requirement |
+|---|---|---|
+| `og:title` | 60 characters | Concise version of the page title |
+| `og:description` | 200 characters | Slightly longer than meta description, conversational |
+| `og:image` | -- | 1200x630 pixels recommended, must be absolute URL |
+| `og:type` | -- | `article` for blog/docs, `website` for landing pages |
+
+### 6.2 Twitter Card
+
+- Use `summary_large_image` for content with strong visual elements.
+- Use `summary` for text-focused content.
+- Twitter title and description may differ from OG -- optimize for each platform.
+
+### 6.3 Fallback
+
+- If OG-specific fields are absent, the system uses the standard title and description.
+- Ensure the standard title and description are suitable for social sharing.
+
+---
+
+## 7. Internal Linking
+
+### 7.1 Relation Fields
+
+- Use Contentrain `relation` and `relations` model fields for cross-references between entries.
+- Prefer structured relations over hardcoded links in body content.
+- Structured relations are maintainable -- if a slug changes, relations still resolve.
+
+### 7.2 Bidirectional Relations
+
+- When Entry A references Entry B, check if Entry B should reference Entry A.
+- Example: if a blog post links to a product, the product's "related articles" should include that blog post.
+- The agent should suggest bidirectional relations but not create them without confirmation.
+
+### 7.3 Manual Links in Body Content
+
+- If the model does not have relation fields and links must be in body text, use relative paths.
+- Verify that linked entries exist before saving.
+- Do not link to draft or archived entries from published content.
+
+---
+
+## 8. URL and Canonical Rules
+
+### 8.1 Slug Patterns
+
+- All entries in a collection must follow the same slug pattern.
+- If existing entries use `verb-noun` format (e.g., `deploy-app`, `configure-server`), new entries must follow the same pattern.
+- Check existing entries before generating a slug for a new entry.
+
+### 8.2 Multi-Locale URLs
+
+- Same slug across all locales (see Section 3.4).
+- Locale prefix is handled by the frontend routing, not by the content slug.
+- Example: `/en/deploy-node` and `/tr/deploy-node` share the slug `deploy-node`.
+
+### 8.3 Trailing Slashes
+
+- The agent does not control trailing slash behavior -- this is a frontend routing concern.
+- Ensure slug values do not include leading or trailing slashes.
+
+---
+
+## Validation Checklist
+
+Before committing any content with SEO impact, verify:
+
+- [ ] Title is 50-60 characters, primary keyword near start, unique
+- [ ] Meta description is 120-155 characters, complete sentence, unique
+- [ ] Slug is lowercase, hyphenated, 3-5 words, no special characters
+- [ ] Published slugs have not been changed
+- [ ] Slugs are identical across all locales for the same entry
+- [ ] One H1 per page, sequential heading hierarchy
+- [ ] All images have descriptive alt text (max 125 chars) or empty string for decorative
+- [ ] OG fields populated if model supports them
+- [ ] Relation fields used for internal cross-references
+- [ ] No keyword stuffing in titles, descriptions, headings, or alt text

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
+```