@contentrain/skills 0.1.2 → 0.2.1

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 |

package/skills/contentrain-init/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: contentrain-init
+description: "Initialize a new Contentrain project. Use when setting up .contentrain/ directory, configuring stack and locales, or scaffolding templates."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Initialize Contentrain in a Project
+
+> Set up Contentrain content infrastructure in an existing project.
+
+---
+
+## When to Use
+
+The user wants to add Contentrain to their project, or says something like "set up contentrain", "initialize contentrain", "add content management".
+
+---
+
+## Steps
+
+### 1. Detect the Tech Stack
+
+Read `package.json` to identify the framework:
+
+| Dependency | Stack |
+|---|---|
+| `nuxt` | Nuxt 3 |
+| `next` | Next.js |
+| `@astrojs/astro` or `astro` | Astro |
+| `@sveltejs/kit` | SvelteKit |
+
+If none match, treat as a generic Node.js project. Report the detected stack to the user before proceeding.
+
+### 2. Ask for Configuration
+
+Ask the user for:
+
+- **Supported locales:** Which languages will the project support? Default: `["en"]`. Use ISO 639-1 codes.
+- **Source locale:** Which locale is the primary/source locale? Default: `"en"`.
+- **Domain names:** Suggest domains based on the project structure (e.g., `marketing`, `blog`, `app`, `docs`). Ask the user to confirm or modify.
+
+### 3. Initialize the Project
+
+Call the MCP tool:
+
+```
+contentrain_init(stack: "<detected>", locales: ["en", ...], domains: ["marketing", ...])
+```
+
+This creates the `.contentrain/` directory structure, `config.json`, and initial `context.json`.
+
+### 4. Analyze Project Conventions
+
+After initialization, review the project for conventions to inform content creation:
+
+- **Tone:** Analyze existing copy in the project (README, landing page, UI text) to determine the appropriate tone (e.g., `professional`, `casual`, `technical`).
+- **Naming conventions:** Note any patterns in file naming, component naming, or content structure.
+
+> **Note:** Do NOT manually edit `context.json`. It is managed automatically by MCP tools and updated after every write operation.
+
+### 5. Suggest Initial Models
+
+Based on the project analysis, suggest models that would be useful:
+
+- If the project has a landing page: suggest `hero` (singleton), `features` (singleton or collection).
+- If the project has a blog section: suggest `blog-post` (document), `categories` (collection), `authors` (collection).
+- If the project has UI text: suggest `ui-labels` (dictionary), `error-messages` (dictionary).
+
+Present suggestions to the user and ask which to create. For selected models, call `contentrain_model_save` for each.
+
+### 6. Offer Scaffold Templates
+
+If the project matches a common pattern, offer to use a scaffold template:
+
+```
+contentrain_scaffold(template: "blog", locales: ["en"], with_sample_content: true)
+```
+
+Available templates: `blog`, `landing`, `docs`, `ecommerce`, `saas`, `i18n`, `mobile`.
+
+### 7. Set Up Agent Rules
+
+Copy the appropriate rules file to the project:
+
+- For Claude Code projects: append Contentrain rules to the project's `CLAUDE.md` or create a new section.
+- For Cursor projects: create or update `.cursorrules` with Contentrain conventions.
+
+Include a reference to the framework-specific guide (nuxt.md, next.md, astro.md, sveltekit.md).
+
+### 8. Final Summary
+
+Report to the user:
+
+- What was created in `.contentrain/`.
+- Which models were set up.
+- How to import content in their code (show the `#contentrain` import).
+- Next steps: create content, run `npx contentrain generate`, start the dev server.

package/skills/contentrain-model/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: contentrain-model
+description: "Design and save Contentrain model definitions. Use when creating models, updating schemas, adding fields, or changing model structure."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Design and Save Models
+
+> Create or evolve Contentrain model definitions safely.
+
+---
+
+## When to Use
+
+Use this when the user wants to:
+
+- add a new model
+- change fields on an existing model
+- choose between `singleton`, `collection`, `document`, and `dictionary`
+- define relations, locales, or custom content paths
+
+---
+
+## Steps
+
+### 1. Inspect Project State
+
+Call `contentrain_status` first:
+
+- confirm the project is initialized
+- see existing model IDs and domains
+- avoid creating duplicates
+
+If the user is extending an existing model, call `contentrain_describe(model: "<model-id>")`.
+
+### 2. Confirm Storage Contract
+
+Call `contentrain_describe_format` before proposing structure changes.
+
+Use it to confirm:
+
+- model kinds and storage expectations
+- locale behavior
+- document vs JSON model tradeoffs
+- how custom `content_path` and `locale_strategy` affect files
+
+### 3. Choose the Right Kind
+
+- `singleton`: one object per locale, e.g. hero, navigation, footer
+- `collection`: repeated entries with IDs, e.g. testimonials, faq items, authors
+- `document`: long-form markdown content with frontmatter, e.g. blog posts, docs pages
+- `dictionary`: flat key-value strings, e.g. UI labels, error messages
+
+Default rules:
+
+- use `dictionary` for UI/system strings
+- use `document` for markdown-heavy long-form content
+- use `collection` for repeated structured items
+- use `singleton` for one page/section config per locale
+
+### 4. Design Fields
+
+Follow these rules:
+
+- model IDs must be kebab-case
+- field names must be snake_case
+- relation fields must define a target `model`
+- prefer small, explicit schemas over large generic `object` blobs
+- only mark fields as `required` when the content truly cannot function without them
+
+Relation guidance:
+
+- `relation`: single reference
+- `relations`: multiple references
+- use `slug`-driven relations for document-like linking
+
+### 5. Decide i18n and Path Strategy
+
+Ask or infer:
+
+- should this model be localized?
+- should it use the default `.contentrain/content/...` path or a custom `content_path`?
+- if custom path is needed, which `locale_strategy` matches the project layout?
+
+Use custom paths only when the framework or repo structure clearly benefits from it.
+
+### 6. Present the Proposed Model
+
+Before writing, show:
+
+- model ID
+- kind
+- domain
+- `i18n` behavior
+- field list with types
+- relation targets
+- any custom `content_path` / `locale_strategy`
+
+Get user confirmation before saving.
+
+### 7. Save the Model
+
+Call `contentrain_model_save` with the approved definition.
+
+Example:
+
+```json
+{
+  "id": "hero",
+  "name": "Hero",
+  "kind": "singleton",
+  "domain": "marketing",
+  "i18n": true,
+  "fields": {
+    "title": { "type": "string", "required": true },
+    "subtitle": { "type": "text" },
+    "cta_label": { "type": "string" },
+    "featured_post": { "type": "relation", "model": "blog-post" }
+  }
+}
+```
+
+### 8. Validate Downstream Impact
+
+After changing a model:
+
+- review whether existing content now needs updates
+- call `contentrain_validate`
+- if the model is consumed by the SDK, recommend `contentrain generate`
+
+### 9. Final Summary
+
+Report:
+
+- model created or updated
+- kind and domain
+- field count
+- any relation targets
+- whether content migration is needed next

package/skills/contentrain-normalize/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: contentrain-normalize
+description: "Two-phase normalize flow: extract hardcoded strings from source code into .contentrain/ (Phase 1) and patch source files with content references (Phase 2). Use when normalizing, extracting content, or replacing hardcoded strings."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Contentrain Normalize
+
+Normalize converts a codebase with hardcoded strings into a Contentrain-managed content architecture. It runs in two independent phases, each producing a separate branch for review.
+
+- **Phase 1 (Extraction):** Pull content from source code into `.contentrain/` structure. Source files are NOT modified.
+- **Phase 2 (Reuse):** Patch source files to replace hardcoded strings with content references. Requires completed extraction.
+
+Phase 1 alone is valuable: content becomes manageable in Studio, translatable, and publishable without touching source code.
+
+---
+
+## Two-Phase Architecture
+
+| Aspect | Phase 1: Extraction | Phase 2: Reuse |
+|--------|-------------------|----------------|
+| Purpose | Pull content from source to `.contentrain/` | Patch source files with content references |
+| Scope | Full project scan | Per model or per domain |
+| Source files modified | No | Yes |
+| Branch pattern | `contentrain/normalize/extract/{domain}/{timestamp}` | `contentrain/normalize/reuse/{model}/{locale}/{timestamp}` |
+| Prerequisite | Initialized `.contentrain/` | Completed extraction (content exists in `.contentrain/`) |
+| Workflow mode | Always `review` | Always `review` |
+| Standalone value | Yes -- content is manageable in Studio immediately | Depends on Phase 1 |
+
+---
+
+## Agent vs MCP Responsibilities
+
+### Agent (Intelligence Layer)
+
+- **Decide what is content vs code.** Semantic judgment requiring context understanding.
+- **Assign domain grouping.** Determine which domain each piece of content belongs to.
+- **Determine model structure.** Group related content into models, choose the right kind.
+- **Create replacement expressions.** Stack-specific, requires framework knowledge (Vue/Nuxt, React/Next, Svelte, Astro, SDK).
+- **Filter false positives** from scan candidates.
+- **Evaluate and group** candidates into logical models.
+
+### MCP (Deterministic Infrastructure)
+
+- **Scan the file system** (build graph, find candidates).
+- **Read and write files** in `.contentrain/`.
+- **Patch source files** with exact string replacement (agent provides the replacement expression).
+- **Create branches, commit, validate** all changes.
+- **Enforce guardrails** (file limits, type restrictions, dry-run requirement).
+
+MCP is framework-agnostic. It does NOT know how `{t('key')}` differs from `{{ $t('key') }}`. The agent provides all stack-specific logic.
+
+---
+
+## Guardrails
+
+| Guardrail | Limit | Rationale |
+|-----------|-------|-----------|
+| Allowed source file types | `.vue`, `.tsx`, `.jsx`, `.ts`, `.js`, `.mjs`, `.astro`, `.svelte` | Only scan files that can contain UI content |
+| Max files per scan | 500 | Prevent scanning entire monorepos |
+| Max files per apply | 100 | Keep diffs reviewable |
+| Dry-run before apply | **MANDATORY** | Preview all changes before executing |
+| Workflow mode | Always `review` | Normalize changes are never auto-merged |
+| Reuse scope | Per model or per domain | No whole-project reuse in one operation |
+| Reuse prerequisite | Extraction must be complete | Content must exist in `.contentrain/` before patching source |
+
+Attempting to apply without a prior dry-run will be rejected. Exceeding file limits will truncate results with a warning.
+
+---
+
+## Phase 1: Extraction (Step-by-Step)
+
+### 1. Check Project State
+
+Call `contentrain_status` to confirm the project is initialized and note supported locales. Call `contentrain_describe_format` to understand the four storage formats (dictionary, collection, singleton, document) before deciding model structure.
+
+### 2. Build the Project Graph
+
+Call `contentrain_scan(mode: "graph")` to build the import/component dependency graph. Use this to understand which components belong to which pages, identify shared vs page-specific components, and prioritize files.
+
+### 3. Find Candidates
+
+Call `contentrain_scan(mode: "candidates")` to find hardcoded strings. The scan returns candidates with file paths, line numbers, string values, and surrounding context.
+
+### 4. Evaluate Candidates (Agent Intelligence)
+
+- **Filter false positives:** Remove CSS values, technical identifiers, import paths, variable names, config values, log messages, test strings. See [What Is Content](references/what-is-content.md) for full heuristics.
+- **Assign domains:** Group candidates by domain (e.g., `marketing`, `blog`, `ui`, `system`).
+- **Determine model types:** Choose dictionary, singleton, collection, or document kind for each group.
+- **Structure fields:** Define field names and assign candidate strings to fields.
+
+### 5. Preview Extraction
+
+Call `contentrain_apply(mode: "extract", dry_run: true)` to generate a preview. Review the dry-run output: verify model definitions, content assignments, and check for missed or misclassified candidates. Show the preview to the user.
+
+### 6. Execute Extraction
+
+After user approval, call `contentrain_apply(mode: "extract", dry_run: false)`. This creates model definitions and content files in `.contentrain/` on a `contentrain/normalize/extract/{timestamp}` branch. Source files are NOT modified.
+
+### 7. Validate and Submit
+
+Call `contentrain_validate` to check schema compliance, i18n completeness, and duplicate entries. Call `contentrain_submit` to push the branch for review. Normalize operations always use `review` workflow mode.
+
+Tell the user: "Phase 1 complete. Content is now in Contentrain and can be managed, translated, and published from Studio. When ready, proceed with Phase 2 to update source files."
+
+---
+
+## Phase 2: Reuse (Step-by-Step)
+
+Only start after Phase 1 is reviewed and merged.
+
+### 1. Select Scope
+
+List the extracted models and ask the user which model or domain to process first. Process one model or domain at a time to keep diffs small and reviewable.
+
+### 2. Determine Replacement Expressions (Agent Intelligence)
+
+Based on the project's tech stack, determine the correct replacement pattern. See [Reuse Details](references/reuse.md) for the full replacement expressions table by stack. Also determine any necessary import statements for patched files.
+
+### 3. Preview Reuse
+
+Call `contentrain_apply(mode: "reuse", scope: { model: "<model-id>" }, patches: [...], dry_run: true)`. Review: verify each replacement is correct, import statements will be added, no non-content strings are being replaced, component structure is preserved.
+
+### 4. Execute Reuse
+
+After user confirmation, call `contentrain_apply(mode: "reuse", scope: { model: "<model-id>" }, patches: [...], dry_run: false)`. This patches source files and creates a `contentrain/normalize/reuse/{model}/{timestamp}` branch.
+
+### 5. Validate and Submit
+
+Call `contentrain_validate` to verify source files parse correctly, content references resolve, and no strings were missed or double-replaced. Call `contentrain_submit` to push the branch for review.
+
+### 6. Repeat
+
+Ask the user which model or domain to process next. Repeat steps 1-5 for each remaining model until all extracted content is referenced in source code.
+
+---
+
+## Domain and Model Grouping Guidelines
+
+### Domain Assignment
+
+| Content Location | Suggested Domain |
+|------------------|-----------------|
+| Landing page, marketing sections | `marketing` |
+| Blog, articles, posts | `blog` |
+| Navigation, footer, header | `ui` |
+| Error messages, validation | `system` |
+| Product pages, e-commerce | `product` |
+| Documentation, help | `docs` |
+| User-facing app strings | `app` |
+
+### Model Kind Selection
+
+| Content Pattern | Kind | Rationale |
+|----------------|------|-----------|
+| One set of fields per page section | `singleton` | Hero, features, pricing header |
+| Multiple items of same type | `collection` | Team members, FAQs, testimonials |
+| Long-form with metadata | `document` | Blog posts, documentation pages |
+| Key-value UI strings | `dictionary` | Error messages, button labels, form labels |
+
+---
+
+## Common Mistakes
+
+| Mistake | Correct Approach |
+|---------|-----------------|
+| Extracting CSS values as content | Only extract user-visible text |
+| Creating one model per component | Group related content into shared models |
+| Skipping dry-run | ALWAYS preview before apply |
+| Auto-merging normalize changes | Normalize ALWAYS uses review mode |
+| Reusing before extraction is merged | Wait for extraction review and merge first |
+| Processing all models in one reuse | Scope reuse to one model/domain at a time |
+| Ignoring project graph | Use graph output to understand component relationships |
+| Hardcoding replacement patterns | Detect the project's i18n stack and use its conventions |
+| Extracting strings with runtime variables | Split parameterized strings: extract the static part, leave interpolation in code |
+
+---
+
+## References
+
+- [Extraction Details](references/extraction.md) -- Phase 1 extraction rules, parameters, and examples
+- [Reuse Details](references/reuse.md) -- Phase 2 replacement expressions by stack and patching rules
+- [What Is Content](references/what-is-content.md) -- Heuristics for identifying content vs code strings