@se-studio/skills 0.0.0-next16-20260822103555

package/README.md

@@ -0,0 +1,95 @@
+# @se-studio/skills
+
+Agent skills for SE Studio marketing site development with Contentful CMS.
+
+## Install
+
+**In this monorepo** — skills are synced into `.agents/skills/` (symlinked from `.cursor/skills/`):
+
+```bash
+pnpm skills:validate
+pnpm skills:sync
+```
+
+From this package directory: `pnpm validate` (runs the same frontmatter check).
+
+**In external projects:**
+
+```bash
+npx skills add @se-studio/skills
+```
+
+Auto-sync on `pnpm install` (see [`packages/project-build/README.md`](../project-build/README.md) for the full `package.json` snippet). Use `pnpm skills:sync` manually to add or refresh third-party skill packs.
+
+## Package layout
+
+| Path | Purpose |
+|------|---------|
+| `skills/<name>/SKILL.md` | Agent skills — the only directories scanned by `skills-npm` and the skills CLI |
+| `references/<name>/` | Support docs, prompt packs, and pipeline references (no `SKILL.md`) |
+
+Do **not** place non-skill material under `skills/` — directories there without `SKILL.md` cause `file_error` warnings in consumer repos on `pnpm install`.
+
+## Authoring skills
+
+Canonical sources live in `packages/skills/skills/<skill-dir>/SKILL.md`. Do **not** edit `.agents/skills/` by hand.
+
+### Frontmatter contract (Claude Code compatible)
+
+Every `SKILL.md` must start with YAML frontmatter containing **only** `name` and `description`:
+
+```yaml
+---
+name: se-marketing-sites-create-component
+description: "Guide for creating new CMS-driven components. Use when asked to create a new CMS component."
+---
+```
+
+Rules:
+
+| Field | Requirement |
+|-------|-------------|
+| `name` | Must exactly match the skill directory name; `[a-z0-9-]+` only; max 64 characters |
+| `description` | Single line, double-quoted, non-empty, max 1024 characters; no backticks |
+
+Do **not** use:
+
+- YAML block scalars for description (`>`, `|`)
+- Multiline descriptions
+- Extra frontmatter keys (`license`, `metadata`, `promptSignals`, etc.) — put those in the markdown body if needed
+- Invalid `name` values (spaces, capitals, colons, dots)
+
+Claude Code uses a naive frontmatter parser; violations cause descriptions to silently disappear from the skill selector.
+
+### Workflow
+
+1. Edit `packages/skills/skills/<skill-dir>/SKILL.md`
+2. Validate: `pnpm skills:validate`
+3. Sync: `pnpm skills:sync` (copies `skills/` → `.agents/skills/` and `references/` → `.agents/references/`)
+4. Add a changeset if publishing `@se-studio/skills`
+
+### cms-edit bundled skills (`@se-studio/contentful-cms`)
+
+The CLI ships a **subset** of skills under `packages/contentful-cms/skills/` for `cms-edit skill install`. Those files are **generated** from this package:
+
+| Canonical source (`packages/skills/skills/`) | Bundled name (`packages/contentful-cms/skills/`) |
+|---------------------------------------------|--------------------------------------------------|
+| `contentful-cms-core` | `core` |
+| `contentful-cms-editor-tasks` | `editor-tasks` |
+| `contentful-cms-templates` | `templates` |
+| `contentful-cms-setup` | `setup` |
+
+After editing any `contentful-cms-*` skill here, run:
+
+```bash
+pnpm --filter @se-studio/contentful-cms sync:skills
+```
+
+Do not edit `packages/contentful-cms/skills/` directly. See `packages/contentful-cms/docs/SKILLS.md`.
+
+**Do not use `.claude/skills/` in the repo** as a skill source — it is untracked and local. Use `.agents/skills/` (via `pnpm skills:sync`) or `cms-edit skill install`.
+
+## References
+
+- [Anthropic skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- Monorepo skill index: root `CLAUDE.md` and `docs/AI_QUICK_REFERENCE.md`

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@se-studio/skills",
+  "version": "0.0.0-next16-20260822103555",
+  "description": "SE Studio agent skills for marketing site development with Contentful CMS",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Something-Else-Studio/se-core-product",
+    "directory": "packages/skills"
+  },
+  "license": "MIT",
+  "files": [
+    "skills",
+    "references",
+    "*.md"
+  ],
+  "keywords": [
+    "agent-skills",
+    "contentful",
+    "nextjs",
+    "marketing-sites"
+  ],
+  "homepage": "https://github.com/Something-Else-Studio/se-core-product#readme",
+  "bugs": {
+    "url": "https://github.com/Something-Else-Studio/se-core-product/issues"
+  },
+  "scripts": {
+    "validate": "node ../../scripts/validate-skills.mjs"
+  }
+}

package/references/agent-session/cms-edit-prod-merge.md

@@ -0,0 +1,35 @@
+# cms-edit-only production merge
+
+The **only** agent exception to “no production git”. Marketing site source, core `main`, and Vercel CLI deploys stay human-only.
+
+## When it applies
+
+All of the following must be true:
+
+1. The user asked to ship **hosted cms-edit** (host package bump, editor-pack-only, or continue a cms-edit host rollout).
+2. Any required `@se-studio/contentful-cms` version is **already on npm**.
+3. The merge is **customer** `develop` → that site’s production branch (`main`, HSD **`production`**). Never `se-core-product` `main`.
+4. `git diff --name-only origin/<productionBranch>...origin/develop` is **only**:
+   - `cms-edit/**`
+   - root `package.json` and/or `pnpm-lock.yaml` (and `pnpm-workspace.yaml` only if it already listed the package)
+5. Those package/lock changes are **only** `@se-studio/contentful-cms` (plus lockfile transitives). No `src/`, `apps/` marketing, smoke, server-config, or other dependency bumps.
+6. Merge **one customer repo at a time**. Wait for that repo’s cms-edit Vercel **production** deployment **Ready**. Then check live `https://<host>/api/health`: `ok`, `cmsEdit.version` matches npm, `redis` and `oauth` checks ok. Probe `/.well-known/oauth-authorization-server` (200). **Stop at the first failure.**
+
+## How to merge
+
+From the **develop** checkout (not `productionPath`):
+
+```bash
+git fetch origin
+git diff --name-only origin/<productionBranch>...origin/develop   # must pass the path gate
+gh pr create --base <productionBranch> --head develop --title "cms-edit: <version or editor-pack>"
+# or ff-only merge via gh
+```
+
+Do **not** use HSD `production-hsd-website` (or any `productionPath`) as the working tree. Do **not** run `pnpm cms-edit:deploy`, `vercel deploy`, or `./scripts/deploy-cms-edit-host.sh`.
+
+## After a successful host
+
+Reconnect Grok `/mcps` → `i` is an editor step if OAuth tokens were dead — not a substitute for the health check.
+
+If the diff is not cms-edit-only, **stop and hand off** — no production merge.

package/references/agent-session/customer-agents-block.md

@@ -0,0 +1,58 @@
+## Agent session workflow
+
+**Load skill `site-workflows-agent-session` at the start of every coding session.**
+
+Default mode for this repo: **site-first**.
+
+### Branch policy
+
+- Agents may commit and push **`develop`** and **`feature/*`**. Customer production (`main`, HSD `production`) only when the **cms-edit-only** gate passes (`se-core-product` `packages/skills/references/agent-session/cms-edit-prod-merge.md`).
+- **Never** merge marketing `src/` to production. **Never** ship from a production checkout (e.g. HSD `production-hsd-website`). Use the develop checkout only.
+- Prefer **draft PRs** to `develop` over direct pushes when `gh` is available.
+
+### Core vs customer placement
+
+Before non-trivial code, run the placement checklist (in the skill). Summary:
+
+| Belongs in… | Examples |
+|-------------|----------|
+| **This repo** (`src/project/*`, `cms-edit/**`) | Brand components, styling, site routing, editor-pack |
+| **Customer shared package** (if monorepo) | Consent/analytics shared across sites in this customer |
+| **`se-core-product`** (`@se-studio/*`) | Fixes/features needed by 2+ sites, CMS infrastructure |
+
+If the checklist says **core**, stop and switch to core-first mode — do not patch `@se-studio` behaviour in this repo.
+
+### Deploy smoke failed?
+
+Do **not** change `baseUrl`, discovery routes, or add `getRequestBaseUrl()` to unblock Vercel Deployment Checks. That fix belongs in `@se-studio/site-check` (core-first).
+
+1. Follow the smoke/deploy failure playbook in `se-core-product` — `packages/skills/references/agent-session/smoke-deploy-failure-playbook.md`
+2. Bump `@se-studio/site-check@2.9.4+` after npm publish (`discovery.urlOrigin: auto`)
+3. Customer-only: curate new URLs in `smoke.cases.json` when CMS routes go live — not package assertion hacks
+
+Record `placement.decision` in `work/active/<feature>.yaml` before smoke/server-config commits aimed at deploy smoke.
+
+### Core release order
+
+When work depends on a new `@se-studio/*` npm release:
+
+1. Release from `se-core-product` (`dev` → CI publish)
+2. Confirm version on npm
+3. `pnpm update @se-studio/<package>@<version> -r` in this repo
+4. Then push `develop`
+
+Never hand-edit `package.json` dependency versions.
+
+### Parallel features
+
+- One feature = one `feature/<scope>/<slug>` branch
+- **Git worktree required** for all feature work — do not implement on the primary `develop` checkout
+  - Path: registry `worktreesRoot` / `<feature-slug>` (see se-core-product `packages/skills/references/agent-session/projects.registry.json`)
+  - Create: `git worktree add <worktreesRoot>/<feature-slug> -b feature/<scope>/<slug> origin/develop`
+  - Manifest must set `worktree:`; opt out only if the user says “work in place” / “no worktree” (`worktree_opt_out: true`)
+- CMS edits: `--session <feature-slug>` (isolate cms-edit sessions)
+- Track in-flight work: manifest at `~/source/se/se-core-product/work/active/<feature>.yaml` (or `work/active/` in this repo if core checkout unavailable)
+
+### Production handoff
+
+When **marketing** work is ready, agents **stop** and hand off. **cms-edit-only** host rollouts may merge `develop` → production one site at a time (health-check, stop at first failure). No `vercel deploy`. See skill Step 7–8 and `cms-edit-prod-merge.md`.

package/references/agent-session/manifest.template.yaml

@@ -0,0 +1,37 @@
+# Copy to work/active/<feature>.yaml — one file per in-flight feature.
+# Canonical location: se-core-product/work/active/ (cross-repo visibility).
+
+feature: my-feature-slug
+mode: site-first # core-first | site-first
+project_key: om1
+primary_repo: ~/source/customers/om1/om1-website
+branch: feature/om1/my-feature-slug
+# REQUIRED for feature/* work — path under registry worktreesRoot (e.g. ~/source/customers/om1/worktrees/my-feature-slug).
+# null only when user explicitly opts out of worktrees in this conversation (record worktree_opt_out: true).
+worktree: ~/source/customers/om1/worktrees/my-feature-slug
+worktree_opt_out: false
+integration_branch: develop
+
+related_repos:
+  - repo: se-core-product
+    path: ~/source/se/se-core-product
+    role: read-only # read-only | pending-extract | active
+
+placement:
+  decision: customer # core | customer | customer-shared | defer-extract
+  rationale: One-site hero layout tied to OM1 Figma
+  extract_to_core: null # pending | null
+  extract_rationale: null
+  # Required before smoke/server-config commits for deploy-smoke goals (agent-session Step 3b):
+  # smoke_edit: null # curated-urls | blocked-on-core | defer-extract
+
+blocked_on: null # e.g. "@se-studio/core-ui@2.1.0"
+cms_session: null # set to feature slug when doing parallel CMS edits
+
+status: in_progress # in_progress | blocked | parked | ready_for_review
+started_at: 2026-07-05
+updated_at: 2026-07-05
+
+validation: []
+
+handoff: null

package/references/agent-session/projects.registry.json

@@ -0,0 +1,96 @@
+{
+  "manifestPath": "work/active/<feature>.yaml",
+  "integrationBranches": {
+    "core": "dev",
+    "customer": "develop"
+  },
+  "branchPattern": "feature/<scope>/<short-slug>",
+  "worktrees": {
+    "requiredForFeatureBranches": true,
+    "pathPattern": "<worktreesRoot>/<feature-slug>",
+    "notes": "Feature work (feature/*) must use a git worktree under the project's worktreesRoot. Primary checkouts stay on integration branches only. Opt out only if the user explicitly says work in place / no worktree in the current conversation."
+  },
+  "projects": [
+    {
+      "key": "se-core-product",
+      "displayName": "SE Core Product",
+      "path": "~/source/se/se-core-product",
+      "worktreesRoot": "~/source/se/worktrees",
+      "branch": "dev",
+      "type": "core",
+      "validate": "pnpm validate",
+      "exampleApps": ["example-empty", "cms-edit-host"]
+    },
+    {
+      "key": "se2026",
+      "displayName": "SE Studio Site",
+      "path": "~/source/se/se-website-2026",
+      "worktreesRoot": "~/source/se/worktrees",
+      "branch": "develop",
+      "type": "customer",
+      "contentfulSpaceId": "g0pw3n92bre6",
+      "hostedMcp": "cms-edit-se-website",
+      "validate": "pnpm check && pnpm type-check"
+    },
+    {
+      "key": "brightline",
+      "displayName": "Brightline Sites",
+      "path": "~/source/customers/brightline/brightline-sites",
+      "worktreesRoot": "~/source/customers/brightline/worktrees",
+      "branch": "develop",
+      "type": "customer-monorepo",
+      "sharedPackage": "@brightline/shared",
+      "contentfulSpaceIds": ["96gdpqkm7elu", "c27ds9epot4n"],
+      "hostedMcp": "cms-edit-brightline",
+      "validate": "pnpm -r validate"
+    },
+    {
+      "key": "om1",
+      "displayName": "OM1 Website",
+      "path": "~/source/customers/om1/om1-website",
+      "worktreesRoot": "~/source/customers/om1/worktrees",
+      "branch": "develop",
+      "type": "customer",
+      "contentfulSpaceId": "ddhe5ahaolzf",
+      "hostedMcp": "cms-edit-om1",
+      "validate": "pnpm check && pnpm type-check && pnpm validate:routes"
+    },
+    {
+      "key": "pointme",
+      "displayName": "PointMe Marketing Site",
+      "path": "~/source/customers/pointme/develop-marketing-site",
+      "worktreesRoot": "~/source/customers/pointme/worktrees",
+      "branch": "develop",
+      "type": "customer",
+      "contentfulSpaceId": "alwdzgjlz5qv",
+      "contentfulEnvironment": "marketing-master-2025-04-15",
+      "validate": "pnpm check && pnpm type-check"
+    },
+    {
+      "key": "pedestal",
+      "displayName": "Pedestal Sites",
+      "path": "~/source/customers/pedestal/pedestal-sites",
+      "worktreesRoot": "~/source/customers/pedestal/worktrees",
+      "branch": "develop",
+      "type": "customer-monorepo",
+      "sharedPackage": "@pedestal/site-common",
+      "contentfulSpaceIds": ["h4s3ip99qawo", "fea4lj2cdgl5"],
+      "hostedMcp": ["cms-edit-pedestal", "cms-edit-headwater"],
+      "validate": "pnpm -r validate"
+    },
+    {
+      "key": "hsd",
+      "displayName": "HopSkipDrive",
+      "path": "~/source/customers/hopskipdrive/develop-hsd-website",
+      "productionPath": "~/source/customers/hopskipdrive/production-hsd-website",
+      "worktreesRoot": "~/source/customers/hopskipdrive/worktrees",
+      "branch": "develop",
+      "productionBranch": "production",
+      "type": "customer",
+      "contentfulSpaceId": "gqa3p93n5wse",
+      "hostedMcp": "cms-edit-hsd",
+      "validate": "pnpm validate",
+      "notes": "Agents work only in path (develop) + feature worktrees under worktreesRoot. productionPath is human-only — never push production from agents."
+    }
+  ]
+}

package/references/agent-session/refuse-customer-patches.md

@@ -0,0 +1,58 @@
+# Refuse customer patches (site-first guardrails)
+
+Agents in **site-first** mode must **refuse** customer-repo changes that belong in **`se-core-product`** (`@se-studio/*`), unless the user explicitly approves **`defer-extract`** in the manifest with `extract_to_core: pending` and a dated extraction plan.
+
+Run this table **in addition to** the placement checklist (`site-workflows-agent-session` Step 3) when the task touches smoke, deploy checks, shared packages, or infra.
+
+## Refusal triggers
+
+| Symptom, file, or request | Correct owner | Agent action (site-first) |
+|---------------------------|---------------|---------------------------|
+| Deploy / `smoke-test:live` failure after bumping `@se-studio/*` | **core** — fix package behaviour | **Stop.** Switch to core-first or set `blocked_on: "@se-studio/<pkg>@<version>"`. Customer only bumps after npm publish. |
+| Discovery smoke (`llms.txt`, `markdown-index.txt`, `cms.txt`, `site-info.md`) origin mismatch on `*.vercel.app` | **core** — `@se-studio/site-check` (`discovery.urlOrigin`) | **Refuse** per-request origin hacks (`getRequestBaseUrl`, `headers()` for `baseUrl`). Bump `site-check@2.9.4+`. |
+| Patching `@se-studio/site-check` expectations in app code | **core** `site-check` | **Refuse.** Open core PR + changeset. |
+| Forking converter / link logic already in `contentful-rest-api` | **core** | **Refuse.** Fix converter or API in core. |
+| `pnpm patch`, `patchedDependencies`, or overrides to fork `@se-studio/*` | **forbidden** | **Refuse** (see root `AGENTS.md`). |
+| New smoke assertion that should apply to all marketing sites | **core** `site-check` | **Refuse** site-only assertion helpers; extend site-check. |
+| `route-build-policy.json` change to hide a core regression (e.g. allow new `ƒ` on CMS routes) | **core** + site routing fix | **Refuse** policy-only workaround; fix why route went dynamic. |
+
+## Allowed customer-only smoke edits
+
+| Change | When |
+|--------|------|
+| Add/remove **curated URLs** in `smoke.cases.json` | New CMS pages, article types, tags/people go live — follow `se-marketing-sites-smoke-test-setup` |
+| Set `discovery` flags to `false` | Site-specific infra (e.g. CloudFront not routing discovery paths yet) |
+| `cmsIntegrity.routing` mapping | Per-site URL calculators — not a package bug |
+| Security **probe** cases (`category: probe`) | Site-specific hardening (see brightline reference) |
+
+## `defer-extract` (escape hatch)
+
+Use only when the user **explicitly** accepts short-term customer code with a core extraction ticket:
+
+1. Manifest `placement.decision: defer-extract`
+2. `extract_to_core: pending` + `extract_rationale` (what moves to which package)
+3. Add `work/tracker.yaml` rollout or `attention` item if multi-site
+4. **Do not** merge to customer `develop` if it blocks other sites on a shared package fix
+
+## Manifest gate
+
+Before committing customer changes to any of:
+
+- `smoke.cases.json`, `route-build-policy.json`
+- `src/lib/server-config.ts`, discovery route handlers (`llms.txt`, `markdown-index.txt`, …)
+- `scripts/smoke-test-*.ts`, `.github/workflows/deployment-smoke.yml`
+
+…when the **stated goal** is “fix deploy smoke” or “fix site-check failure”:
+
+1. Record `placement.decision` and `placement.rationale` in `work/active/<feature>.yaml`
+2. If decision is `core`: **do not commit customer workaround** — switch mode
+3. If decision is `customer`: user must confirm in chat (legitimate site-only URL curation)
+4. If decision is `defer-extract`: user must confirm extraction plan in chat
+
+## Emergency bypass (temporary only)
+
+- `SMOKE_TEST_IGNORE=true` on a single deploy
+- `workflow_dispatch` deployment smoke against a known-good URL
+- Skip Vercel Deployment Check with **human** approval
+
+Never treat emergency bypass as permission to land a permanent customer patch for `@se-studio/*` behaviour.

package/references/agent-session/smoke-deploy-failure-playbook.md

@@ -0,0 +1,80 @@
+# Smoke / deploy failure playbook
+
+When **local smoke**, **`smoke-test:live`**, or **Vercel Deployment Checks** fail, follow this sequence. Do **not** patch customer origin/URL logic to satisfy `@se-studio/site-check` assertions.
+
+Full refusal rules: [`refuse-customer-patches.md`](./refuse-customer-patches.md).
+
+## 1. Classify the failure
+
+Read the failing step and package:
+
+| Failure mentions | Likely owner |
+|------------------|--------------|
+| `discovery`, `llms.txt`, `markdown-index.txt`, `urlOrigin`, canonical origin | `@se-studio/site-check` |
+| `article link integrity`, `cmsIntegrity` | `@se-studio/site-check` + site `routing` config (customer OK) or `contentful-rest-api` (core) |
+| `route-build-policy`, `mustBeSsgOrStatic`, `ƒ` on CMS route | Site introduced dynamic APIs — fix site routing/layout **or** core if shared helper caused it |
+| HTML 404/500 on a **curated** smoke path | Site content/routing or CMS — usually **customer** |
+| Lockfile / install on Vercel | Customer lockfile sync — see `lockfile-sync` reference, not site-check |
+
+## 2. If `@se-studio/*` behaviour is wrong → core-first
+
+1. Set manifest `mode: core-first` (or stop and ask user to switch).
+2. Fix in `packages/<pkg>/`, add **changeset**, run package tests.
+3. Push `dev` → wait for CI npm publish.
+4. Add/update `work/tracker.yaml` **rollout** for customer bumps.
+5. Set customer manifest `blocked_on: "@se-studio/<pkg>@<version>"` until npm confirms.
+
+**Customer repo during wait:** only dependency bump via `pnpm update` — no `baseUrl` / origin / assertion hacks.
+
+## 3. If site content/routing is wrong → site-first
+
+Examples: wrong slug in `smoke.cases.json`, page unpublished, new article type needs a case.
+
+1. Confirm placement `customer`.
+2. Refresh cases from production sitemap (`se-marketing-sites-smoke-test-setup` skill).
+3. Run `pnpm smoke-test:run` locally; `pnpm smoke-test:preview` against develop preview if needed.
+
+## 4. Discovery canonical origin (known anti-pattern)
+
+**Symptom:** Deploy smoke hits `https://<project>-<hash>.vercel.app` but `llms.txt` / `markdown-index.txt` list `https://www.example.com/...` links. Smoke fails origin check.
+
+**Wrong fix (refuse):**
+
+- `getRequestBaseUrl()` from request headers in `server-config` or discovery routes
+- Rewriting discovery output to match deployment host permanently
+
+**Right fix:**
+
+1. Core: `@se-studio/site-check@2.9.4+` with `discovery.urlOrigin: auto` (default in smoke runner).
+2. Customer: `pnpm update @se-studio/site-check@2.9.4 -r`, keep canonical `baseUrl` in app config.
+3. Tracker rollout: `site-check-discovery-canonical` in `work/tracker.yaml`.
+
+## 5. Emergency unblock (human or agent with explicit approval)
+
+| Action | Use when |
+|--------|----------|
+| `workflow_dispatch` deployment smoke | Re-test after core fix + customer bump |
+| `SMOKE_TEST_IGNORE=true` | One-off deploy; document in manifest notes |
+| Human approves blocked Deployment Check | Production promotion already reviewed |
+
+Record what was bypassed and the real fix still required (core PR / npm bump).
+
+## 6. Validate before customer push
+
+| Check | Command |
+|-------|---------|
+| Local HTTP smoke | `pnpm smoke-test:run` |
+| Preview smoke | `pnpm smoke-test:preview` (develop URL + bypass token) |
+| After core bump | `pnpm update @se-studio/site-check@<version> -r` then re-run smoke |
+| Route policy | `pnpm validate:routes` when Contentful creds available in CI |
+
+Deployment checks stay **HTTP-only** — never enable `cmsIntegrity` on Vercel live smoke.
+
+## 7. Handoff
+
+Include in manifest / handoff:
+
+- Root cause (core vs customer)
+- Published package versions required
+- Tracker rollout id
+- Whether any emergency bypass was used

package/references/contentful-cms-cms-guidelines/README.md

@@ -0,0 +1,170 @@
+# CMS Guidelines Generation
+
+This directory contains the pipeline prompts and documentation for generating CMS component guideline fragments for any app in the monorepo.
+
+---
+
+## What are CMS guidelines?
+
+Guidelines are short markdown fragments — one per CMS type — that describe how each component or collection looks, what fields it uses, how colours are applied, and how it behaves. They are merged into `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md`, a single document used to give LLMs accurate context about the app's component library.
+
+---
+
+## Lifecycle: From content to guidelines
+
+1. **Build the site** — implement all components and collections; ensure all content is correct and published in Contentful.
+2. **Generate showcase data** — pull real Contentful data into the app's showcase:
+   ```bash
+   pnpm --filter <appName> generate-showcase
+   ```
+   This writes `src/generated/showcase-examples.json`.
+3. **Curate showcase mocks** — run the [curate-showcase-mocks skill](../../skills/se-marketing-sites-curate-showcase-mocks/SKILL.md) to select the best examples into `showcase-mocks.json`. This makes the showcase (and screenshots) show realistic content.
+4. **Generate field list** — parse TypeScript types to produce structured field metadata:
+   ```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 .
+   ```
+5. **Generate guidelines** — run the [Generate CMS guidelines skill](../../skills/contentful-cms-generate-cms-guidelines/SKILL.md).
+
+Steps 1–3 only need to be repeated when content or component code changes significantly. Step 4 only needs to be repeated when TypeScript types change. Step 5 can be re-run at any time.
+
+---
+
+## How to run guideline generation
+
+Use the Cursor skill at [`../../skills/contentful-cms-generate-cms-guidelines/SKILL.md`](../../skills/contentful-cms-generate-cms-guidelines/SKILL.md). It supports three modes:
+
+| Mode | When to use |
+|---|---|
+| `full` | First-time generation, or regenerate everything |
+| `single` | Regenerate one component after code changes |
+| `merge-only` | Rebuild `COMPONENT_GUIDELINES_FOR_LLM.md` after manual fragment edits |
+
+**Example: full from scratch**
+
+Start the app:
+
+```bash
+pnpm dev
+# Note the port from dev server output, or read devBaseUrl from .contentful-cms.json
+```
+
+Then invoke the skill with:
+
+- App directory: `<appDir>` (e.g. `.` in an external project)
+- Mode: `full`
+- Discovery URL: `http://localhost:<PORT>/api/cms/discovery/`
+
+**Example: single component**
+
+Invoke the skill with:
+
+- App directory: `<appDir>`
+- Mode: `single`
+- Type name: `Hero`
+- Discovery URL: `http://localhost:<PORT>/api/cms/discovery/`
+
+**Example: merge only**
+
+```bash
+cms-merge-guidelines --app-dir apps/example-empty
+```
+
+---
+
+## CLIs used by this pipeline
+
+| CLI | Purpose |
+|---|---|
+| `cms-generate-html-style-guide` | Generate `html-component-style-guide.md` from `tailwind.config.json` + `globals.css` |
+| `cms-generate-field-list` | Parse TypeScript types → `field-list.json` |
+| `cms-capture-screenshots` | Capture component screenshots for variant evaluation |
+| `cms-update-colour-hints` | Upsert a colour hint in `colour-hints.json` |
+| `cms-generate-collection-guidelines` | Generate all collection/external `.md` files from a discovery URL |
+| `cms-merge-guidelines` | Merge all fragments → `COMPONENT_GUIDELINES_FOR_LLM.md` |
+
+All CLIs are provided by `@se-studio/project-build`. Run `pnpm build` from the repo root to ensure they are built and linked.
+
+---
+
+## `cms-generate-html-style-guide`
+
+Generates `docs/cms-guidelines/html-component-style-guide.md` — a design system reference for any LLM or developer authoring HTML in `HtmlComponent` CMS entries.
+
+Does not require a running dev server. Reads only local files:
+- `tailwind.config.json` → colour palette, typography classes, grid configuration
+- `src/app/globals.css` → custom utilities, RTF class names, CSS custom properties
+
+```bash
+# From the app directory:
+pnpm cms-generate-html-style-guide
+```
+
+The output file is a **static fragment** — not generated by the LLM component pipeline. It is automatically included as a preamble in `COMPONENT_GUIDELINES_FOR_LLM.md` when `cms-merge-guidelines` runs. Regenerate it whenever the design system changes.
+
+---
+
+## `cms-generate-collection-guidelines`
+
+New project-independent CLI. Reads the discovery API and writes collection and external guideline fragments without any app-specific hardcoding.
+
+```bash
+cms-generate-collection-guidelines \
+  --discovery-url http://localhost:<PORT>/api/cms/discovery/ \
+  --app-dir <appDir>
+```
+
+Options:
+
+| Flag | Description |
+|---|---|
+| `--discovery-url <url>` | Discovery API URL (required). App must be running. |
+| `--app-dir <path>` | App directory (default: cwd). |
+
+Outputs:
+- `docs/cms-guidelines/collections/<slug>.md` for every collection
+- `docs/cms-guidelines/externals/<slug>.md` for every external
+- Updates `generated/cms-discovery/colour-hints.json`
+
+---
+
+## Pipeline document index
+
+| File | Purpose |
+|---|---|
+| `generate-component-guidelines.md` | Full pipeline overview: Phases A–F |
+| `variant-loop.md` | Phase A: propose variants → screenshot → evaluate |
+| `variant-proposal-prompt.md` | LLM prompt: propose showcase variants |
+| `evaluation-prompt.md` | LLM prompt: evaluate screenshot diversity |
+| `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 guideline validation |
+
+---
+
+## Output files (per app)
+
+```
+<appDir>/
+  docs/cms-guidelines/
+    html-component-style-guide.md     # design system reference (auto-generated; static fragment)
+    components/          # one .md per componentType
+    collections/         # one .md per collectionType
+    externals/           # one .md per externalComponentType
+    COMPONENT_GUIDELINES_FOR_LLM.md   # merged document (includes style guide as preamble)
+  generated/cms-discovery/
+    field-list.json
+    colour-hints.json
+    accepted-variants/
+      components/        # one .json per component type
+      collections/       # one .json per collection type
+      externals/         # one .json per external component type
+    screenshots/
+      components/        # PNG screenshots for components
+      collections/       # PNG screenshots for collections
+      externals/         # PNG screenshots for externals
+      index.json         # file field uses subpath e.g. "components/hero-default.png"
+```