@se-studio/project-build 1.0.131 → 1.0.133

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

@@ -1,348 +0,0 @@
----
-name: update-cms-guidelines
-description: Primary CMS guideline orchestration. Use `fresh` only after a full clean slate and complete pipeline (showcase → screenshots → new component prose via Phase B/C/D — never git-restore fragments). Use `sync` for incremental changes but always delete stale types. If the user is vague, ask whether they want a full clean regeneration or incremental sync before acting.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.1.0"
----
-
-# Update CMS Guidelines
-
-This is the **primary entry point** for all CMS guideline work. It wraps the lower-level skills
-into three clear modes so you always know which path to take.
-
-## Terms: full regeneration vs incremental
-
-| Term | Meaning |
-|---|---|
-| **Full regeneration** (brand-new run) | **Clean slate** of generated artifacts, then rerun the **entire** pipeline: showcase data → mocks → field list → **all** screenshots (components **and** collections) → **new** component guideline markdown (Phase B + C + D for **every** type — no restoring old `.md` from git) → collection/external CLI step → merge → commit. Collections are CLI-regenerated; externals may need hand-filled sections after stub creation. |
-| **Incremental** (`sync` + targeted work) | Discovery/registrations are the source of truth. **Remove every stale artifact** for types no longer registered (fragments, PNGs, `screenshots/index.json` rows, `accepted-variants` JSON where your app tracks them). Then add or refresh only **new** or **changed** types (screenshots + `generate-cms-guidelines` single / generate-all partial). Always merge at the end if fragments changed. |
-
-**Not** a full regeneration: restoring `docs/cms-guidelines/components/*.md` (or externals) from `git checkout`, merge-only, or screenshots-only while leaving years-old prose in place.
-
-## When the user is vague
-
-Phrases like “regenerate guidelines”, “refresh CMS docs”, “update showcase/guidelines”, or “redo screenshots” are **ambiguous**.
-
-**Before doing substantial work, ask briefly:**
-
-1. Do you want a **full clean regeneration** (delete existing fragments and screenshots, rewrite every component guideline from scratch, full screenshot pass)?  
-2. Or an **incremental** update (sync with registrations — **including removing** dropped types — plus only new/changed types)?  
-3. Or something narrower (e.g. **merge-only**, **one component**, **collections CLI only**)?
-
-If they insist on “everything” / “from scratch” / “totally regenerate” / “wipe and rebuild”, treat that as **full regeneration** and follow **`fresh`** including the **clean slate** steps below — do **not** shortcut with git-restored fragments.
-
-## When to use which mode
-
-| Situation | Mode |
-|---|---|
-| New app — no guidelines exist yet | `fresh` |
-| User wants **total** / **full** / **clean-slate** regeneration | `fresh` (must include **clean slate** + full **generate-all-guidelines** Phase 3 for all components) |
-| Types added or removed in `registrations.ts` (incremental) | `sync` — **always** remove stale files and index entries, then add/refresh new types |
-| Fragment files edited manually, combined doc needs rebuild | `merge-only` |
-| Major refactor but user confirms they **do not** need new prose | Rare — confirm explicitly; otherwise use `fresh` |
-
----
-
-## Inputs
-
-| Input | Example |
-|---|---|
-| App directory (repo-relative or absolute) | `apps/example-se2026` |
-| Port | `3012` |
-| Discovery URL | `http://localhost:3012/api/cms/discovery/` |
-| Mode | `fresh` \| `sync` \| `merge-only` |
-
-**App ports:**
-
-| App | Port |
-|---|---|
-| example-brightline | 3010 |
-| example-se2026 | 3012 |
-| example-om1 | 3013 |
-| example-empty | 3014 |
-| example-brightlifekids | 3015 |
-
----
-
-## Mode: fresh
-
-Full pipeline from a **clean slate** (or a brand-new app). Expect roughly **30–90+ minutes** for a typical site (component count × LLM time for Phase B/C/D).
-
-### Step 0 — Clean slate (mandatory for true full regeneration)
-
-If any guideline or screenshot files already exist, **delete generated guideline outputs** before re-running the pipeline. Otherwise you risk mixed old/new content or skipping work.
-
-**Do:**
-
-1. Remove per-type fragments:  
-   `docs/cms-guidelines/components/*.md`, `docs/cms-guidelines/collections/*.md`, `docs/cms-guidelines/externals/*.md`  
-   **Keep** editorial/meta files if present (e.g. `README.md`, `CHECKLIST.md`, `LAYOUT.md`, `GENERATE_NEXT_*.md`).
-2. Remove merged bundle: `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md`.
-3. Remove screenshots: all `docs/cms-guidelines/screenshots/components/*.png`, `.../collections/*.png`, `.../externals/*.png` (if used), then reset `docs/cms-guidelines/screenshots/index.json` to `[]` **or** delete it so captures recreate it.
-4. Clear showcase pipeline inputs as needed: remove `src/generated/showcase-examples.json`, `src/generated/showcase-mocks-draft.json`, and the tree `src/generated/cms-discovery/accepted-variants/` (or empty `components/` / `collections/` / `externals/` subdirs). Stub `src/generated/showcase-mocks.json` per **curate-showcase-mocks** if the import must compile.
-5. Remove any **duplicate** variant path some apps still have (e.g. `generated/cms-discovery/accepted-variants/` at repo root of the app) if it is not the canonical `src/generated/...` tree.
-6. Optionally reset `generated/cms-discovery/colour-hints.json` if you want colour hints re-derived during Phase C.
-
-**Do not** (for a claimed full regeneration):
-
-- Restore `docs/cms-guidelines/components/*.md` or `externals/*.md` from git instead of running **generate-all-guidelines Phase 3** (Phase B + C + D per component).
-- Skip collection screenshot capture when collections are registered — Phase 1 must cover **both** components and collections for a complete visual record.
-
-After this, run Steps 1–4 in order (prerequisites → showcase mocks → field list → generate-all-guidelines).
-
-### Step 1 — Prerequisites
-
-Check all of these before starting:
-
-```bash
-# 1. Dev server is running
-curl -sL http://localhost:<PORT>/api/cms/discovery/ | head -c 100
-# Should return: {"components":[
-
-# 2. agent-browser is installed
-agent-browser --version
-# If missing: npm install -g agent-browser && agent-browser install
-
-# 3. Env vars present in <appDir>/.env.local
-grep -E "CONTENTFUL_SPACE_ID|CONTENTFUL_ACCESS_TOKEN|OPENAI_API_KEY|ANTHROPIC_API_KEY" <appDir>/.env.local
-```
-
-### Step 2 — Curate showcase mocks
-
-Read and follow the **curate-showcase-mocks** skill:
-`.agents/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md`
-
-This produces `src/generated/showcase-mocks.json` (committed) and
-`src/generated/cms-discovery/accepted-variants/{components|collections|externals}/<slug>.json` (often gitignored — **some apps commit them**; follow the app’s `.gitignore`).
-
-When complete, confirm:
-- `src/generated/showcase-mocks.json` has non-empty `components` and `collections` keys
-- `src/generated/cms-discovery/accepted-variants/` has `components/` and `collections/` subdirs with JSON files
-
-Backfill any registered types missing from the LLM draft using `showcase-examples.json` (see curate skill), and add minimal `accepted-variants` JSON for types with no variant file so screenshot capture can run.
-
-### Step 3 — Generate HTML Component Style Guide
-
-Generate the design system reference used when authoring `HtmlComponent` entries:
-
-```bash
-# From the app directory:
-pnpm run cms-generate-html-style-guide
-# or from repo root:
-pnpm --filter <appName> exec cms-generate-html-style-guide --app-dir .
-```
-
-Reads `tailwind.config.json` and `src/app/globals.css`; writes `docs/cms-guidelines/html-component-style-guide.md`. No dev server required. Safe to skip if the design system has not changed since the last run.
-
-### Step 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 .
-```
-
-Produces `generated/cms-discovery/field-list.json` (discovery API reads from this path). Some apps use `src/generated/` for showcase artifacts; see app docs.
-
-### Step 5 — Run generate-all-guidelines
-
-Read and follow the **generate-all-guidelines** skill:
-`.agents/skills/contentful-cms-generate-all-guidelines/SKILL.md`
-
-Skip its prerequisite check (you already verified everything through Step 4).
-Run Phases 0–5 from that skill with **full regeneration rules**:
-
-- **Phase 0** — Discover types; **do not** skip components that already had old fragments (there should be none after clean slate).
-- **Phase 1** — Bulk screenshot capture for **all components**, then **all collections** (and externals if your app captures them).
-- **Phase 2** — Collections + externals (`cms-generate-collection-guidelines`)
-- **Phase 3** — Component guidelines (**every** type: Phase B + C + D; **overwrite** `components/<slug>.md`)
-- **Phase 4** — Merge (`cms-merge-guidelines`)
-- **Phase 5** — Commit
-
-### After Phase 2 (externals)
-
-If any `docs/cms-guidelines/externals/<slug>.md` stubs were created, fill in their
-`## Fields & Schema` and `## Usage` sections before committing. See the
-**generate-cms-guidelines** skill (`Step 2b`) for guidance on what to put in these sections.
-
----
-
-## Mode: sync
-
-Use when types have been added or removed in `registrations.ts` (or from the Contentful space).
-This mode diffs the current registered types against existing guideline files and handles both
-stale files and new types.
-
-**Incremental is not “append only”.** If a type left registrations or discovery, you **must** remove its artifacts (markdown, PNGs, index rows, optional `accepted-variants` files). Otherwise the repo and `COMPONENT_GUIDELINES_FOR_LLM.md` will lie.
-
-### Phase 0 — Diff
-
-Fetch the discovery endpoint and compute the current set of registered type slugs:
-
-```bash
-curl -sL http://localhost:<PORT>/api/cms/discovery/ > /tmp/discovery.json
-```
-
-Slug formula: `name.toLowerCase().replace(/\s+/g, '-').replace(/[()]/g, '')`
-
-Examples: `"Article Browser Sticky"` → `article-browser-sticky`, `"Two Column (Rich Text)"` → `two-column-rich-text`
-
-Build three diff lists by comparing discovery slugs against existing files:
-
-```bash
-# List existing guideline file slugs (strip .md extension)
-ls <appDir>/docs/cms-guidelines/components/  # → component file slugs
-ls <appDir>/docs/cms-guidelines/collections/ # → collection file slugs
-ls <appDir>/docs/cms-guidelines/externals/   # → external file slugs
-```
-
-From the diff, identify:
-
-| Status | Meaning | Action |
-|---|---|---|
-| **STALE** | File exists, type not in discovery | Remove files |
-| **NEW** | Type in discovery, no file exists | Generate guidelines |
-| **UNCHANGED** | Both exist | Skip |
-
-Report the full diff to the user before taking any action.
-
-### Phase 1 — Remove stale files
-
-For each **stale component** slug (`<slug>`):
-
-```bash
-# 1. Delete the guideline fragment
-rm <appDir>/docs/cms-guidelines/components/<slug>.md
-
-# 2. Delete all screenshot variants (screenshots live under components/ or collections/ subdirs)
-rm -f <appDir>/docs/cms-guidelines/screenshots/components/<slug>-*.png
-rm -f <appDir>/docs/cms-guidelines/screenshots/collections/<slug>-*.png
-
-# 3. Remove screenshot index entries for this type (index.json has typeName and file e.g. "components/<slug>-default.png")
-# Read screenshots/index.json, filter out entries where typeName matches or file starts with "components/<slug>-" or "collections/<slug>-", rewrite
-node -e "
-  const fs = require('node:fs');
-  const p = '<appDir>/docs/cms-guidelines/screenshots/index.json';
-  const idx = JSON.parse(fs.readFileSync(p, 'utf8'));
-  const filtered = idx.filter(e => !e.file.startsWith('components/<slug>-') && !e.file.startsWith('collections/<slug>-'));
-  fs.writeFileSync(p, JSON.stringify(filtered, null, 2));
-  console.log('Removed', idx.length - filtered.length, 'entries for <slug>');
-"
-
-# 4. Remove accepted-variants file if present (check both components/ and collections/)
-rm -f <appDir>/src/generated/cms-discovery/accepted-variants/components/<slug>.json
-rm -f <appDir>/src/generated/cms-discovery/accepted-variants/collections/<slug>.json
-```
-
-For each **stale collection** slug (`<slug>`):
-
-```bash
-# 1. Fragment
-rm <appDir>/docs/cms-guidelines/collections/<slug>.md
-
-# 2. Screenshots for that collection
-rm -f <appDir>/docs/cms-guidelines/screenshots/collections/<slug>-*.png
-
-# 3. Remove index entries (same pattern as components — filter by file prefix)
-# e.g. drop rows where e.file.startsWith('collections/<slug>-')
-```
-
-Use the same **index.json** filtering approach as for stale components (adjust the `startsWith` prefix to `collections/<slug>-`).
-
-For each **stale external** slug:
-
-> **Caution:** External guideline files contain hand-authored schema documentation. Confirm
-> with the user before deleting. If confirmed:
-
-```bash
-rm <appDir>/docs/cms-guidelines/externals/<slug>.md
-```
-
-### Phase 2 — Add new types
-
-**New components** (one or more):
-
-Run the [generate-all-guidelines](../generate-all-guidelines/SKILL.md) skill's Phase 1 (screenshots)
-and Phase 3 (component subagents) for **only the new types**, then skip to Phase 4 (merge).
-
-If the new component does not yet have an `accepted-variants/components/<slug>.json` file (or `collections/<slug>.json` for a collection), run:
-
-```bash
-pnpm --filter <appName> generate-showcase-mocks -- --types "<Type Name 1>,<Type Name 2>"
-```
-
-This regenerates the variant file for just those types. Then capture screenshots and run the
-Phase 3 subagent prompt as described in generate-all-guidelines.
-
-**New collections or externals:**
-
-Re-running the generator is safe — it always overwrites collections and only creates externals
-if the file does not already exist:
-
-```bash
-cms-generate-collection-guidelines \
-  --discovery-url http://localhost:<PORT>/api/cms/discovery/ \
-  --app-dir <appDir>
-```
-
-If a new external stub was created, fill in its `## Fields & Schema` and `## Usage` sections
-before committing (see Mode: fresh → After Phase 2).
-
-### Phase 3 — Merge and commit
-
-```bash
-# Rebuild the combined document
-cms-merge-guidelines --app-dir <appDir>
-# or: pnpm --filter <appName> run cms-guidelines:merge
-
-# Commit everything
-git add <appDir>/docs/cms-guidelines/ <appDir>/src/generated/cms-discovery/
-git commit -m "chore(<appName>): sync CMS guidelines with registrations"
-```
-
----
-
-## Mode: merge-only
-
-Rebuilds `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md` from all existing fragment files.
-Use after manual edits to fragment files, or after any of the other modes if the combined doc
-looks stale.
-
-```bash
-cms-merge-guidelines --app-dir <appDir>
-# or from the app directory:
-pnpm run cms-guidelines:merge
-```
-
----
-
-## Output files (reference)
-
-All under `<appDir>`:
-
-| File | Description | Committed |
-|---|---|---|
-| `docs/cms-guidelines/components/<slug>.md` | Per-component fragment | Yes |
-| `docs/cms-guidelines/collections/<slug>.md` | Per-collection fragment | Yes |
-| `docs/cms-guidelines/externals/<slug>.md` | Per-external fragment | Yes |
-| `docs/cms-guidelines/screenshots/index.json` | Screenshot index | Yes |
-| `docs/cms-guidelines/screenshots/{components\|collections\|externals}/*.png` | Screenshot images | Yes |
-| `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md` | Merged document (AI-readable) | Yes |
-| `generated/cms-discovery/field-list.json` | Field metadata (discovery API) | Yes |
-| `src/generated/showcase-mocks.json` | Curated showcase mocks | Yes |
-| `src/generated/cms-discovery/accepted-variants/{components\|collections\|externals}/<slug>.json` | Variant files (per type) | Usually no (app-dependent) |
-| `src/generated/showcase-examples.json` | Raw Contentful data dump | No |
-
----
-
-## Sub-skills reference
-
-| Purpose | Skill |
-|---|---|
-| Curate showcase mocks (Step 2 of `fresh`) | `.agents/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md` |
-| Full-site bulk generation (Step 4 of `fresh`: Phases 0–5) | `.agents/skills/contentful-cms-generate-all-guidelines/SKILL.md` |
-| Single-type regeneration (after code change) | `.agents/skills/contentful-cms-generate-cms-guidelines/SKILL.md` (mode: single) |
-| Per-component pipeline detail | `packages/contentful-cms/skills/cms-guidelines/generate-component-guidelines.md` |

package/skills/se-marketing-sites/cms-routes-and-appshared/SKILL.md

@@ -1,99 +0,0 @@
----
-name: cms-routes-and-appshared
-description: Guide for the (cms-routes) route group and appShared pattern. Use when setting up or migrating CMS-driven routing, creating new route segments, or refactoring page structure.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.0.0"
----
-
-# CMS Routes and appShared Pattern
-
-Reference apps: **example-se2026**, **example-brightline**, **example-om1**. (example-om1 uses `resources/`, `team/`, `topics/` instead of `articles/`, `people/`, `tags/`.)
-
-## Route Group: (cms-routes)
-
-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;
-}
-```
-
-## 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) |
-| `/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 come from `@/lib/constants` (e.g. ARTICLES_BASE = `/learning-hub` or `/articles`).
-
-## appShared Modules
-
-Route files are thin wrappers. Logic lives in `src/appShared/`:
-
-| Module | Exports | Used by |
-|--------|---------|---------|
-| `pageShared.tsx` | `generatePage`, `generatePageMetadata` | `/`, `[level1]`, `[level1]/[...slugs]` |
-| `articleShared.tsx` | `generateArticlePage`, `generateArticleMetadata` | Article detail |
-| `articleTypeShared.tsx` | `generateArticleTypePage`, `generateArticleTypeMetadata` | Article type index |
-| `articleTypesIndexShared.tsx` | `generateArticleTypesIndexPage`, `generateArticleTypesIndexMetadata` | Articles index |
-| `articleTypeTagShared.tsx` | `generateArticleTypeTagPage`, `generateArticleTypeTagMetadata` | Article type + tag index |
-| `customTypeShared.tsx` | `generateCustomTypePage`, `generateCustomTypeMetadata` | Custom types |
-| `personShared.tsx` | `generatePersonPage`, `generatePersonMetadata` | Person page |
-| `tagShared.tsx` | `generateTagPage`, `generateTagMetadata` | Tag index |
-| `tagsIndexShared.tsx` | `generateTagsIndexPage`, `generateTagsIndexMetadata` | Tags index |
-| `teamIndexShared.tsx` | `generateTeamIndexPage`, `generateTeamIndexMetadata` | People index |
-
-## Route Page Pattern
-
-Each route page:
-
-1. Exports `generateStaticParams() { return []; }` for dynamic routes
-2. Defines `extractDetails(props)` to derive slug/path from params
-3. Exports `generateMetadata(props, parent)` calling the shared metadata function
-4. Exports default async function calling the shared page 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 article routes, use `converterContext.urlCalculators.article`, `articleType`, `articleTypeTag` to compute the path. Import `converterContext` from `@/lib/converter-context` when that module exists (so route files don't pull in cms-server); otherwise from `@/lib/cms-server`.
-
-## See Also
-
-- **create-page** – Creating new pages and routes
-- **lib-cms-structure** – lib directory layout