@se-studio/skills 1.7.10 → 1.7.12

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/skills
 
+## 1.7.12
+
+### Patch Changes
+
+- 76bc91c: Document Darwin hoisted-frozen install (clean tree, no win32 architectures) and require `next typegen` before `tsc` for typed-route PageProps.
+
+## 1.7.11
+
+### Patch Changes
+
+- 1e65f12: Generated theme lookups return `undefined` (and warn when `LOG_CMS=1`) instead of throwing on unknown CMS names. `lookupTextStyleClassName` is now `string | undefined` — treat the result as optional, do not concatenate it. Tailwind `@source` should scan core-ui `src/**/*.tsx` plus `dist/**/*.js`, not the whole `dist` tree.
+
 ## 1.7.10
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.7.10",
+  "version": "1.7.12",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",

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

@@ -113,7 +113,7 @@
       "contentfulSpaceId": "bkkox68g99rn",
       "hostedMcp": "cms-edit-highlander",
       "validate": "pnpm check && pnpm type-check && pnpm validate:routes",
-      "notes": "2026 stack is live on Vercel (develop preview, main production alias). Public DNS is still Bond/Netlify highlanderhealth.com until cutover. cms-edit DNS/OAuth for highlander.content.se.studio is a human gate."
+      "notes": "2026 stack is live on Vercel (develop preview, main production alias). Public DNS is still Bond/Netlify highlanderhealth.com until cutover. Hosted cms-edit: https://highlander.content.se.studio (Git production branch main)."
     }
   ]
 }

package/references/lockfile-sync/README.md

@@ -34,9 +34,12 @@ See [`validate-workflow-snippet.yml`](validate-workflow-snippet.yml). Customer m
 
 cms-edit Vercel and `check-lockfile-sync.sh` (full) run `pnpm install --frozen-lockfile --config.node-linker=hoisted`. That path requires lockfile snapshots for **linux-x64/glibc** optional binaries even when you generate the lockfile on macOS.
 
-Every consumer `pnpm-workspace.yaml` must include `supportedArchitectures` (current + linux, current + x64, current + glibc). Canonical copy: skill `site-workflows-deps-update` Step 3. After adding it, run `pnpm install` (not frozen) so the lockfile gains those snapshots, then verify:
+Every consumer `pnpm-workspace.yaml` must include `supportedArchitectures` (current + linux, current + x64, current + glibc). Canonical copy: skill `site-workflows-deps-update` Step 3. After adding it, run `pnpm install` (not frozen) so the lockfile gains those snapshots, then verify.
+
+**Local Darwin:** never run hoisted frozen on top of an isolated `node_modules`. That yields `ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY` for `@next/swc-win32-*`. Next lists every platform SWC as optional; we do **not** add `win32` to `supportedArchitectures`. Ubuntu CI `lockfile-hoisted` is authoritative.
 
 ```bash
+rm -rf node_modules
 pnpm install --frozen-lockfile --config.node-linker=hoisted
 pnpm install   # restore isolated linker for local workspace packages
 ```
@@ -62,5 +65,6 @@ Apply the full stack when touching deps or CI in each repo:
 | se-website-2026 | yes | develop | yes | yes | yes |
 | pointme | yes | develop | yes | yes | yes |
 | hsd (`develop-hsd-website`; prod human-only: `production-hsd-website`) | yes | develop (+ `extended-port`) | yes | yes | yes |
+| highlander-health-website-2026 | yes | develop | yes | yes | yes |
 
 Update this table as repos adopt the pattern. Every cms-edit host `pnpm-workspace.yaml` must include `supportedArchitectures` (current + linux, x64, glibc).

package/skills/coding-discipline/SKILL.md

@@ -0,0 +1,411 @@
+---
+name: coding-discipline
+description: Behavioral guidelines to reduce common LLM coding mistakes in se-core-product. Use when writing or reviewing application code, not for CMS copy or one-line fixes.
+---
+
+# CLAUDE.md - AI Assistant Guide
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+
+
+
+This file provides guidance for AI assistants (Claude, Cursor, Copilot) working with this codebase.
+
+## Quick Start
+
+This is a **TypeScript monorepo** for building **Next.js 16 marketing sites** with **Contentful CMS**. Customer sites are on Next 16.3; `@se-studio/*` packages still declare peer `next` `>=15.5.0 <17` for older installs.
+
+```bash
+pnpm install    # Install dependencies
+pnpm build      # Build all packages (required before dev)
+pnpm dev        # Run development mode
+pnpm test       # Run tests
+pnpm format     # Format code with Biome
+```
+
+## Command Reference
+
+Use these commands from the **repository root**:
+
+| Task | Command |
+|------|---------|
+| Install dependencies | `pnpm install` |
+| Build all packages (required before dev) | `pnpm build` |
+| Run dev (packages) | `pnpm dev` |
+| Run a specific app | `pnpm --filter example-empty dev` (https://example.localhost), `pnpm --filter cms-edit-host dev` (https://cms-edit.localhost — template only; SE Studio prod: `se-website-2026/cms-edit/host`). Customer sites run from their own repos — see `docs/RELATED_PROJECTS.md`. |
+| Run all apps (except ignored) | `pnpm dev:apps` or `cd apps && pnpm dev` (ignore via `SITEMAP_VALIDATE_IGNORE=true` in app’s `.env.local`) |
+| Sitemap validate (prod vs portless `pnpm dev`) | Per app: `pnpm sitemap-validate` in app dir (needs `portless service install` + `pnpm dev`). Bulk: `pnpm sitemap-validate:all`. Set `SITEMAP_PROD_URL` in `.env.local`; build site-check first. |
+| Smoke test (local) | Per app: `pnpm smoke-test` (`dev:dev` + HTTP on localhost port), `pnpm smoke-test:audit`, `pnpm smoke-test:cache` (`start:dev`). Uses `smoke.cases.json`; no Contentful. Regenerates: skill `se-marketing-sites-smoke-test-setup`. Set `SMOKE_TEST_IGNORE=true` to skip. |
+| Smoke test (preview) | Per app: `pnpm smoke-test:preview` — curated HTTP checks against Vercel preview via `runPreviewStaticSmokeTest` (no local server). Requires `PREVIEW_SITE_URL` and `VERCEL_PROTECTION_BYPASS_TOKEN` in `.env.local`. Same `smoke.cases.json` as local smoke. |
+| Run all tests | `pnpm test` |
+| Test a specific package | `pnpm --filter @se-studio/core-ui test` |
+| Format code | `pnpm format` |
+| Type-check (packages + apps) | `pnpm type-check` |
+| Lint | `pnpm lint` |
+| Full validation (circular imports, skills, format, type-check) | `pnpm validate` |
+| Validate skill frontmatter (Claude Code) | `pnpm skills:validate` |
+| Sync skills to `.agents/skills/` | `pnpm skills:sync` |
+| Worktree `.env.local` (canonical store, seed, audit, 1Password backup) | `pnpm --dir ~/source/se/se-core-product local-env seed --project <key>` — see `packages/skills/references/agent-session/local-env.md` |
+
+## Guides for Common App Tasks
+
+Step-by-step guides are available as **Cursor skills**. Use them when creating or changing app-level features so you follow the right patterns and don't miss steps (e.g. registration).
+
+| Task | Skill / doc |
+|------|-------------|
+| **Agent session** (core vs customer, parallel features, handoff) | `.agents/skills/site-workflows-agent-session/SKILL.md`, `docs/WORKFLOW.md` |
+| **Worktree `.env.local`** | `packages/skills/references/agent-session/local-env.md`, `pnpm --dir ~/source/se/se-core-product local-env seed --project <key>` |
+| Create a new **CMS component** (app) | `.agents/skills/se-marketing-sites-create-component/SKILL.md` |
+| Create a new **collection** (app) | `.agents/skills/se-marketing-sites-create-collection/SKILL.md` |
+| Create a new **page** or route | `.agents/skills/se-marketing-sites-create-page/SKILL.md`, `.agents/skills/se-marketing-sites-cms-routes-and-appshared/SKILL.md` |
+| **Register** components/collections | `.agents/skills/se-marketing-sites-register-cms-features/SKILL.md` |
+**Editor-managed redirects** (rebuild pattern + migrations) | `.agents/skills/se-marketing-sites-redirects/SKILL.md` |
+| **Media** (images, videos, animations) | `.agents/skills/se-marketing-sites-handling-media/SKILL.md` |
+| **Styling** (typography, colours, grids) | `.agents/skills/se-marketing-sites-styling-system/SKILL.md` |
+| **Lib/CMS structure** (cms.ts, registrations) | `.agents/skills/se-marketing-sites-lib-cms-structure/SKILL.md` |
+| **Sync Contentful schema** to core (golden diff, migration runbook) | `.agents/skills/contentful-cms-sync-schema/SKILL.md`, `docs/schema-audit/` |
+| **Edit CMS content** (pages, components, articles) | `.agents/skills/contentful-cms-core/SKILL.md` |
+| **CMS guidelines — orchestration** (full **fresh** clean regen vs **sync** incremental + stale removal vs **merge-only**) | `.agents/skills/contentful-cms-update-cms-guidelines/SKILL.md` — if the user is vague (“regenerate guidelines”), confirm **fresh** vs **sync** before acting |
+| **CMS guidelines — fragments** (full / single / merge-only; prefer **update-cms-guidelines** for true total regeneration) | `.agents/skills/contentful-cms-generate-cms-guidelines/SKILL.md` |
+
+**Skills — canonical source and sync:** All SE Studio skills live in **`packages/skills/skills/`** (the `@se-studio/skills` npm package). **In the monorepo**, edit sources there, run **`pnpm skills:validate`**, then **`pnpm skills:sync`** to copy into **`.agents/skills`**. The repo root keeps **`.cursor/skills`** as a **symlink** to **`.agents/skills`**. **External projects** install skills via the `skills` CLI: `npx skills add @se-studio/skills`. Do not edit skills under **`.agents/skills`** by hand. Frontmatter rules: [`packages/skills/README.md`](packages/skills/README.md).
+
+See also **docs/AI_QUICK_REFERENCE.md** for a short task → doc/skill index.
+
+## Package Dependency Graph
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                                APPS                                           │
+│   ┌─────────────────┐  ┌─────────────────┐  (+ customer sites in separate repos) │
+│   │  example-empty  │  │  cms-edit-host  │  see docs/RELATED_PROJECTS.md        │
+│   │ example.localhost│  │ cms-edit.localhost│                                        │
+│   └────────┬────────┘  └────────┬────────┘                                        │
+│            └────────────────────┘                                                 │
+│                        ▼                                                                                        │
+├─────────────────────────────────────────────────────────────────┤
+│                       PACKAGES                                   │
+│                                                                  │
+│   ┌──────────────────────────────────────────────────────────┐  │
+│   │                      core-ui                             │  │
+│   │  React components, CMS rendering, analytics              │  │
+│   └─────────────────────────┬────────────────────────────────┘  │
+│                             │                                   │
+│         ┌───────────────────┼────────────────────┐              │
+│         ▼                   ▼                    ▼              │
+│   ┌─────────────────┐ ┌─────────────────────┐ ┌──────────────┐ ┌────────────────┐ │
+│   │ contentful-     │ │   project-build     │ │ ab-testing   │ │    skills      │ │
+│   │ rest-api        │ │   Build tools,      │ │ A/B testing  │ │ Agent skills   │ │
+│   │ CDA/CPA client  │ │   Tailwind, CLI     │ │ framework    │ │ (@se-studio/   │ │
+│   └────────┬────────┘ └─────────────────────┘ └──────┬───────┘ │  skills)       │ │
+│            │                                          │         └────────────────┘ │
+│            │                                          │         │
+│            │                                          │         │
+│            ▼                                          │         │
+│   ┌───────────────────────────────────────────────────────────▼─────┐   │
+│   │                   core-data-types                       │   │
+│   │  TypeScript types, interfaces, type guards              │   │
+│   │  (No runtime dependencies - pure types)                 │   │
+│   └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+│   ┌─────────────────────────────────────────────────────────┐   │
+│   │                  markdown-renderer                      │   │
+│   │  Utilities for converting Contentful to Markdown        │   │
+│   │  (Depends on contentful-rest-api, core-data-types)      │   │
+│   └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+│   ┌─────────────────────────────────────────────────────────┐   │
+│   │                      search                             │   │
+│   │  AI-powered site search with Upstash Search             │   │
+│   │  (Depends on contentful-rest-api, core-data-types,      │   │
+│   │   markdown-renderer, @upstash/search)                   │   │
+│   └─────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Key Files to Understand
+
+| File | Purpose |
+|------|---------|
+| `packages/core-data-types/src/index.ts` | All shared type exports |
+| `packages/contentful-rest-api/src/api.ts` | Contentful API functions |
+| `packages/contentful-rest-api/src/converters/` | Entry-to-model converters |
+| `packages/core-ui/src/components/CmsContent.tsx` | Main CMS renderer |
+| `packages/core-ui/CMS_INFRASTRUCTURE.md` | CMS system documentation |
+| `packages/ab-testing/src/middleware/index.ts` | A/B testing middleware handler |
+| `packages/search/src/types.ts` | Search types and configuration |
+| `packages/search/src/indexing/rebuild.ts` | Full search index rebuild |
+| `packages/search/src/webhook/handler.ts` | Webhook-driven search index updates |
+| `packages/markdown-renderer/src/MarkdownConverter.ts` | Contentful to Markdown logic |
+| `turbo.json` | Build pipeline configuration |
+| `biome.json` | Code style rules |
+
+## Common Tasks
+
+### Adding a New Content Type
+
+1. **Define types** in `core-data-types/src/types/`
+2. **Export types** from `core-data-types/src/index.ts`
+3. **Create converter** in `contentful-rest-api/src/converters/`
+4. **Add API function** in `contentful-rest-api/src/api.ts`
+5. **Create renderer** in the app's components
+
+### Adding a New UI Component (in core-ui package)
+
+For **shared package** components (used across apps):
+
+1. Create component in `packages/core-ui/src/components/`
+2. Export from `packages/core-ui/src/index.ts`
+3. Add tests in `packages/core-ui/src/__tests__/`
+4. Document props with JSDoc
+
+### Adding a New CMS Component (in an app)
+
+For **app-level** components that render CMS content (Hero, CTA, etc.):
+
+1. Use the **create-component** skill: `.agents/skills/se-marketing-sites-create-component/SKILL.md`
+2. Follow the four-layer pattern (Core, Wrapper, Renderer, Registration) and the template there
+3. **Register** the component in the app's `src/lib/registrations.ts` (add to `componentRegistrationsList`). The **register-cms-features** skill describes this; missing registrations cause a type error in `cms.ts` via `buildComponentRecord`.
+4. Ensure the `name` in `defineComponent` matches the CMS `componentType` exactly (name is defined once in the registration).
+
+### Heading hierarchy
+
+Use `Element` from `getSizingInformation(index)` for the main heading of each component/collection; use `ChildElement` for headings of items inside a collection. Render **preHeading** and **postHeading** as `<p>` with a typography class, never as heading tags. See `.cursorrules` (Heading and pre/post rules) and the create-component skill.
+
+### Fetching Contentful Data
+
+```typescript
+import { contentfulPageRest } from '@se-studio/contentful-rest-api';
+
+const page = await contentfulPageRest(
+  {
+    spaceId: process.env.CONTENTFUL_SPACE_ID!,
+    accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
+    environment: 'master',
+  },
+  'home', // slug
+  {
+    preview: false,
+    cache: { tags: ['page#home'], revalidate: 3600 }
+  }
+);
+```
+
+### Rendering CMS Content
+
+```tsx
+import { CmsContent } from '@se-studio/core-ui';
+
+<CmsContent
+  content={page}
+  config={rendererConfig}
+  context={{ pageLink: { slug: page.slug, title: page.title } }}
+/>
+```
+
+## TypeScript Patterns
+
+### Type Guards (Runtime Type Checking)
+```typescript
+import { isPage, isComponent, isImage } from '@se-studio/core-data-types';
+
+if (isPage(content)) {
+  console.log(content.slug); // TypeScript knows content is IBasePage
+}
+```
+
+### Strict Index Access
+The project uses `noUncheckedIndexedAccess`, so array/object index access returns `T | undefined`:
+```typescript
+const items = ['a', 'b', 'c'];
+const first = items[0]; // string | undefined - must handle undefined!
+if (first) {
+  console.log(first.toUpperCase()); // Now safe
+}
+```
+
+### Component Props Pattern
+```typescript
+// Define explicit prop types for presentational components
+export interface HeroProps {
+  heading: string | null;
+  body: unknown;
+  visual: IResponsiveVisual | undefined;
+}
+
+// Extract props in the renderer
+export const HeroRenderer: ComponentRenderer<ProjectConfig> = ({ information }) => {
+  return <HeroCore 
+    heading={information.heading}
+    body={information.body}
+    visual={information.visual}
+  />;
+};
+```
+
+## Code Style Requirements
+
+- **Styling**: Tailwind only. Do not use CSS modules (`*.module.css`). Use Tailwind classes or `src/app/globals.css` for shared styles.
+- **Biome** for linting/formatting (not ESLint/Prettier)
+- Single quotes, semicolons, trailing commas
+- `import type` for type-only imports
+- `node:` protocol for Node.js built-ins
+- 100 character line width
+
+Run `pnpm format` before committing.
+
+## Testing
+
+```bash
+pnpm test                                    # Run all tests
+pnpm --filter @se-studio/core-ui test       # Test specific package
+```
+
+Tests use **Vitest** and live in `__tests__/` directories.
+
+## Environment Setup
+
+**Worktrees:** `.env.local` is gitignored and will be missing after `git worktree add`. Seed from `~/source/local-env` with `pnpm --dir ~/source/se/se-core-product local-env seed --project <key>`. Do not invent a stub file or symlink at develop. Details: `packages/skills/references/agent-session/local-env.md`.
+
+Apps need these environment variables in `.env.local`:
+
+```bash
+CONTENTFUL_SPACE_ID=your-space-id
+CONTENTFUL_ACCESS_TOKEN=your-delivery-token
+CONTENTFUL_PREVIEW_ACCESS_TOKEN=your-preview-token
+CONTENTFUL_ENVIRONMENT=master
+```
+
+### Optional: Verbose logging
+
+Uncomment in `.env.local` (or `.env.example`) to enable detailed console output from specific subsystems (silent by default):
+
+```bash
+# LOG_CMS=1          # Contentful fetching, resolution, revalidation, unknown component/collection types, unknown colour/text-style names
+# LOG_SVG_SPRITE=1   # SVG icon processing and sprite generation warnings
+```
+
+## Server vs Client: cms-server
+
+- **Do not import `cms-server` (or `@/lib/cms-server`) in files that have `'use client'`.** That module is server-only (Contentful config). Client components must not import it; pass server-rendered content as `children` from server components instead.
+- **Do not import preview/fetch helpers from `cms-server` in components or collections.** That causes circular dependencies (registrations → components → cms-server → registrations). Use `getPreviewFieldProps(rendererConfig, id, fieldId)` and `getPreviewResponsiveVisualFieldProps(rendererConfig, id, 'visual', 'mobileVisual')` from `@se-studio/core-ui`, and `rendererConfig?.fetchHelpers` for data. Pass `previewHelpers` to `<Section>` and `rendererConfig` to `<SectionLinks>`.
+- Each app's `cms-server.ts` has `import 'server-only'`. If a client component imports it, the build will fail with a clear "cannot be imported from a Client Component" error. See `docs/SERVER_CLIENT_BOUNDARIES.md`.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| "Cannot find module '@se-studio/...'" | Run `pnpm build` from root |
+| "Cannot find name 'PageProps'" in example-empty | `typedRoutes` defines `PageProps` in `.next/types/routes.d.ts`. `pnpm --filter example-empty type-check` runs `next typegen` first. Delete a stale `apps/example-empty/.tsbuildinfo` if tsc still misses it. |
+| Port already in use / `.localhost` not on 443 | Install `portless service install`. `pnpm dev` uses named URLs. Smoke still uses localhost:3014 via `dev:dev`. Customer sites: `docs/RELATED_PROJECTS.md` |
+| Contentful 401 error | Check access token and space ID |
+| "This module cannot be imported from a Client Component" | You imported `cms-server` (or a file that uses it) in a `'use client'` file. Move content rendering to a server component and pass it as `children`. |
+
+## Keeping Documentation Updated
+
+When making changes, update the relevant documentation:
+
+| Change | Update |
+|--------|--------|
+| New content type | `specs/CONTENT_MODEL.md` |
+| New component pattern | `specs/COMPONENT_PATTERNS.md` |
+| New API function | `packages/contentful-rest-api/README.md` and `packages/contentful-rest-api/docs/llms.md` |
+| New package | `README.md`, `CLAUDE.md`, `docs/ARCHITECTURE.md` |
+| New app | `README.md`, `CLAUDE.md`, `docs/DEVELOPMENT.md`, `docs/ARCHITECTURE.md`, port list |
+| New env variable | All `.env.example` files |
+| Workflow change | `docs/DEVELOPMENT.md`, `docs/WORKFLOW.md` |
+| Worktree / local env handling | `packages/skills/references/agent-session/local-env.md` |
+
+**Documentation locations:**
+- `docs/` - Architecture and development guides
+- `specs/` - Content model and component specifications
+- `packages/*/README.md` - Package-specific docs (human-facing)
+- `packages/*/docs/llms.md` - LLM-optimised quick-reference per package (also published to npm)
+- `.cursorrules` - AI conventions (update if patterns change)
+
+## Links
+
+- [Related Projects](./docs/RELATED_PROJECTS.md) – Client and studio projects that consume these packages (Contentful space IDs, environments, repo paths)
+- [AI Quick Reference](./docs/AI_QUICK_REFERENCE.md) – Task → doc/skill index for common app tasks
+- [GitHub issues implementation status](./docs/GITHUB_ISSUES_IMPLEMENTATION_STATUS.md) – closed issues mapped to code; open backlog summary
+- [Content Structure Guide](./docs/CONTENT_STRUCTURE_GUIDE.md) – Content author guide for CMS workflows
+- [Server vs Client Boundaries](./docs/SERVER_CLIENT_BOUNDARIES.md) – cms-server rule and pattern
+- [core-ui package export boundaries](./packages/core-ui/docs/PACKAGE_EXPORT_BOUNDARIES.md) – main vs `/server` entry; prevent client bundle CMS leaks
+- [Contentful webhook revalidation](./docs/CONTENTFUL_WEBHOOK_REVALIDATION.md) – Contentful webhooks for cache revalidation
+- [CMS Infrastructure Guide](./packages/core-ui/CMS_INFRASTRUCTURE.md)
+- [Contentful REST API Docs](./packages/contentful-rest-api/README.md) — LLM ref: [docs/llms.md](./packages/contentful-rest-api/docs/llms.md)
+- [Core Data Types Docs](./packages/core-data-types/README.md) — LLM ref: [docs/llms.md](./packages/core-data-types/docs/llms.md)
+- [Core UI Docs](./packages/core-ui/README.md) — LLM ref: [docs/llms.md](./packages/core-ui/docs/llms.md)
+- [A/B Testing Docs](./packages/ab-testing/README.md) — LLM ref: [docs/llms.md](./packages/ab-testing/docs/llms.md)
+- [HubSpot Docs](./packages/hubspot/README.md) — LLM ref: [docs/llms.md](./packages/hubspot/docs/llms.md)
+- [Search Docs](./packages/search/README.md) — LLM ref: [docs/llms.md](./packages/search/docs/llms.md)
+- [Markdown Renderer Docs](./packages/markdown-renderer/README.md) — LLM ref: [docs/llms.md](./packages/markdown-renderer/docs/llms.md)
+- [Contentful CMS CLI Docs](./packages/contentful-cms/README.md)
+
+### For consuming projects (in node_modules)
+
+When working in a project that installs `@se-studio` packages, tell LLMs to read the relevant doc in `node_modules/`:
+
+- `node_modules/@se-studio/contentful-rest-api/docs/llms.md`
+- `node_modules/@se-studio/core-data-types/docs/llms.md`
+- `node_modules/@se-studio/core-ui/docs/llms.md`
+- `node_modules/@se-studio/ab-testing/docs/llms.md`
+- `node_modules/@se-studio/hubspot/docs/llms.md`
+- `node_modules/@se-studio/search/docs/llms.md`
+- `node_modules/@se-studio/markdown-renderer/docs/llms.md`
+
+These are the source of truth — training data is outdated. See the example app `AGENTS.md` files for the ready-to-copy block.

package/skills/contentful-cms-core/SKILL.md

@@ -31,7 +31,8 @@ Use this skill when you need to read or edit content in Contentful using **hoste
 All `save` operations create **draft** versions. A human must review and publish in Contentful.
 
 **Assets:** Upload **is** supported (`asset upload`). Default workflow: **search and reuse** existing assets first (`index sync` → `asset search`). When uploading:
-- **Hosted MCP:** always `cms_edit_request_staged_upload` → curl → `asset upload --staged` (never `--base64`)
+- **Raster/video:** `cms_edit_request_staged_upload` → curl → `cms_edit_media` prepare (`stagedUploadIds`) → wait → catalog → import with real alt. Never `asset upload --staged/--url/--base64` for jpeg/png/webp/gif/mp4.
+- **SVG/PDF/Lottie:** `cms_edit_request_staged_upload` → curl → `asset upload --staged` (never `--base64`)
 - Use a **sensible fileName** and **descriptive title** (and alt text where the site uses it)
 - Avoid oversized images — width over **2000px** is usually wasteful for web (exact limits vary by project; check `asset audit` / media review guidance)
 - Prefer `--if-exists-by-filename` to avoid duplicates
@@ -371,13 +372,8 @@ cms-edit asset search "hero background"
 cms-edit asset search --filename istockphoto-123.jpg
 cms-edit asset search --filename-match 'istockphoto-.*'
 
-# Local CLI — URL or base64 (hosted MCP rejects --base64)
-cms-edit asset upload --url https://example.com/image.jpg --if-exists-by-filename
-cms-edit asset upload --base64 "$B64" --mime image/png --file-name poster.png
-
-# Hosted MCP — always staged upload for binary files
-# cms_edit_request_staged_upload → curl uploadUrl → consumeArgs
-# cms_edit ["asset", "upload", "--staged", "<uploadId>", "--mime", "image/png", "--file-name", "photo.png"]
+# Raster/video: cms_edit_media prepare → wait → catalog → import (video: import only).
+# SVG/PDF/Lottie: cms_edit_request_staged_upload → curl → asset upload --staged
 
 # Upload and create a Media wrapper in one step (--media-name defaults to asset title)
 cms-edit asset upload ./figure.png --with-media --media-position Middle

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

@@ -36,6 +36,16 @@ export default function CmsRoutesLayout({ children }: { children: React.ReactNod
 
 Base paths come from `@/lib/constants` (e.g. ARTICLES_BASE = `/learning-hub` or `/articles`).
 
+## Type-check (typed routes)
+
+Next 16 puts `PageProps` in `.next/types`. A cold worktree has no `.next`, so bare `tsc --noEmit` fails on CMS `page.tsx`. Marketing apps must use:
+
+```json
+"type-check": "next typegen && tsc --noEmit --incremental false"
+```
+
+Keep committed `next-env.d.ts` importing `./.next/types/routes.d.ts` and `./.next/types/root-params.d.ts` — not `.next/dev/types` (that path is from `next dev`). Do not commit Next rewriting those imports to double quotes if Biome uses single quotes.
+
 ## appShared Modules
 
 Route files are thin wrappers. Logic lives in `src/appShared/`:

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

@@ -55,7 +55,9 @@ Route files are thin wrappers. Data-fetching and rendering logic lives in `src/a
 Each route page extracts params and delegates to the appropriate appShared function:
 
 ```typescript
+import { joinCmsPathSegments } from '@se-studio/core-ui';
 import type { ResolvingMetadata } from 'next';
+import { notFound } from 'next/navigation';
 import { generatePage, generatePageMetadata } from '@/appShared/pageShared';
 
 export function generateStaticParams() {
@@ -64,8 +66,11 @@ export function generateStaticParams() {
 
 async function extractDetails(props: PageProps<'/[level1]'>) {
   const params = await props.params;
-  const { level1 } = params;
-  return { slug: level1, path: `/${level1}/` };
+  const slug = joinCmsPathSegments(params.level1);
+  if (!slug) {
+    notFound();
+  }
+  return { slug, path: `/${slug}/` };
 }
 
 export async function generateMetadata(props: PageProps<'/[level1]'>, parent: ResolvingMetadata) {
@@ -134,6 +139,7 @@ Direct visits to a variant's own CMS URL (normal `[...slugs]` route) continue to
 
 ```typescript
 import { findCanonicalPath } from '@se-studio/ab-testing';
+import { joinCmsPathSegments } from '@se-studio/core-ui';
 import type { ResolvingMetadata } from 'next';
 import { notFound } from 'next/navigation';
 import { testsByPath } from '@/generated/abTests';
@@ -155,7 +161,10 @@ export function generateStaticParams() {
 
 async function extractDetails(props: PageProps<'/page-test/[...slugs]'>) {
   const params = await props.params;
-  const slug = params.slugs.join('/');
+  const slug = joinCmsPathSegments(params.slugs);
+  if (!slug) {
+    notFound();
+  }
   return { slug, path: `/page-test/${slug}/` };
 }
 

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

@@ -17,6 +17,19 @@ The `tailwind.config.json` file in your app's root directory defines the followi
 
 These configurations are processed by the build system to generate utility classes and TypeScript helpers.
 
+## Tailwind `@source` (core-ui)
+
+In `src/app/globals.css`:
+
+```css
+@source "../../node_modules/@se-studio/core-ui/src/**/*.tsx";
+@source "../../node_modules/@se-studio/core-ui/dist/**/*.js";
+```
+
+Do **not** `@source` the whole `dist` tree — that includes `*.map` source maps and makes `next dest` heavier. Scan `src/**/*.tsx` so monorepo workspace links pick up showcase/media-library classes without a core-ui rebuild; on npm that glob is a no-op (`src` is not published). Scan `dist/**/*.js` for the compiled package.
+
+Unknown CMS colour / text-style names must not throw; generated lookups return `undefined`. Set `LOG_CMS=1` to log misspelled names.
+
 ## Typography
 
 Typography utility classes (e.g., `h1`, `h2`, `p1`, `p2`) are automatically generated from the `fontTable` in `tailwind.config.json`.
@@ -66,6 +79,7 @@ Colors are defined in `colorOptions` within `tailwind.config.json`. The build sy
     // Returns "bg-primary-blue text-white" (if White is opposite of Primary Blue)
     lookupColourClassNames('Primary Blue')
     ```
+    Unknown CMS names return `undefined` (no page crash). Set `LOG_CMS=1` to warn.
 
 ## Grid System
 

package/skills/site-workflows-deps-update/SKILL.md

@@ -208,12 +208,16 @@ rg '"node"' package.json apps/*/package.json packages/*/package.json 2>/dev/null
 
 ## Step 6 — Validate (unified for all repos)
 
-If the registry project has `cms-edit/host` in `pnpm-workspace.yaml`, run the frozen hoisted install check first:
+If the registry project has `cms-edit/host` in `pnpm-workspace.yaml`, run the frozen hoisted install check first. **Do not** mix an isolated-linker `node_modules` with hoisted frozen — on Darwin that fails with `ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY` for `@next/swc-win32-*` (Next lists every platform SWC as optional; `supportedArchitectures` does not include win32). Ubuntu CI `lockfile-hoisted` is the source of truth. Locally:
 
 ```bash
+rm -rf node_modules
 pnpm install --frozen-lockfile --config.node-linker=hoisted
+pnpm install   # restore isolated linker for day-to-day work
 ```
 
+Do **not** add `win32` to `supportedArchitectures` to make Mac hoisted pass.
+
 Always run the patches check **once**, then the project validate from the registry:
 
 ```bash
@@ -284,6 +288,7 @@ See [`references/lockfile-sync/README.md`](../../references/lockfile-sync/README
 | Issue | Action |
 |-------|--------|
 | `ERR_PNPM_OUTDATED_LOCKFILE` on frozen/hoisted install | `package.json` and `pnpm-workspace.yaml` overrides out of sync with lockfile — re-run `pnpm update` for the package and align `overrides` |
+| `ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY` (`@next/swc-win32-*`) on Darwin hoisted frozen | Isolated `node_modules` mixed with hoisted linker — `rm -rf node_modules`, hoisted frozen, then `pnpm install`. Do not add win32 to `supportedArchitectures`. Trust Ubuntu `lockfile-hoisted` |
 | `ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY` (`rollup-linux-*`, Sharp, etc.) on hoisted frozen install | Missing `supportedArchitectures` (current + linux, x64, glibc) — add the Step 3 block, run `pnpm install`, then re-verify hoisted |
 | `next` or `@types/node` still outdated to wrong major | Re-run overrides + safety re-pin; check `pnpm-workspace.yaml` overrides |
 | Non-`@se-studio` package still outdated after update | Likely within 24h of npm publish — wait and re-run; **do not** bypass `minimumReleaseAge` |