@se-studio/project-build 1.0.104 → 1.0.105

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/project-build
 
+## 1.0.105
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
 ## 1.0.104
 
 ### Patch Changes

package/dist/management/sync-skills.d.ts

@@ -1,2 +1,4 @@
-export declare function syncSkills(targetDir?: string): Promise<void>;
+export declare function syncSkills(targetDir?: string, 
+/** When true, exits silently (code 0) if not running as an installed package. Safe for postinstall. */
+ifInstalled?: boolean): Promise<void>;
 //# sourceMappingURL=sync-skills.d.ts.map

package/dist/management/sync-skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-skills.d.ts","sourceRoot":"","sources":["../../src/management/sync-skills.ts"],"names":[],"mappings":"AAuBA,wBAAsB,UAAU,CAAC,SAAS,GAAE,MAAsB,iBA0BjE"}
+{"version":3,"file":"sync-skills.d.ts","sourceRoot":"","sources":["../../src/management/sync-skills.ts"],"names":[],"mappings":"AAmCA,wBAAsB,UAAU,CAC9B,SAAS,GAAE,MAAsB;AACjC,uGAAuG;AACvG,WAAW,UAAQ,iBAsCpB"}

package/dist/management/sync-skills.js

@@ -17,16 +17,37 @@ async function copyDir(src, dest) {
         }
     }
 }
-export async function syncSkills(targetDir = process.cwd()) {
+/**
+ * Returns true when this script is running from inside a pnpm/npm workspace
+ * (i.e. as a local package, not as an installed dependency from the registry).
+ *
+ * Detection: if the path to this file does NOT contain "node_modules" then we
+ * are running from the workspace source — syncing would overwrite the canonical
+ * skill files with the distributed copies, which is the wrong direction.
+ */
+function isWorkspacePackage() {
+    return !__dirname.includes('node_modules');
+}
+export async function syncSkills(targetDir = process.cwd(), 
+/** When true, exits silently (code 0) if not running as an installed package. Safe for postinstall. */
+ifInstalled = false) {
+    if (isWorkspacePackage()) {
+        if (ifInstalled) {
+            // Running inside the monorepo during a workspace install — skip silently.
+            return;
+        }
+        console.warn('Warning: seskills sync is running from a workspace package (not from node_modules).\n' +
+            'Skipping to avoid overwriting canonical skill files in the monorepo.\n' +
+            'Run `seskills sync` from an external project that has @se-studio/project-build installed.');
+        return;
+    }
     // Locate the skills directory relative to this file (dist/management/sync-skills.js)
-    // We want to go up to the package root and then into skills
-    // dist/management/ -> dist/ -> root -> skills
+    // dist/management/ -> dist/ -> package root -> skills/
     const packageRoot = path.resolve(__dirname, '..', '..');
     const skillsSourceDir = path.join(packageRoot, 'skills');
     const skillsTargetDir = path.join(targetDir, '.cursor', 'skills');
     console.log(`Syncing skills from ${skillsSourceDir} to ${skillsTargetDir}...`);
     try {
-        // Check if source exists
         try {
             await fs.promises.access(skillsSourceDir);
         }

package/dist/management/sync-skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync-skills.js","sourceRoot":"","sources":["../../src/management/sync-skills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAE3C,KAAK,UAAU,OAAO,CAAC,GAAW,EAAE,IAAY;IAC9C,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAExE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAE7C,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,YAAoB,OAAO,CAAC,GAAG,EAAE;IAChE,qFAAqF;IACrF,4DAA4D;IAC5D,8CAA8C;IAC9C,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACxD,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACzD,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAElE,OAAO,CAAC,GAAG,CAAC,uBAAuB,eAAe,OAAO,eAAe,KAAK,CAAC,CAAC;IAE/E,IAAI,CAAC;QACH,yBAAyB;QACzB,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,KAAK,CAAC,wCAAwC,eAAe,EAAE,CAAC,CAAC;YACzE,OAAO,CAAC,KAAK,CAAC,uEAAuE,CAAC,CAAC;YACvF,OAAO;QACT,CAAC;QAED,MAAM,OAAO,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAAC;QAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}
+{"version":3,"file":"sync-skills.js","sourceRoot":"","sources":["../../src/management/sync-skills.ts"],"names":[],"mappings":"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"}

package/dist/seskills.js

@@ -10,11 +10,18 @@ async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
     if (command === 'sync') {
-        const targetDir = args[1] || process.cwd();
-        await syncSkills(targetDir);
+        // Filter out flags from positional args
+        const positional = args.slice(1).filter((a) => !a.startsWith('--'));
+        const ifInstalled = args.includes('--if-installed');
+        const targetDir = positional[0] || process.cwd();
+        await syncSkills(targetDir, ifInstalled);
     }
     else {
-        console.log('Usage: seskills sync [target-dir]');
+        console.log('Usage: seskills sync [target-dir] [--if-installed]');
+        console.log('');
+        console.log('  --if-installed  Exit silently when running as a workspace package.');
+        console.log('                  Use this in a postinstall script so it only runs in');
+        console.log('                  external projects, not inside the monorepo.');
         process.exit(1);
     }
 }

package/dist/seskills.js.map

@@ -1 +1 @@
-{"version":3,"file":"seskills.js","sourceRoot":"","sources":["../src/seskills.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAC3C,MAAM,UAAU,CAAC,SAAS,CAAC,CAAC;IAC9B,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;QACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"seskills.js","sourceRoot":"","sources":["../src/seskills.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,wCAAwC;QACxC,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QACpE,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;QACpD,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QACjD,MAAM,UAAU,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC3C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,oDAAoD,CAAC,CAAC;QAClE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,sEAAsE,CAAC,CAAC;QACpF,OAAO,CAAC,GAAG,CAAC,uEAAuE,CAAC,CAAC;QACrF,OAAO,CAAC,GAAG,CAAC,+DAA+D,CAAC,CAAC;QAC7E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/project-build",
-  "version": "1.0.104",
+  "version": "1.0.105",
   "description": "Build tools and management scripts for SE Studio projects",
   "repository": {
     "type": "git",

package/skills/contentful-cms/generate-cms-guidelines/SKILL.md

@@ -0,0 +1,302 @@
+# Skill: Generate CMS Guidelines
+
+Use this skill when you need to generate, regenerate, or merge CMS guideline markdown fragments for any app in the monorepo.
+
+---
+
+## When to use this skill
+
+- **Full from scratch:** Generating guidelines for all components, collections, and externals in an app for the first time.
+- **Single type:** Regenerating the guideline for one component, collection, or external (e.g. after editing the component code).
+- **Merge only:** Rebuilding `COMPONENT_GUIDELINES_FOR_LLM.md` after manual edits to guideline fragments.
+- **Regenerate all:** Re-running everything after bulk code changes or prompt tweaks.
+
+---
+
+## Prerequisite: Showcase lifecycle
+
+Guidelines are only meaningful when the showcase is populated with realistic data. Complete these steps **before** running guideline generation for the first time:
+
+1. **Build the site** and ensure all content is correct and published in Contentful.
+2. **Generate showcase data:**
+   ```bash
+   pnpm --filter <appName> generate-showcase
+   ```
+   This writes `src/cms-showcase/showcase-examples.json` to the app.
+3. **Curate showcase mocks:** Follow the [curate-showcase-mocks skill](.cursor/skills/se-marketing-sites/curate-showcase-mocks/SKILL.md) to produce `showcase-mocks.json`.
+4. **Generate field list:**
+   ```bash
+   # From the app directory:
+   pnpm run cms-discovery:field-list
+   # Or from repo root:
+   pnpm --filter <appName> exec cms-generate-field-list --app-dir .
+   ```
+   This writes `generated/cms-discovery/field-list.json`.
+
+---
+
+## Inputs
+
+| Input | Description |
+|---|---|
+| **App directory** | Repo-relative path, e.g. `apps/example-om1` or `apps/example-se2026` |
+| **Mode** | `full` \| `single` \| `merge-only` |
+| **Type name** | Required for `single` mode — the exact type name from discovery, e.g. `"Hero"` or `"Cards Grid"` |
+| **Discovery URL** | URL to the live app's discovery endpoint, e.g. `http://localhost:3013/api/cms/discovery/` |
+
+**App ports** (app must be running for `full` and `single` modes):
+
+| App | Port | Discovery URL |
+|---|---|---|
+| example-brightline | 3010 | `http://localhost:3010/api/cms/discovery/` |
+| example-se2026 | 3012 | `http://localhost:3012/api/cms/discovery/` |
+| example-om1 | 3013 | `http://localhost:3013/api/cms/discovery/` |
+| example-empty | 3014 | `http://localhost:3014/api/cms/discovery/` |
+| example-brightlifekids | 3015 | `http://localhost:3015/api/cms/discovery/` |
+
+---
+
+## Mode: full
+
+Run all steps from scratch. Generates guidelines for all collections, externals, and components.
+
+### Step 1 — Verify prerequisites
+
+Confirm that:
+- The app is running (check `http://localhost:<port>/api/cms/discovery/` returns JSON).
+- `generated/cms-discovery/field-list.json` exists in the app directory.
+- Showcase has been generated (see Prerequisite section above).
+
+### Step 2 — Generate collections and externals
+
+Run the project-independent generator. It reads discovery, writes all `collections/*.md`, creates any missing `externals/*.md` templates, and updates `colour-hints.json`:
+
+```bash
+cms-generate-collection-guidelines \
+  --discovery-url <discoveryUrl> \
+  --app-dir <appDir>
+```
+
+**Overwrite behaviour:**
+- **Collections:** always overwritten (regenerated from discovery on each run).
+- **Externals:** created only if the file does not exist. Existing external files are preserved to protect hand-authored schema documentation.
+
+### Step 2b — Fill in external component schemas (first time only)
+
+For each external component file created in `docs/cms-guidelines/externals/`, open the file and fill in the **Fields & Schema** and **Usage** sections. These files are not regenerated once created, so the schema documentation you add here is permanent.
+
+For each external type:
+1. Check the Contentful content type schema (or ask the project owner) for the list of fields, their types, and purpose.
+2. Replace the `<!-- TODO: ... -->` block in `## Fields & Schema` with a filled-in Markdown table.
+3. Replace the `## Usage` placeholder with a short description of how to add and configure the component via `cms-edit`.
+4. Commit the completed files to version control.
+
+Example of a completed `## Fields & Schema` section:
+
+```markdown
+## Fields & Schema
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| externalComponentType | Symbol | Yes | Must be set to `ResearchChart` |
+| data | Object | No | Chart config payload — see project data-viz spec |
+| cmsLabel | Symbol | Yes | Internal label for CMS authoring |
+```
+
+### Step 3 — Generate component guidelines
+
+For each component in discovery order, run the full per-component pipeline defined in
+[`packages/contentful-cms/skills/cms-guidelines/generate-component-guidelines.md`](../../../packages/contentful-cms/skills/cms-guidelines/generate-component-guidelines.md).
+
+To find unfinished components:
+1. Fetch `<discoveryUrl>` and collect all `components[].name` values.
+2. Compute slug for each: `name.toLowerCase().replace(/\s+/g, '-').replace(/[()]/g, '')`.
+3. Check which slugs lack a corresponding file in `<appDir>/docs/cms-guidelines/components/<slug>.md`.
+4. Process only the unfinished ones (or all, if regenerating).
+
+**For each unfinished component** (process in batches of 5 if preferred):
+
+Run a Cursor subagent with this prompt, substituting `<COMPONENT_TYPE>` and `<APP_DIR>`:
+
+```
+Run the full guideline generation pipeline for <COMPONENT_TYPE>.
+Target app: <APP_DIR> (all paths relative to repo root / that directory).
+
+Read these pipeline docs first (they are in packages/contentful-cms/skills/cms-guidelines/):
+- generate-component-guidelines.md  (overall pipeline)
+- variant-loop.md                   (Phase A: variant loop)
+- generation-prompt.md              (Phase B: generation)
+- colour-hint-prompt.md             (Phase C: colour hint)
+- validation-prompt.md              (Phase D: validation)
+
+=== Phase A: Variant loop ===
+Follow variant-loop.md.
+1. Read src/project/components/<TypeName>.tsx (or collections/<TypeName>.tsx).
+2. Read generated/cms-discovery/field-list.json for field metadata.
+3. Propose 5 variants using variant-proposal-prompt.md.
+4. Capture screenshots:
+   cms-capture-screenshots --variants /tmp/<type-slug>-variants.json --app-dir <APP_DIR>
+   This also updates docs/cms-guidelines/screenshots/index.json automatically.
+5. Evaluate screenshots using evaluation-prompt.md.
+   When done: save accepted list to generated/cms-discovery/accepted-variants/<type-slug>.json
+
+=== Phase B: Generate guideline ===
+Follow generation-prompt.md.
+1. Describe screenshots (Step 1 prompt).
+2. Extract behaviour from code (Step 2 prompt).
+3. Merge into guideline block (Step 3 prompt).
+   IMPORTANT: Read docs/cms-guidelines/screenshots/index.json and .contentful-cms.json first.
+   The guideline must include a ## Screenshots section with image links:
+     ![Default](<devBaseUrl>/cms/screenshot?file=<type-slug>-default.png)
+   Only include variants present in index.json. Use devBaseUrl from .contentful-cms.json.
+4. Save to docs/cms-guidelines/components/<type-slug>.md.
+
+=== Phase C: Colour hint ===
+Follow colour-hint-prompt.md.
+Run:
+  cms-update-colour-hints --app-dir <APP_DIR> \
+    --type "<COMPONENT_TYPE>" --hint "<hint>" --notes "<brief reason>"
+
+=== Phase D: Validate ===
+Follow validation-prompt.md. Apply fixes until APPROVED.
+
+Do NOT run merge yet — merge runs once after all components.
+```
+
+### Step 4 — Merge
+
+After all components are done, run merge:
+
+```bash
+cms-merge-guidelines --app-dir <appDir>
+```
+
+Or from the app directory: `pnpm run cms-guidelines:merge`
+
+### Step 5 — Commit (optional)
+
+```bash
+git add <appDir>/docs/cms-guidelines/ <appDir>/generated/cms-discovery/
+git commit -m "chore(<app>): generate all CMS guidelines"
+```
+
+---
+
+## Mode: single
+
+Regenerate the guideline for one type. Useful after editing a component's code.
+
+### Step 1 — Fetch discovery to determine type category
+
+```bash
+curl -sL '<discoveryUrl>' | node -e "
+  const data = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+  const name = '<TYPE_NAME>';
+  const inComponents = data.components.some(c => c.name === name);
+  const inCollections = data.collections.some(c => c.name === name);
+  const inExternals = data.externals.some(c => c.name === name);
+  console.log(inComponents ? 'component' : inCollections ? 'collection' : inExternals ? 'external' : 'not found');
+"
+```
+
+### Step 2a — If component
+
+Run the full per-component pipeline (Phases A–D) from the subagent prompt in Mode: full → Step 3, for just this one type.
+
+### Step 2b — If collection or external
+
+For a **collection:** re-run the generator — it always overwrites collection files:
+
+```bash
+cms-generate-collection-guidelines \
+  --discovery-url <discoveryUrl> \
+  --app-dir <appDir>
+```
+
+For an **external:** the generator will not overwrite an existing file. Edit `docs/cms-guidelines/externals/<slug>.md` directly, updating the `## Fields & Schema` and `## Usage` sections as needed. If you need to regenerate from the template (e.g. for a new external), delete the file first and re-run the generator, then fill in the schema sections.
+
+### Step 3 — Merge
+
+```bash
+cms-merge-guidelines --app-dir <appDir>
+```
+
+---
+
+## Mode: merge-only
+
+Use when guideline fragments have been edited manually or generated outside this skill.
+
+```bash
+cms-merge-guidelines --app-dir <appDir>
+```
+
+Or from the app directory: `pnpm run cms-guidelines:merge`
+
+This rebuilds `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md` from all existing `components/*.md`, `collections/*.md`, and `externals/*.md` fragments.
+
+---
+
+## Output files
+
+All produced under `<appDir>`:
+
+| File | Description |
+|---|---|
+| `docs/cms-guidelines/components/<slug>.md` | Per-component guideline fragment (includes screenshot links) |
+| `docs/cms-guidelines/collections/<slug>.md` | Per-collection guideline fragment |
+| `docs/cms-guidelines/externals/<slug>.md` | Per-external guideline fragment |
+| `docs/cms-guidelines/screenshots/index.json` | Index of all captured screenshots (type, variant, file, date) |
+| `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md` | Merged full document (includes screenshot links) |
+| `generated/cms-discovery/accepted-variants/<slug>.json` | Accepted variant list (components only) |
+| `generated/cms-discovery/colour-hints.json` | Colour application hints for all types |
+
+### Screenshot links in guidelines
+
+Each component guideline contains a `## Screenshots` section with image links:
+
+```markdown
+## Screenshots
+
+| Variant | Preview |
+|---------|---------|
+| Default | ![Default](http://localhost:3010/cms/screenshot?file=hero-default.png) |
+| Navy    | ![Navy](http://localhost:3010/cms/screenshot?file=hero-navy.png) |
+```
+
+These links:
+- Resolve when the dev server is running (the `/cms/screenshot` route serves the PNG files)
+- Use the `devBaseUrl` from `.contentful-cms.json` for the host
+- Work for both human reviewers browsing the guidelines and AI assistants reading the markdown
+- Are preserved in `COMPONENT_GUIDELINES_FOR_LLM.md` when `cms-merge-guidelines` runs
+
+---
+
+## Pipeline reference
+
+All per-component pipeline docs live in `packages/contentful-cms/skills/cms-guidelines/`:
+
+| File | Purpose |
+|---|---|
+| `generate-component-guidelines.md` | Full pipeline overview (Phases A–F) |
+| `variant-loop.md` | Phase A: propose → screenshot → evaluate |
+| `variant-proposal-prompt.md` | LLM prompt for proposing variants |
+| `evaluation-prompt.md` | LLM prompt for evaluating screenshots |
+| `generation-prompt.md` | Phase B: three-step guideline generation |
+| `colour-hint-prompt.md` | Phase C: derive colour application hint |
+| `validation-prompt.md` | Phase D: 9-check validation |
+
+---
+
+## New CLI reference
+
+```
+cms-generate-collection-guidelines --discovery-url <url> --app-dir <path>
+```
+
+| Flag | Description |
+|---|---|
+| `--discovery-url <url>` | Discovery API URL (required). App must be running. |
+| `--app-dir <path>` | App directory (default: cwd). |
+
+Writes `docs/cms-guidelines/collections/*.md`, `docs/cms-guidelines/externals/*.md`, and updates `generated/cms-discovery/colour-hints.json`. Project-independent: works for any app in the monorepo.

package/skills/se-marketing-sites/curate-showcase-mocks/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: curate-showcase-mocks
+description: Extracts real component/collection data from Contentful and curates the best examples into showcase-mocks.json, making the CMS showcase display realistic content instead of generic placeholder text.
+license: Private
+metadata:
+  author: se-core-product
+  version: "2.0.0"
+---
+
+# Curate Showcase Mocks
+
+This skill refreshes the CMS showcase with realistic content from the live Contentful space.
+It uses a **two-phase CLI pipeline** — extraction followed by LLM-driven curation — to produce
+`src/generated/showcase-mocks.json`, which the showcase loads at runtime.
+
+## When to use
+
+Run this skill when:
+- A new app has been populated in Contentful and the showcase still shows placeholder text
+- The CMS content has been significantly updated and the showcase looks stale
+- New component or collection types have been added and need good mock data
+
+## Prerequisites
+
+- The app's `.env.local` must contain `CONTENTFUL_SPACE_ID`, `CONTENTFUL_ACCESS_TOKEN`, and `CONTENTFUL_ENVIRONMENT_NAME`
+- An LLM API key in `.env.local`: `OPENAI_API_KEY` (preferred) or `ANTHROPIC_API_KEY`
+- Optional: `CONTENTFUL_PREVIEW_ACCESS_TOKEN` to also include draft/unpublished entries
+- For monorepo apps: all packages must be built (`pnpm build` from repo root)
+- The app must be fully set up (see **First-time setup** below if not yet done)
+
+## First-time setup (new apps)
+
+Before running this skill on a new app, four one-time changes are required.
+
+### 1 — Add scripts to `package.json`
+
+**Monorepo app** (uses local packages via relative paths):
+
+```json
+"generate-showcase": "node ../../packages/project-build/dist/generate-showcase-data.js",
+"generate-showcase-mocks": "node ../../packages/project-build/dist/generate-showcase-mocks.js"
+```
+
+**External/standalone project** (uses npm-installed packages):
+
+```json
+"generate-showcase": "node node_modules/@se-studio/project-build/dist/generate-showcase-data.js",
+"generate-showcase-mocks": "node node_modules/@se-studio/project-build/dist/generate-showcase-mocks.js"
+```
+
+Alternatively for external projects, use the installed binaries directly (available on PATH after install):
+
+```bash
+generate-showcase-data       # runs in-place from the project root
+generate-showcase-mocks
+```
+
+### 2 — Gitignore the generated files
+
+In the app's `.gitignore`, add:
+
+```
+# Generated showcase files (large, regenerable — curated mocks committed separately)
+src/generated/showcase-examples.json
+src/generated/showcase-mocks-draft.json
+src/generated/cms-discovery/accepted-variants/
+```
+
+### 3 — Wire the render pages to use curated mocks
+
+Both `src/app/(cms-dev)/cms/showcase/render/page.tsx` and `render-all/page.tsx` need to import
+`mergeShowcaseMocks` and the curated mocks file.
+
+**`render/page.tsx`** — change from:
+
+```tsx
+import { DEFAULT_SHOWCASE_CONTROL_STATE, ShowcaseRenderPage } from '@se-studio/core-ui';
+// ... other imports ...
+
+export default async function Page(...) {
+  return (
+    <ShowcaseRenderPage
+      componentMockMap={componentMockMap}
+      collectionMockMap={collectionMockMap}
+      collectionCardMockMap={collectionCardMockMap}
+      ...
+    />
+  );
+}
+```
+
+to:
+
+```tsx
+import { DEFAULT_SHOWCASE_CONTROL_STATE, ShowcaseRenderPage, mergeShowcaseMocks } from '@se-studio/core-ui';
+// ... other imports ...
+import curatedMocks from '@/generated/showcase-mocks.json';
+
+const { componentMockMap: mergedComponentMocks, collectionMockMap: mergedCollectionMocks, collectionCardMockMap: mergedCardMocks } =
+  mergeShowcaseMocks(curatedMocks, { componentMockMap, collectionMockMap, collectionCardMockMap });
+
+export default async function Page(...) {
+  return (
+    <ShowcaseRenderPage
+      componentMockMap={mergedComponentMocks}
+      collectionMockMap={mergedCollectionMocks}
+      collectionCardMockMap={mergedCardMocks}
+      ...
+    />
+  );
+}
+```
+
+Apply the same pattern to **`render-all/page.tsx`**.
+
+### 4 — Create an empty `showcase-mocks.json` stub
+
+Create `src/generated/showcase-mocks.json` so the import compiles before curated data exists:
+
+```json
+{
+  "curatedAt": "2026-01-01T00:00:00.000Z",
+  "components": {},
+  "collections": {}
+}
+```
+
+Once these four steps are done, proceed with the steps below.
+
+---
+
+## Pipeline Overview
+
+The workflow is now a **three-step pipeline**:
+
+```
+Step 1: generate-showcase-data   → showcase-examples.json  (all CMS data, sorted by completeness)
+Step 2: generate-showcase-mocks  → showcase-mocks-draft.json  (LLM selects best + proposes variants)
+Step 3: AI review (this skill)   → showcase-mocks.json  (final curated mocks, committed)
+```
+
+Steps 1 and 2 are automated CLI commands. Step 3 is where you (the AI) review the draft,
+adjust anything the LLM got wrong, handle layout variants, and write the final committed file.
+
+---
+
+## Steps
+
+### Step 1 — Run the extraction script
+
+Run the CLI to fetch all component/collection entries from Contentful:
+
+**Monorepo:**
+```bash
+pnpm --filter {appName} generate-showcase
+```
+
+**External project (from project root):**
+```bash
+node node_modules/@se-studio/project-build/dist/generate-showcase-data.js
+```
+
+**Optional flags:**
+- `--include-drafts` — also fetches draft/unpublished entries via the Preview API (requires `CONTENTFUL_PREVIEW_ACCESS_TOKEN`)
+- `--all-types` — fetches all entry content types without a filter (instead of fetching component and collection separately)
+
+This writes `src/generated/showcase-examples.json` — every example grouped by type, sorted by
+`fieldCompleteness` descending. This file is gitignored.
+
+### Step 2 — Run the LLM curation script
+
+**Monorepo:**
+```bash
+pnpm --filter {appName} generate-showcase-mocks
+```
+
+**External project:**
+```bash
+node node_modules/@se-studio/project-build/dist/generate-showcase-mocks.js
+```
+
+This reads `showcase-examples.json`, calls the LLM (OpenAI or Anthropic — auto-detected from
+`.env.local`), and produces:
+- `src/generated/showcase-mocks-draft.json` — best mock per type + proposed variant param sets
+- `src/generated/cms-discovery/accepted-variants/<slug>.json` — per-type variant files
+
+**Optional flags:**
+- `--model <model>` — override the LLM model (e.g. `--model gpt-4o`)
+- `--types <Type1,Type2>` — limit to specific type names (comma-separated, useful for re-running single types)
+
+### Step 3 — Read the draft and registrations
+
+Read these files:
+
+1. `src/generated/showcase-mocks-draft.json` — the LLM's selected mocks + variant proposals
+2. `src/lib/registrations.ts` — the app's component/collection registrations
+
+From the registrations file, collect:
+- The full list of registered component type names
+- The full list of registered collection type names
+- Any registrations with `showcaseExclude: true` — these types must be skipped entirely
+
+Check the draft against the registrations: are there registered types missing from the draft?
+If so, check `showcase-examples.json` directly to find examples for those types.
+
+### Step 4 — Review and refine mocks
+
+For each type in the draft:
+
+**Validate the LLM selection:**
+- Confirm the selected mock has a real heading (not a test entry)
+- Confirm it has a working visual URL (if the field exists)
+- Confirm the mock fields are complete and reflect real brand content
+
+**Add layout variants not in the CMS:**
+Some types have meaningful variants that may not exist as separate CMS entries — a flipped
+layout, a narrow/wide version, or a no-visual state. These can be represented by adjusting
+the base mock with URL param overrides. Review each type's variant proposals from the LLM
+(in `showcase-mocks-draft.json`) and add any important ones that are missing:
+
+- For a Hero with a left-layout variant: add a variant with `{ "showcaseParams": { "flip": "true" } }` or similar
+- For a content block with a narrow option: `{ "showcaseParams": { "width": "narrow" } }`
+- Adjust the LLM's proposed params to match the actual param names used in the component's showcase controls
+
+**For collections — curating cards:**
+- Select ALL cards from the best example (do not cap — use the real count)
+- If fewer than 4 cards, check the next-best example for additional cards
+- Cards with no heading and no body are useless — skip them
+
+### Step 5 — Write showcase-mocks.json
+
+Write the curated data to `src/generated/showcase-mocks.json`. This file IS committed to git.
+
+Use the LLM draft as the starting point and apply your corrections from Step 4.
+
+**Format:**
+
+```json
+{
+  "curatedAt": "2026-02-28T14:00:00.000Z",
+  "components": {
+    "Hero": {
+      "heading": "Mental health care for kids and teens. Parenting support for you.",
+      "preHeading": "Brightline",
+      "body": { "json": { "nodeType": "document", "content": [...] } },
+      "visual": { "width": 1200, "height": 800, "url": "https://images.ctfassets.net/..." },
+      "backgroundColour": "Off White"
+    }
+  },
+  "collections": {
+    "FAQ": {
+      "mock": { "heading": "Top FAQs" },
+      "cards": [
+        { "heading": "Who is Brightline?", "body": { "json": { ... } } }
+      ]
+    }
+  }
+}
+```
+
+**Rules for the output:**
+- Set `curatedAt` to the current ISO timestamp
+- Only include types that have real CMS data
+- For component mocks: include only fields present in the source data
+- For collection mocks: always include `mock` and `cards`
+- Rich Text body fields must be `{ "json": <Document> }` — copy as-is
+- Visual fields must include `width`, `height`, AND `url` — never strip `url`
+- Include `widthPercent` when present on media/externalVideo entries
+- Include `otherMedia` when present — copy the full array including `url` and `widthPercent`
+- Do NOT invent or modify content — use the real data from the examples file
+- Include `backgroundColour` and `textColour` where the source has them
+- For cards: include ALL fields present in source, including `backgroundColour`, `textColour`, `links`
+
+### Step 6 — Verify
+
+After writing, briefly confirm:
+- The file is valid JSON
+- Component and collection counts look reasonable (non-zero)
+- Key types (Hero, main collections) have entries
+- Visual fields include `url` properties
+
+---
+
+## Output files
+
+| File | Location | Committed |
+|------|----------|-----------|
+| `showcase-examples.json` | `src/generated/showcase-examples.json` | No (gitignored) |
+| `showcase-mocks-draft.json` | `src/generated/showcase-mocks-draft.json` | No (gitignored) |
+| `accepted-variants/` | `src/generated/cms-discovery/accepted-variants/` | No (gitignored) |
+| `showcase-mocks.json` | `src/generated/showcase-mocks.json` | Yes |
+
+---
+
+## How the showcase uses this
+
+The showcase uses a **two-layer model**:
+
+1. **Base: mock data** — `showcase-mocks.json` is merged over inline registration mocks via
+   `mergeShowcaseMocks()` from `@se-studio/core-ui`. Curated data takes precedence; types without
+   curated data fall back to their inline `mock:` in the registration.
+
+2. **Patch: URL params** — Any control field in the URL (e.g. `?backgroundColour=Navy`) overrides
+   the mock. The control bar encodes only values that differ from the mock baseline.
+
+`?clean=true` skips mock data entirely and uses the default showcase control state only.
+
+---
+
+## External project setup (seskills)
+
+### Installing skills
+
+For standalone projects not in the monorepo, install or update skills via:
+
+```bash
+seskills sync
+```
+
+This copies all SE Studio cursor skills (including this one) into the project's `.cursor/skills/`
+directory. The `seskills` binary is provided by `@se-studio/project-build`.
+
+### Auto-sync on package update
+
+Add a `postinstall` script to the project's `package.json` so skills automatically sync
+whenever `pnpm install` is run (including after bumping `@se-studio/project-build`):
+
+```json
+"postinstall": "seskills sync --if-installed"
+```
+
+The `--if-installed` flag makes the sync a no-op if run inside the monorepo itself
+(where `project-build` is a workspace package, not an installed npm package), so it
+is safe to add to any project.
+
+### Script paths
+
+The CLI scripts are available as installed binaries after `npm install @se-studio/project-build`.
+Both `generate-showcase-data` and `generate-showcase-mocks` read `.env.local` from `process.cwd()`,
+so run them from the project root.