@se-studio/project-build 1.0.131 → 1.0.133

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

@@ -1,313 +0,0 @@
----
-name: generate-all-guidelines
-description: Full-site CMS guideline run — bulk screenshots (components + collections), CLI collection/externals, then Phase B/C/D for every component. After update-cms-guidelines fresh/clean slate, do not skip types or git-restore component fragments.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.1.0"
----
-
-# Generate All Guidelines (Full Site Run)
-
-Generates CMS guidelines for every registered type in one orchestrated run.
-The workflow front-loads all screenshot capture so parallel subagents can go
-straight to guideline writing without waiting for screenshots one by one.
-
-## Full regeneration vs partial resume
-
-| Caller intent | What to do |
-|---|---|
-| **Parent skill:** `update-cms-guidelines` mode **`fresh`** (after **clean slate**) | **Ignore** the Phase 0 “skip if fragment + screenshot exist” rule for components — there must be **no** pre-existing `components/<slug>.md`. Capture **every** discovery component (Phase 1) and **every** discovery collection (Phase 1b). Run Phase 3 for **every** component (overwrite all `components/*.md`). |
-| **Partial resume** (crashed mid-run, or only some types failed) | Use the skip check in Phase 0 only for types that are **already complete** (fragment + `index.json` rows with `mode` `component`). Finish missing types only. |
-| **Invalid shortcut for “total regen”** | Restoring `docs/cms-guidelines/components/*.md` from git instead of Phase 3 — **never** when the user asked for a full regeneration. |
-
-## When to use
-
-- First-time guideline generation for a new project
-- **`fresh` full regeneration** after **update-cms-guidelines** clean slate
-- Bulk regeneration after major refactoring (prefer **`fresh`** if prose and screenshots should both be renewed)
-- Adding screenshot links to an existing set of guidelines that has no screenshots yet (partial — still run Phase 3 only for types missing fragments)
-
-Use the **generate-cms-guidelines** skill (`single` or `merge-only` mode) for small incremental edits; use **`sync`** in **update-cms-guidelines** when registrations change (**including stale removal**).
-
----
-
-## Prerequisites
-
-All of these must be true before starting. Check each one.
-
-1. **Dev server is running** at the app's port. Confirm:
-   ```bash
-   curl -sL http://localhost:<PORT>/api/cms/discovery/ | head -c 100
-   ```
-   Should return JSON starting with `{"components":[`.
-
-2. **`agent-browser` is installed** (needed for screenshot capture):
-   ```bash
-   agent-browser --version
-   # If missing: npm install -g agent-browser && agent-browser install
-   ```
-
-3. **Showcase pipeline completed** — `src/generated/showcase-mocks.json` must contain real content (not just `{}` stubs). If empty, run the **curate-showcase-mocks** skill first.
-
-4. **Field list generated:**
-   ```bash
-   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 here).
-
-5. **LLM pre-pass run** — `src/generated/cms-discovery/accepted-variants/` must contain JSON files in subdirs (`components/`, `collections/`, `externals/`). These are written by `generate-showcase-mocks`. If the directory is empty or missing, run:
-   ```bash
-   pnpm generate-showcase-mocks
-   # or: node node_modules/@se-studio/project-build/dist/generate-showcase-mocks.js
-   ```
-
----
-
-## Inputs
-
-| Input | Example |
-|-------|---------|
-| App directory (absolute or repo-relative) | `apps/example-se2026` or `/home/nick/source/se/se-website-2026` |
-| Discovery URL | `http://localhost:3012/api/cms/discovery/` |
-| Port | `3012` |
-
----
-
-## Pipeline Overview
-
-```
-Phase 0 — Discover      Fetch all type names from the discovery API
-Phase 1 — Screenshots   Bulk capture all component screenshots (CLI only, no LLM)
-Phase 1b — Screenshots  Bulk capture all collection screenshots (same; required for a complete full run)
-Phase 2 — Collections   Generate collection + external guideline fragments (CLI only)
-Phase 3 — Components    Parallel subagents: Phase B (write) + C (colour) + D (validate) per type
-Phase 4 — Merge         cms-merge-guidelines (single CLI call)
-Phase 5 — Commit        git add + commit
-```
-
-Phases 1, 1b, and 2 are purely mechanical — they run fast and require no LLM supervision.
-Phase 3 is where parallel subagents do the guideline writing.
-
----
-
-## Phase 0 — Discover all types
-
-Fetch the discovery endpoint and collect the full list of component type names.
-Store this as your working list.
-
-```bash
-curl -sL http://localhost:<PORT>/api/cms/discovery/ > /tmp/discovery.json
-```
-
-From the JSON (top-level keys from `/api/cms/discovery/`):
-- `components[].name` — component types needing Phases 1 + 3
-- `collections[].name` — collection types (Phase 1 screenshots + Phase 2 markdown)
-- `externals[].name` — external types (Phase 2 handles markdown; screenshots only if your app captures them)
-
-Compute each component's slug: `typeName.toLowerCase().replace(/\s+/g, '-').replace(/[()]/g, '')`
-
-**Skip check (partial runs only):** For each component, if **both** of these already exist, you may skip that component:
-- `<appDir>/docs/cms-guidelines/components/<slug>.md`
-- `<appDir>/docs/cms-guidelines/screenshots/index.json` has an entry for this component (`mode` `component`)
-
-If both exist, skip that component (already done). Only process the unfinished ones.
-
-**Full regeneration (`fresh` after clean slate):** **Do not apply** this skip check — process **all** discovery components.
-
-**Note:** Same **display name** can exist as both a component and a collection (e.g. FAQ). `cms-capture-screenshots` indexes entries by `mode::typeName::variant`; keep both screenshot sets when both exist.
-
----
-
-## Phase 1 — Bulk screenshot capture (all components at once)
-
-This is the key step that makes the full run fast. Instead of capturing screenshots one
-type at a time inside each subagent, we capture everything upfront in a tight loop.
-
-For each component type name that needs processing, run:
-
-```bash
-# Check if accepted-variants file exists for this type (check both components/ and collections/)
-SLUG="<type-slug>"
-VARIANTS_FILE="<appDir>/src/generated/cms-discovery/accepted-variants/components/${SLUG}.json"
-if [ ! -f "$VARIANTS_FILE" ]; then
-  VARIANTS_FILE="<appDir>/src/generated/cms-discovery/accepted-variants/collections/${SLUG}.json"
-fi
-
-if [ -f "$VARIANTS_FILE" ]; then
-  cms-capture-screenshots --variants "$VARIANTS_FILE" --app-dir <appDir>
-else
-  # Fall back to default variants for the type
-  cms-capture-screenshots --type "<TYPE_NAME>" --app-dir <appDir>
-fi
-```
-
-Run all of these sequentially (screenshots require the browser to be driven one at a time).
-`cms-capture-screenshots` automatically updates `docs/cms-guidelines/screenshots/index.json` after each run.
-
-**If `agent-browser` is not available:** the command degrades to printing URLs only.
-Install it first: `npm install -g agent-browser && agent-browser install`.
-
-After all captures, confirm `docs/cms-guidelines/screenshots/index.json` exists and has entries.
-
-### Phase 1b — Collection screenshots (required for a complete full run)
-
-Repeat the same loop for **each** `collections[].name` from discovery:
-
-- Resolve `accepted-variants/collections/<slug>.json` (same slug rules as Phase 0).
-- If missing, add a minimal variant file (e.g. single `default` variant) so capture can run, or run `generate-showcase-mocks` / manual backfill — see **curate-showcase-mocks** / **update-cms-guidelines** `fresh`.
-
-```bash
-cms-capture-screenshots --variants "<appDir>/src/generated/cms-discovery/accepted-variants/collections/<slug>.json" --app-dir <appDir>
-```
-
-**Full regeneration:** capture **every** collection. **Partial resume:** only collections that are new or that you intentionally refreshed.
-
----
-
-## Phase 2 — Collections and externals (CLI, no subagents needed)
-
-Run once — this regenerates all collection guidelines and creates any missing external templates:
-
-```bash
-cms-generate-collection-guidelines \
-  --discovery-url http://localhost:<PORT>/api/cms/discovery/ \
-  --app-dir <appDir>
-```
-
-This writes `docs/cms-guidelines/collections/*.md` and creates stub `docs/cms-guidelines/externals/*.md` for any new externals.
-
-**External schemas:** If any new `externals/*.md` stubs were created, fill in their
-`## Fields & Schema` and `## Usage` sections manually before continuing (or after the full run).
-The rest of the pipeline doesn't depend on them being complete.
-
----
-
-## Phase 3 — Component guidelines (parallel subagents)
-
-Launch subagents in batches of **4 in parallel**. Each subagent handles one component type
-through Phases B, C, and D only (screenshots are already done from Phases 1 and 1b).
-
-### Subagent prompt template
-
-For each component type, use this prompt (fill in `<COMPONENT_TYPE>`, `<APP_DIR>`, `<PORT>`):
-
-```
-Generate the CMS guideline fragment for <COMPONENT_TYPE>.
-Target app directory: <APP_DIR>
-
-IMPORTANT: Screenshots have already been captured. Skip Phase A entirely.
-Go straight to Phase B.
-
-Files to read before starting:
-- packages/contentful-cms/skills/cms-guidelines/generation-prompt.md  (Phase B instructions)
-- packages/contentful-cms/skills/cms-guidelines/colour-hint-prompt.md  (Phase C instructions)
-- packages/contentful-cms/skills/cms-guidelines/validation-prompt.md   (Phase D instructions)
-- <APP_DIR>/src/project/components/<TypeName>.tsx  (component source)
-- <APP_DIR>/generated/cms-discovery/field-list.json
-- <APP_DIR>/src/generated/cms-discovery/accepted-variants/{components|collections|externals}/<type-slug>.json
-- <APP_DIR>/docs/cms-guidelines/screenshots/index.json  (which screenshots exist)
-- <APP_DIR>/.contentful-cms.json  (get devBaseUrl for screenshot links)
-
-=== Phase B: Generate guideline ===
-Follow generation-prompt.md (three-step process).
-The guideline MUST include a ## Screenshots table using devBaseUrl from .contentful-cms.json.
-Only include variants present in screenshots/index.json.
-Save output to <APP_DIR>/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 — that runs once after all components complete.
-```
-
-### Batch execution
-
-Process all unfinished components in batches:
-- Launch 4 subagents simultaneously
-- Wait for all 4 to complete before launching the next batch
-- If any subagent fails or times out, note the type name and re-run it individually
-  using the **generate-cms-guidelines** skill in `single` mode
-
-Typical time per component: 3–6 minutes (mostly LLM time for generation + validation).
-Typical total time for 15 components in batches of 4: ~25–35 minutes.
-
----
-
-## Phase 4 — Merge
-
-After all subagents complete, rebuild the combined document:
-
-```bash
-cms-merge-guidelines --app-dir <appDir>
-# or from the app directory:
-pnpm run cms-guidelines:merge
-```
-
-Open `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md` and do a quick sanity check:
-- Does it contain all expected types?
-- Do the screenshot image links look correct (using the right port)?
-
----
-
-## Phase 5 — Commit
-
-```bash
-git add <appDir>/docs/cms-guidelines/ <appDir>/src/generated/cms-discovery/
-git commit -m "chore(<appName>): generate all CMS guidelines with screenshots"
-```
-
----
-
-## Handling failures and partial runs
-
-The pipeline is designed to be resumable. If it stops partway through:
-
-- **Phase 1 failed for some types:** Re-run `cms-capture-screenshots` for just those types.
-  `index.json` is additive — it won't remove entries from previous runs.
-- **Phase 3 subagent failed:** Use `generate-cms-guidelines` skill in `single` mode for that type.
-- **Phase 2 not run yet:** Re-run `cms-generate-collection-guidelines` — it's idempotent for collections.
-- **Phase 4 merge not run:** Just run `cms-merge-guidelines` — it reads whatever `.md` files exist.
-
-To re-run everything for a single type after fixing a problem:
-```bash
-# Re-capture screenshots
-cms-capture-screenshots --type "<TYPE_NAME>" --app-dir <appDir>
-# Then use generate-cms-guidelines skill (single mode) for the guideline
-```
-
----
-
-## Quick reference — full command sequence
-
-```bash
-# 0. Prerequisites check
-curl -sL http://localhost:<PORT>/api/cms/discovery/ | head -c 100
-agent-browser --version
-
-# 1. Bulk screenshots (repeat for each type — use the mode subdir)
-cms-capture-screenshots --variants src/generated/cms-discovery/accepted-variants/components/<slug>.json --app-dir <appDir>
-# or for collections:
-cms-capture-screenshots --variants src/generated/cms-discovery/accepted-variants/collections/<slug>.json --app-dir <appDir>
-
-# 2. Collections + externals
-cms-generate-collection-guidelines \
-  --discovery-url http://localhost:<PORT>/api/cms/discovery/ \
-  --app-dir <appDir>
-
-# 3. [Parallel subagents — see Phase 3 above]
-
-# 4. Merge
-cms-merge-guidelines --app-dir <appDir>
-
-# 5. Commit
-git add docs/cms-guidelines/ src/generated/cms-discovery/
-git commit -m "chore: generate all CMS guidelines"
-```

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

@@ -1,313 +0,0 @@
----
-name: "contentful-cms:generate-cms-guidelines"
-description: "Generate, regenerate, or merge CMS guideline markdown fragments for any app in the monorepo."
----
-
-# 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.
-
-**Orchestration:** For a **true full clean regeneration** (wipe artifacts, all screenshots, **new** component prose for every type, stale removal policy), use **`update-cms-guidelines`** (mode **`fresh`**) — not this skill’s `full` mode alone. This skill’s **`full`** mode follows **generate-all-guidelines**, which may **skip** types that already have fragments unless you are doing a **partial resume**.
-
-**Incremental:** If registrations changed, start with **`update-cms-guidelines`** mode **`sync`** so **removed** types are deleted (fragments, PNGs, index rows) before you add or refresh individual types with **`single`** here.
-
----
-
-## When to use this skill
-
-- **Full site (first time or after clean slate):** Prefer invoking **`update-cms-guidelines`** → **`fresh`** (clean slate + **generate-all-guidelines**). Use this skill’s **`full`** only when aligned with that pipeline (no skip / post-clean-slate).
-- **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.
-- **Vague “regenerate everything”:** Ask whether the user means **`fresh`** (clean + rewrite all component guidelines) or **`sync`** + targeted updates — see **update-cms-guidelines**.
-
----
-
-## 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/generated/showcase-examples.json` to the app.
-3. **Curate showcase mocks:** Follow the [curate-showcase-mocks skill](.agents/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/{components|collections|externals}/<type-slug>.json
-   (choose subdir based on mode: component → components/, collection → collections/, external → externals/)
-
-=== 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={components|collections|externals}/<type-slug>-default.png)
-   Use the `file` field from index.json (which includes the mode subpath).
-   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/{components\|collections\|externals}/<slug>.json` | Accepted variant list (per type, in mode subdir) |
-| `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=components/hero-default.png) |
-| Navy    | ![Navy](http://localhost:3010/cms/screenshot?file=components/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.