@se-studio/skills 1.0.1

package/skills/se-marketing-sites-handling-media/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: handling-media
+description: Guide for using images, videos, and animations in marketing sites using the ResponsiveVisual and VisualComponent systems.
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.0.0"
+---
+
+# Handling Media
+
+This project uses a unified media system to handle images, videos, and animations efficiently.
+
+## Core Components
+
+### 1. `ResponsiveVisual` (or `VisualComponent`)
+
+This is the main component for rendering media from Contentful. It handles:
+*   Responsive image sources (desktop/mobile).
+*   Format optimization (WebP/AVIF).
+*   Video auto-play/looping.
+*   Lottie animations.
+*   Lazy loading & Priority hints.
+
+```typescript
+import VisualComponent from '@/framework/VisualComponent';
+// or
+import { Visual } from '@se-studio/core-ui';
+```
+
+## Usage Pattern
+
+### Basic Usage
+
+```typescript
+<VisualComponent
+  visual={field.visual}
+  className="w-full h-auto"
+/>
+```
+
+### Responsive Sizing (`visualSizes`)
+
+You **MUST** provide `visualSizes` to ensure the browser loads the correct image size. This uses the `sizes` attribute.
+
+```typescript
+import { calculateVisualSizes } from '@se-studio/core-ui';
+
+// Example: Full width on mobile, 50% width on laptop
+const sizes = calculateVisualSizes(1, { laptop: 0.5 });
+
+<VisualComponent
+  visual={visual}
+  visualSizes={sizes}
+/>
+```
+
+*   `1`: 100vw (Mobile default)
+*   `laptop: 0.5`: 50vw (Laptop breakpoint)
+
+### visualSizes Must Mirror Col-Span
+
+`visualSizes` **must** match the visual's layout (col-span, container width). The browser uses these values to pick the right image size.
+
+*   **Rule**: `col-span-N` in a 12-col grid → use `N/12` (e.g. 6 cols → 0.5, 5 cols → 5/12).
+*   **Full width** (`col-span-full`) → use `1`.
+*   **First arg** = mobile/default; breakpoint keys (`laptop`, `tablet`, `desktop`) = that breakpoint.
+*   **Common mistake**: Reversing mobile vs laptop. If mobile is full width and laptop is smaller, use `(1, { laptop: 0.5 })`, **not** `(0.5, { laptop: 1 })`.
+*   **Fixed-size icons** (~96–128px): use small ratios like `0.2`–`0.25`; **never** use values > 1 (e.g. `(100)` is invalid and causes massive over-fetch).
+*   **Example table**:
+
+| Layout | visualSizes |
+|--------|-------------|
+| Full width | `(1)` |
+| 6 cols on laptop, full on mobile | `(1, { laptop: 0.5 })` |
+| 5 cols on laptop, full on mobile | `(1, { laptop: 5/12 })` |
+| 2 cols in 12 on laptop, half on mobile | `(0.5, { laptop: 2/12 })` |
+| Small icon (~96px) | `(0.25)` |
+
+### CMS Width & Position (`widthPercent`, `horizontalPosition`)
+
+Visuals in Contentful can have a `widthPercent` (e.g. 50%) and `horizontalPosition` (Left / Middle / Right). These control how wide the visual renders on laptop+ and where it aligns within its container. **How these fields are applied depends on the component rendering the visual.**
+
+**Key principle**: The `Visual` component is a "fill my container" renderer — it does **not** apply width constraints itself. Width and position are always the responsibility of the wrapping component.
+
+#### Which components handle it automatically
+
+*   **`VisualComponent`** (framework, `@/framework/VisualComponent`): Handles `widthPercent` and `horizontalPosition` in both embedded and non-embedded modes. Also adjusts `visualSizes` so the browser fetches an appropriately sized image.
+*   **`ResponsiveVisual`** (core-ui): Wraps the `Visual` in a div that applies `--image-width` and horizontal positioning. Components using `ResponsiveVisual` get this for free.
+
+#### Custom components using `Visual` directly
+
+If your component renders `Visual` directly and the visual may have a `widthPercent`, you must handle it yourself:
+
+1.  **Wrap in a positioning div** using helpers from `core-ui`:
+
+```typescript
+import { getVisualWidthPercent } from '@se-studio/core-data-types';
+import {
+  calculateHorizontalPositionClassName,
+  calculateImageWidthStyleVariable,
+  calculateVisualSizes,
+  Visual,
+  cn,
+} from '@se-studio/core-ui';
+
+const imageWidthStyle = calculateImageWidthStyleVariable(visual);
+const imageHorizontalPosition = imageWidthStyle
+  ? calculateHorizontalPositionClassName(visual)
+  : undefined;
+
+<div
+  className={cn(
+    'w-full',
+    imageHorizontalPosition,
+    imageWidthStyle && 'laptop:w-(--image-width)',
+  )}
+  style={imageWidthStyle}
+>
+  <Visual visual={visual} visualSizes={visualSizes} />
+</div>
+```
+
+2.  **Factor width into `visualSizes`** so the browser doesn't over-fetch:
+
+```typescript
+const widthPercent = getVisualWidthPercent(visual);
+const laptopRatio = widthPercent ? widthPercent / 100 : undefined;
+const visualSizes = laptopRatio
+  ? calculateVisualSizes(1, { laptop: laptopRatio })
+  : calculateVisualSizes(1);
+```
+
+#### Collections with multiple visuals
+
+Collections like `SeparatedVisualsCollection` may interpret `widthPercent` differently — as relative proportions between visuals rather than absolute percentages. The collection controls the layout and passes the computed slot width to `visualSizes`. Don't apply the standard wrapper pattern blindly in collections; match `visualSizes` to the actual rendered slot width.
+
+### LCP Optimization (`calculateImagePriority`)
+
+For the Hero component (or whatever is at the top of the page), you must prioritize the image load to improve LCP (Largest Contentful Paint).
+
+Use `calculateImagePriority(index)` where `index` is the component's position on the page.
+
+```typescript
+import { calculateImagePriority } from '@se-studio/core-ui';
+
+<VisualComponent
+  visual={visual}
+  {...calculateImagePriority(index)}
+/>
+```
+
+If `index` is `0`, this sets `priority={true}` (or `fetchPriority="high"`). If `index > 0`, it defaults to lazy loading.
+
+### Analytics Tracking
+
+Pass `componentLabel` (usually `cmsLabel`) and `analyticsContext` to enable click tracking on media elements (if they are linked).
+
+```typescript
+<VisualComponent
+  visual={visual}
+  componentLabel={cmsLabel}
+  analyticsContext={contentContext.analyticsContext}
+/>
+```
+
+## Media Types
+
+The `IResponsiveVisual` type (from `@se-studio/core-data-types`) supports:
+
+1.  **Image**: Standard Contentful image asset.
+2.  **Video**: Hosted video file (mp4/webm). The component handles `<video>` tag rendering with autoplay/loop/muted attributes suitable for background videos.
+3.  **Animation**: Lottie JSON file. Renders using a Lottie player.
+
+The component automatically detects the type and renders the appropriate element.
+
+## Mobile Specific Visuals
+
+Contentful models often support a separate `mobileVisual` field. The `VisualComponent` handles switching between them using `<picture>` tags or CSS media queries internally.
+
+You typically pass the combined object or handle it via props if the component exposes both:
+
+```typescript
+// If your component merges them into one responsive object before rendering:
+<VisualComponent visual={combinedVisual} />
+```
+
+Or if using raw fields:
+
+```typescript
+<VisualComponent
+  visual={visual}
+  mobileVisual={mobileVisual}
+/>
+```

package/skills/se-marketing-sites-lib-cms-structure/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: lib-cms-structure
+description: Guide for the lib directory structure in SE Core Product CMS apps. Use when setting up lib/, migrating from contentful-config, or adding new CMS configuration.
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.0.0"
+---
+
+# Lib Directory Structure
+
+Reference apps: **example-se2026**, **example-brightline**, **example-om1**.
+
+## File Responsibilities
+
+| File | Client-safe? | Purpose |
+|------|--------------|---------|
+| `cms.ts` | Yes | Types, buildComponentRecord / buildCollectionRecord / buildExternalRecord (array → Record), then build*Maps from those Records, createConverterContext |
+| `cms-server.ts` | No (server-only) | createAppHelpers, buildOptions, getContentfulConfig, projectRendererConfig |
+| `config.ts` | Yes | isProduction, isDevelopment |
+| `server-config.ts` | No | draftOnly, videoPrefix, baseUrl, revalidationSecret |
+| `constants.ts` | Yes | ARTICLES_BASE, TAGS_BASE, PEOPLE_BASE, enable flags, customer name |
+| `registrations.ts` | Yes | componentRegistrationsList, collectionRegistrationsList, externalComponentRegistrationsList (arrays) |
+| `SizingInformation.ts` | Yes | getSizingInformation for dynamic heading sizes |
+
+## Server vs Client Boundary
+
+- **cms-server.ts** has `import 'server-only'`. Never import it in `'use client'` components.
+- **cms.ts** is client-safe: types, maps, converter context factory (no env access).
+- **registrations.ts** imports from cms.ts and project components; keep it client-safe.
+
+## constants.ts Shape
+
+```typescript
+export const ARTICLES_SLUG = 'articles';  // or 'learning-hub'
+export const TAGS_SLUG = 'tags';
+export const PEOPLE_SLUG = 'people';
+export const DEFAULT_TOPIC = 'other';
+
+export const ARTICLES_BASE = `/${ARTICLES_SLUG}`;
+export const TAGS_BASE = `/${TAGS_SLUG}`;
+export const PEOPLE_BASE = `/${PEOPLE_SLUG}`;
+
+export const customerName = '...';
+export const applicationName = '...';
+export const siteTitle = '...';
+export const siteDescription = '...';
+export const enablePerson = false;
+export const enablePeopleIndex = false;
+export const enableTag = false;
+export const enableTagsIndex = false;
+```
+
+## Data Flow
+
+```
+registrations.ts (*RegistrationsList arrays)
+       →  cms.ts (build*Record from arrays, then build*Maps)
+       →  builds maps  →  cms-server.ts
+                                ↓
+                      projectRendererConfig
+```
+
+Add new components/collections to the appropriate *RegistrationsList array in `registrations.ts`. The `cms.ts` imports those arrays, builds Records via `buildComponentRecord` / `buildCollectionRecord` / `buildExternalRecord` (which enforce that every CMS type has a registration), then builds the maps used by `cms-server.ts`.
+
+## Circular Dependency: Do Not Import cms-server in Components/Collections
+
+Components and collections in the registration chain (imported by `registrations.ts`) must **not** import from `cms-server` directly. Doing so creates a circular dependency (cms-server → cms → registrations → components → cms-server) that causes TDZ errors during RSC serialization.
+
+**Instead**, use the helpers from `@se-studio/core-ui`:
+
+- `getPreviewFieldProps(rendererConfig, id, fieldId)` – for field preview props
+- `getPreviewResponsiveVisualFieldProps(rendererConfig, id, visualFieldId, mobileVisualFieldId)` – for responsive visuals
+- `rendererConfig.previewHelpers?.getPreviewParentProps?.(information)`
+- `rendererConfig.fetchHelpers?.getAllArticleLinks?.()`
+- `rendererConfig.fetchHelpers?.getRelatedArticles?.(information, contentContext, count)`
+
+These are passed via `projectRendererConfig` in `cms-server.ts`. `Section` and `SectionLinks` accept `previewHelpers` / `rendererConfig` props. See `docs/SERVER_CLIENT_BOUNDARIES.md`.
+
+## See Also
+
+- **register-cms-features** – Adding components and collections
+- **cms-routes-and-appshared** – Route structure and appShared

package/skills/se-marketing-sites-register-cms-features/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: register-cms-features
+description: Guide for registering new components, collections, and external integrations in the CMS configuration (src/lib/registrations.ts).
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.0.0"
+---
+
+# Registering CMS Features
+
+The file `src/lib/registrations.ts` is where you add new components, collections, and external components. It exports three **arrays** (not Records): `componentRegistrationsList`, `collectionRegistrationsList`, `externalComponentRegistrationsList`. The **name is defined only in each registration** (in the `defineComponent` / `defineCollection` / `defineExternalComponent` call). The `cms.ts` module imports these arrays, uses `buildComponentRecord` / `buildCollectionRecord` / `buildExternalRecord` to build Records keyed by `name` (with exhaustiveness checks), then passes those Records to the core-ui build*Maps helpers. Add new registrations to the appropriate *List array in `registrations.ts`.
+
+## How Registration Works
+
+The system uses registration objects created via `defineComponent`, `defineCollection`, or `defineExternalComponent` (from `@/lib/define-cms`). Each object contains:
+1.  **Name**: Matches the Contentful content type ID exactly. Defined **once** in the registration (not as a Record key).
+2.  **Renderer**: The React component to render.
+3.  **Used Fields**: Which fields from the content model are used.
+4.  **Mock Data**: Sample data for the styleguide/showcase.
+
+## Registering a New Component
+
+1.  **Import the Registration**:
+    At the top of `src/lib/registrations.ts`, import your component's registration export.
+
+    ```typescript
+    import { MyNewComponentRegistration } from '@/project/components/MyNewComponent';
+    ```
+
+2.  **Add to `componentRegistrationsList`**:
+    Find the `componentRegistrationsList` array in `registrations.ts` and add your component.
+
+    ```typescript
+    export const componentRegistrationsList = [
+      HeroRegistration,
+      // ...
+      MyNewComponentRegistration, // Add this
+    ] as const;
+    ```
+
+    *Order does not matter for functionality, but logical grouping is helpful. Missing a CMS type causes a type error in `cms.ts` when `buildComponentRecord(componentRegistrationsList)` is called.*
+
+## Registering a New Collection
+
+1.  **Import the Registration** in `src/lib/registrations.ts`:
+
+    ```typescript
+    import { MyCollectionRegistration } from '@/project/collections/MyCollection';
+    ```
+
+2.  **Add to `collectionRegistrationsList`** in `registrations.ts`:
+
+    ```typescript
+    export const collectionRegistrationsList = [
+      CardGridRegistration,
+      // ...
+      MyCollectionRegistration, // Add this
+    ] as const;
+    ```
+
+## Adding External Components
+
+External components (like 3rd party forms or iframes) use a separate list in `src/lib/registrations.ts`.
+
+1.  **Import**:
+    ```typescript
+    import { MyExternalWidgetRegistration } from '@/project/externalComponents/MyExternalWidget';
+    ```
+
+2.  **Add to `externalComponentRegistrationsList`** in `registrations.ts`:
+    ```typescript
+    export const externalComponentRegistrationsList = [
+        ExternalIFrameRegistration,
+        MyExternalWidgetRegistration,
+    ] as const;
+    ```
+
+## Extending Type Definitions
+
+If you introduce new Color names, Button variants, or other enumerations, update the type definitions in `src/lib/cms.ts` (types are defined there; registrations live in `registrations.ts`):
+
+```typescript
+export type CmsColourName = NonNullable<TypeComponentFields['backgroundColour']>['values'];
+// Add or modify if types are not automatically generated from Contentful
+```
+
+**Note**: Most types are generated automatically into `@/generated/types` by the `type-gen` script. You typically don't need to manually edit types unless you are defining project-specific overrides.
+
+## The Showcase
+
+Registering a component automatically adds it to the CMS Showcase (usually available at `/cms/showcase` in development). This allows you to view the component in isolation using its mock data.
+
+*   Ensure your `mock` object in the registration is complete and realistic.
+*   The showcase helps verify that `usedFields` and `UnusedChecker` are working correctly.

package/skills/se-marketing-sites-styling-system/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: styling-system
+description: Reference guide for the marketing site styling system, including typography, colors, grids, and RTF classes.
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.1.0"
+---
+
+# Styling System
+
+This project uses a customized Tailwind CSS setup where the configuration is driven by `tailwind.config.json` in each app. This JSON file acts as the source of truth for design tokens, including colors, typography, spacing, and breakpoints.
+
+## Configuration Source
+
+The `tailwind.config.json` file in your app's root directory defines the following:
+
+*   **`colorOptions`**: Defines the project's color palette.
+*   **`fontTable`**: Defines typography styles, responsive scaling, and font families.
+*   **`sizes`**: Defines breakpoints, grid columns, gaps, and margins.
+
+These configurations are processed by the build system to generate utility classes and TypeScript helpers.
+
+## Typography
+
+Typography utility classes (e.g., `h1`, `h2`, `p1`, `p2`) are automatically generated from the `fontTable` in `tailwind.config.json`.
+
+### generated Utilities
+
+Classes are generated for each key in `fontTable.styles`. Common keys include:
+
+*   **Headings**: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`
+*   **Body**: `p1`, `p2`, `p3`, `p4`
+*   **Special**: `quote`, `button`, `nav`, etc. (varies by project)
+
+Styles are responsive and scale automatically based on the breakpoints defined in the config (e.g., `laptop`, `desktop`).
+
+### Best Practice: Dynamic Sizing
+
+Use `getSizingInformation(index)` from `@/lib/SizingInformation` to get **Element** (or **ChildElement** for items inside a collection) and typography classes. Use **Element** for the single main heading of the block; apply a class from `sizingInformation` (e.g. `sizingInformation.h1`). **preHeading** and **postHeading** must be rendered as **<p>** with typography classes (e.g. `sizingInformation.p`), not as heading elements.
+
+```typescript
+import { getSizingInformation } from '@/lib/SizingInformation';
+
+// Example usage in a component renderer
+const { Element, sizingInformation } = getSizingInformation(index);
+<Element className={sizingInformation.h1}>{title}</Element>
+```
+
+For embedded content (e.g. inside rich text), pass `embedded: true` as the second argument.
+
+## Colors
+
+Colors are defined in `colorOptions` within `tailwind.config.json`. The build system generates TypeScript helpers in `@/generated/colors` to access these colors safely.
+
+### Helper Functions
+
+1.  **`lookupColourString(colorName, property)`**:
+    Get a single class for a specific property.
+    ```typescript
+    // Returns "text-primary-blue" (if 'Primary Blue' exists in config)
+    lookupColourString('Primary Blue', 'text')
+    // Returns "bg-light-gray" (if 'Light Gray' exists in config)
+    lookupColourString('Light Gray', 'bg')
+    ```
+
+2.  **`lookupColourClassNames(bgColor, textColor)`**:
+    Get background AND text classes, handling automatic contrast if text color is omitted (based on `colorOpposites` in config).
+    ```typescript
+    // Returns "bg-primary-blue text-white" (if White is opposite of Primary Blue)
+    lookupColourClassNames('Primary Blue')
+    ```
+
+## Grid System
+
+The grid system is defined in the `sizes` object of `tailwind.config.json`. It specifies the number of columns, margins, and gaps for each breakpoint.
+
+### Standard Breakpoints
+
+While configurable, most projects use:
+*   `mobile`: Default (0px+)
+*   `tablet`: ~768px+
+*   `laptop`: ~1024px+
+*   `desktop`: ~1440px+
+
+### Layout Helpers
+
+Common layout patterns using Tailwind grid utilities:
+
+*   **Full Width**: `col-span-full`
+*   **Centered Content**: `col-span-full laptop:col-start-2 laptop:col-span-10` (assuming 12 columns on laptop)
+*   **Split 50/50**:
+    *   Left: `col-span-full laptop:col-span-6`
+    *   Right: `col-span-full laptop:col-span-6`
+
+## Rich Text (RTF) Classes
+
+Rich text styling is handled via custom utility classes defined in `src/app/globals.css`. These classes map raw HTML elements (from the CMS rich text field) to the project's typography utilities.
+
+Common conventions for RTF classes (check your specific `globals.css`):
+
+*   **`.rtf-standard` / `.content-rich-text`**: Default styling for body content.
+*   **`.rtf-legal`**: Styling for terms and conditions (often smaller text, decimal lists).
+*   **`.rtf-article`**: Editorial styling (often larger text, specific spacing).
+*   **`.rtf-core`**: Minimal styling reset.
+
+**Usage**:
+Wrap the `RtfOrString` component with the appropriate class:
+```tsx
+<div className="rtf-standard">
+  <RtfOrString data={richTextData} />
+</div>
+```
+
+## Global Styles
+
+Project-specific global styles, animations, and custom utility classes are located in `src/app/globals.css`. This file imports the generated Tailwind CSS and defines:
+
+*   Root variables (if any)
+*   Animation keyframes
+*   Custom component classes (e.g., `.btn-primary`)
+*   Rich Text Formatting classes

package/skills/site-workflows-brand-context-builder/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: "Brand Context Builder"
+description: "Interactively create or update a brand context skill for a customer's site by analysing their content and asking refinement questions."
+---
+
+# Brand Context Builder
+
+Create a brand context skill for a customer's website. This skill guides you through analysing the site, proposing a brand context, and refining it with the user.
+
+## When to Use
+
+- User wants to set up brand context for a new customer
+- User says "create brand context for [site]" or "set up [customer] brand context"
+- User wants to update an existing brand context
+
+## Workflow
+
+### Step 1: Gather Information
+
+Ask the user for:
+- **Site URL** (required) — e.g., "https://www.hopskipdrive.com"
+- **Customer name** (optional) — e.g., "HopSkipDrive" (can be inferred)
+
+### Step 2: Analyse the Site
+
+Call the `build_brand_context` tool with the site URL and customer name. This fetches the homepage and common pages via markdown routes and returns the content for analysis.
+
+If the tool returns no content, the site may not have markdown routes enabled. Ask the user if they can provide the site URL with markdown routes, or proceed with what they can tell you about the brand.
+
+### Step 3: Propose Brand Context
+
+Based on the site content returned by the tool, propose a complete brand context covering:
+
+1. **Customer name** — the brand name as they write it
+2. **Brand voice** — analyse the writing style (formal? casual? technical? warm?)
+3. **Target audience** — who is the site for? What are their needs?
+4. **Terminology** — brand-specific terms that should be used instead of generic words
+5. **Tone** — one-line description
+6. **SEO focus** — primary topics and keywords
+7. **Image context** — brand colours, common visual subjects and what they represent
+
+Present the proposed context as JSON to the user.
+
+### Step 4: Refine
+
+Ask the user these questions to refine the context:
+
+1. "Is the brand voice description accurate? Any adjustments?"
+2. "Are there brand-specific terms I missed? For example, do you have special names for your products, roles, or services?"
+3. "Are there visual elements in your imagery I should know about? (e.g., 'people in orange shirts are CareDrivers')"
+4. "Is the target audience description correct?"
+5. "Any SEO keywords or topics to add?"
+
+Incorporate their feedback into the context.
+
+### Step 5: Generate the Brand Context Skill
+
+Once the user is happy with the context, generate a brand context skill file:
+
+```markdown
+---
+name: "[CustomerName] Brand Context"
+description: "Brand voice, terminology, audience, and visual guidelines for [CustomerName] ([siteUrl])."
+---
+
+# Brand Context: [CustomerName]
+**Site:** [siteUrl]
+**Brand voice:** [brandVoice]
+**Target audience:** [targetAudience]
+**Tone:** [tone]
+**SEO focus:** [seoFocus]
+
+## Terminology
+Use these brand-specific terms instead of generic alternatives:
+- **[term]**: [meaning]
+...
+
+## Image Interpretation
+**Brand colours:** [colours]
+**When you see → interpret as:**
+- "[visual]" → [meaning]
+...
+```
+
+### Step 6: Save
+
+Tell the user:
+
+1. **For Claude Desktop:** Save the skill content as `Skill.md` in a folder named `[customer-name]-brand-context/`, ZIP it, and upload via Customize > Skills
+2. **For the project:** Save the JSON as `.site-context.json` in the project root, then run `generate-skills` to create the skill automatically
+3. **To update later:** Edit `.site-context.json` and re-run `generate-skills`, or use this skill again to rebuild from scratch
+
+## Tips
+
+- If the site has a blog, look at article content for more terminology and voice clues
+- Company about pages are great for understanding target audience
+- Service/product pages reveal the key terms and benefits language
+- Look for consistent phrases that appear across multiple pages — those are likely intentional brand language