@se-studio/skills 1.0.1

package/skills/se-marketing-sites-create-page/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: create-page-route
+description: Guide for creating new Next.js App Router pages and dynamic routes in the SE Core Product framework. Use when creating CMS-driven pages, adding route segments, or setting up routing.
+license: Private
+metadata:
+  author: se-core-product
+  version: "2.0.0"
+---
+
+# Creating Pages and Routes
+
+This guide explains how to create new pages and handle routing in the SE Core Product Next.js framework. The system uses Next.js App Router with Contentful-driven dynamic routing.
+
+Reference apps: **example-se2026**, **example-brightline**, **example-om1**.
+
+## Page Architecture
+
+### 1. (cms-routes) Route Group
+
+All CMS-driven pages live under `src/app/(cms-routes)/`. The layout enables dynamic params:
+
+```tsx
+// layout.tsx
+export const dynamicParams = true;
+
+export default function CmsRoutesLayout({ children }: { children: React.ReactNode }) {
+  return children;
+}
+```
+
+### 2. Route Structure
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/` | `page.ts` | Home (slug: `index`) |
+| `/{slug}/` | `[level1]/page.ts` | Single-level page |
+| `/{slug1}/{slug2}/...` | `[level1]/[...slugs]/page.ts` | Multi-level pages |
+| `/articles/` | `articles/page.ts` | Articles index (uses ARTICLES_BASE from constants) |
+| `/articles/{type}/` | `articles/[articleType]/page.ts` | Article type index |
+| `/articles/{type}/{tag}/` | `articles/[articleType]/[tag]/page.ts` | Article type + tag index |
+| `/articles/{type}/{tag}/{article}/` | `articles/[articleType]/[tag]/[...slugs]/page.ts` | Individual article |
+| `/tags/`, `/tags/{tag}/` | `tags/` | Tag index (if enabled) |
+| `/people/`, `/people/{person}/` | `people/` | People (if enabled) |
+
+Base paths (e.g. `/articles` vs `/learning-hub`) come from `@/lib/constants`.
+
+### 3. appShared Pattern
+
+Route files are thin wrappers. Data-fetching and rendering logic lives in `src/appShared/`:
+
+- `pageShared.tsx` – `generatePage`, `generatePageMetadata`
+- `articleShared.tsx` – articles
+- `articleTypeShared.tsx`, `articleTypesIndexShared.tsx`, `articleTypeTagShared.tsx` – article indices
+- `customTypeShared.tsx` – custom types
+- `personShared.tsx`, `tagShared.tsx`, `tagsIndexShared.tsx`, `teamIndexShared.tsx`
+
+## Route Page Template
+
+Each route page extracts params and delegates to the appropriate appShared function:
+
+```typescript
+import type { ResolvingMetadata } from 'next';
+import { generatePage, generatePageMetadata } from '@/appShared/pageShared';
+
+export function generateStaticParams() {
+  return [];
+}
+
+async function extractDetails(props: PageProps<'/[level1]'>) {
+  const params = await props.params;
+  const { level1 } = params;
+  return { slug: level1, path: `/${level1}/` };
+}
+
+export async function generateMetadata(props: PageProps<'/[level1]'>, parent: ResolvingMetadata) {
+  const { slug, path } = await extractDetails(props);
+  return generatePageMetadata(slug, path, true, parent);
+}
+
+export default async function (props: PageProps<'/[level1]'>) {
+  const { slug, path } = await extractDetails(props);
+  return generatePage(slug, path, true);
+}
+```
+
+For the home page (`/`), use slug `'index'` and path `'/'` directly.
+
+## CmsContent Usage
+
+The appShared modules render content with:
+
+```tsx
+<CmsContent
+  contents={page.contents}
+  rendererConfig={projectRendererConfig}
+  pageContext={{ page }}
+/>
+```
+
+- `contents` – array of page/article contents (not the full page object)
+- `rendererConfig` – from `@/lib/cms-server`
+- `pageContext` – provides page/article/customType to child components
+
+For route files that only need `converterContext` or `buildInformation` (e.g. `generateStaticParams`, sitemap, path computation), import from `@/lib/converter-context` when that module exists, so you don't pull in cms-server.
+
+## Creating a Specialized Route
+
+For a route that behaves differently from standard CMS pages (e.g. search, dashboard):
+
+1. Create the route under `(cms-routes)` or a separate route group.
+2. Either create a new appShared module (if the pattern is reusable) or implement inline.
+3. Use `getPageWithErrors`, `getArticleWithErrors`, etc. from `@/lib/cms-server`.
+4. Use `projectRendererConfig` from `@/lib/cms-server`.
+5. Render with `CmsContent` using `contents`, `rendererConfig`, and `pageContext`.
+
+## Custom Layouts
+
+If a route needs a different layout (e.g. no header/footer), create `layout.tsx` in that route directory.
+
+## Troubleshooting
+
+- **404 on new route**: Re-run the dev server or build after adding a dynamic route segment.
+- **Static params missing**: Dynamic routes use `generateStaticParams() { return []; }` for on-demand rendering.
+- **Preview mode**: Handled by `draftOnly` in `@/lib/server-config`; appShared modules use it automatically.
+
+## A/B Test Variant Route (`page-test`)
+
+When A/B testing is enabled, variant pages are served through a `/page-test/[...slugs]` route that the middleware rewrites to. This route **must** use `generatePageTestMetadata` (not `generatePageMetadata`) so that `robots`/`indexed` comes from the **canonical/control** page — variant entries are intentionally `indexed: false` in Contentful.
+
+If the slug is not a known variant in `testsByPath`, **return 404** (`notFound()`): there is no control page to merge, and `/page-test/…` is only valid for configured tests.
+
+```typescript
+import { findCanonicalPath } from '@se-studio/ab-testing';
+import type { ResolvingMetadata } from 'next';
+import { notFound } from 'next/navigation';
+import { testsByPath } from '@/generated/abTests';
+import { generatePage, generatePageTestMetadata } from '@/lib/route-handlers';
+import { getPageRouteConfig } from '@/lib/routeConfig';
+
+/** Variant slug must appear in testsByPath; otherwise this route is not valid. */
+function requireCanonicalPath(slug: string): string {
+  const canonicalPath = findCanonicalPath(testsByPath, slug);
+  if (!canonicalPath) {
+    notFound();
+  }
+  return canonicalPath;
+}
+
+export function generateStaticParams() {
+  return [];
+}
+
+async function extractDetails(props: PageProps<'/page-test/[...slugs]'>) {
+  const params = await props.params;
+  const slug = params.slugs.join('/');
+  return { slug, path: `/page-test/${slug}/` };
+}
+
+export async function generateMetadata(
+  props: PageProps<'/page-test/[...slugs]'>,
+  parent: ResolvingMetadata,
+) {
+  const { slug } = await extractDetails(props);
+  const canonicalPath = requireCanonicalPath(slug);
+  const canonicalSlug = canonicalPath.replace(/^\/|\/$/g, '') || slug;
+  // Use generatePageTestMetadata: merges variant title/description with
+  // canonical page's indexed flag so robots directives are always correct.
+  return generatePageTestMetadata(slug, canonicalSlug, canonicalPath, getPageRouteConfig(canonicalSlug), parent);
+}
+
+export default async function (props: PageProps<'/page-test/[...slugs]'>) {
+  const { slug, path } = await extractDetails(props);
+  requireCanonicalPath(slug);
+  return generatePage(slug, path, getPageRouteConfig(slug));
+}
+```
+
+Also export `generatePageTestMetadata` from the app's `src/lib/route-handlers.ts` destructuring alongside `generatePageMetadata`.
+
+## See Also
+
+- **cms-routes-and-appshared** – Full route structure and appShared pattern
+- **lib-cms-structure** – lib directory layout and cms-server usage

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

@@ -0,0 +1,344 @@
+---
+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.1.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.
+
+It is **Step 2** of **`update-cms-guidelines`** mode **`fresh`** (after the clean slate). Realistic mocks and `accepted-variants` files are **required** before bulk screenshot capture in **generate-all-guidelines**.
+
+## 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
+- You are doing a **full CMS guidelines regeneration** and need fresh showcase data before Phase 1 / 1b screenshots
+
+## 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/{components|collections|externals}/<slug>.json` — per-type variant files (in mode subdir)
+
+**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/{components\|collections\|externals}/` | 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
+
+### Installing skills
+
+For standalone projects not in the monorepo, install SE Studio skills via the `skills` CLI:
+
+```bash
+npx skills add @se-studio/skills
+```
+
+This installs all SE Studio agent skills (including this one) into the project's agent skill
+directories (e.g. `.claude/skills/` for Claude Code).
+
+### Auto-sync on package update
+
+Add `@se-studio/skills` as a devDependency and a `postinstall` script so skills reinstall
+whenever `pnpm install` is run:
+
+```json
+"devDependencies": {
+  "@se-studio/skills": "^1.0.0"
+},
+"scripts": {
+  "postinstall": "npx skills update -y"
+}
+```
+
+### 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.