@comet/agent-features 9.0.0-beta.5

package/skills/comet-block/references/registration.md

@@ -0,0 +1,167 @@
+# Block Registration Patterns
+
+"Registering a block" means adding it to a **blocks block** (`createBlocksBlock`) so editors can select and use it in a content area. A newly created block is not available in the admin UI until it is registered in at least one blocks block. Registration must happen consistently across all three layers (API, Admin, Site).
+
+---
+
+## Registration Targets
+
+Most Comet projects have a hierarchy of blocks blocks:
+
+| Target                    | Purpose                                                                                                     | Typical Includes                                                                                                        |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **PageContentBlock**      | Top-level page content area. Editors build page content by adding blocks here.                              | All general-purpose blocks, including `columns`, `contentGroup`, `pageTreeIndex`, and any full-width page-level blocks. |
+| **ContentGroupBlock**     | A grouped content section with a shared background color or visual wrapper. Used inside `PageContentBlock`. | Same as `PageContentBlock`, minus `contentGroup` (no self-nesting), `pageTreeIndex`, and page-level-only blocks.        |
+| **ColumnsContentBlock**   | Content inside a single column of a `ColumnsBlock`. More restricted due to limited width.                   | Reduced set: `accordion`, `anchor`, `richText`, `space`, `heading`, `callToActionList`, `media`.                        |
+| **AccordionContentBlock** | Content inside an accordion item. Very restricted.                                                          | Minimal set: `richText`, `heading`, `space`, `callToActionList`.                                                        |
+
+Not all projects have all of these. Discover the project's blocks blocks by searching for `createBlocksBlock` usages.
+
+---
+
+## Default Registration Target
+
+When the user does not specify where to register a block:
+
+1. **Always add to `PageContentBlock`** -- the main content area.
+2. **Also add to `ContentGroupBlock`** if it exists and the block is a general-purpose content block.
+3. **Do not add to `ColumnsContentBlock`** or `AccordionContentBlock` unless explicitly requested.
+
+Blocks that should typically **not** be added to `ContentGroupBlock`:
+
+- `contentGroup` -- would cause self-nesting
+- `pageTreeIndex` -- page-level navigation block
+- Any full-width or page-level-only block (e.g., a hero block)
+- Any block that is a layout container wrapping other blocks blocks
+
+Blocks that should typically **not** be added to `ColumnsContentBlock`:
+
+- `teaser`, `featureList`, `columns` -- too wide or complex for column layouts
+- `contentGroup`, `pageTreeIndex` -- page-level blocks
+
+---
+
+## Consistent Keys Across Layers
+
+The key used to register a block in `supportedBlocks` must be **identical across API, Admin, and Site**. The key is **camelCase** and typically matches the block's purpose or name (without "Block").
+
+```ts
+// API
+supportedBlocks: { featureList: FeatureListBlock }
+
+// Admin
+supportedBlocks: { featureList: FeatureListBlock }
+
+// Site
+const supportedBlocks: SupportedBlocks = {
+    featureList: (props) => <FeatureListBlock data={props} />,
+};
+```
+
+A mismatch in keys causes data loss or runtime errors.
+
+**Common key conventions:**
+
+| Block                             | Typical Key        |
+| --------------------------------- | ------------------ |
+| `StandaloneRichTextBlock`         | `richText`         |
+| `StandaloneHeadingBlock`          | `heading`          |
+| `StandaloneMediaBlock`            | `media`            |
+| `StandaloneCallToActionListBlock` | `callToActionList` |
+| `ColumnsBlock`                    | `columns`          |
+| `ContentGroupBlock`               | `contentGroup`     |
+| `FeatureListBlock`                | `featureList`      |
+| `TeaserBlock`                     | `teaser`           |
+| `SpaceBlock`                      | `space`            |
+| `AccordionBlock`                  | `accordion`        |
+| `AnchorBlock`                     | `anchor`           |
+| `ProductListBlock`                | `productList`      |
+
+For new blocks, derive the key from the block name in camelCase without "Block" (e.g., `ProductListBlock` -> `productList`).
+
+---
+
+## Step-by-Step: Registering a Block
+
+To register `FeatureListBlock` in `PageContentBlock`:
+
+**1. API layer** -- add import and key to `supportedBlocks`:
+
+```ts
+import { FeatureListBlock } from "@src/documents/pages/blocks/feature-list.block";
+
+export const PageContentBlock = createBlocksBlock(
+    {
+        supportedBlocks: {
+            // ... existing blocks ...
+            featureList: FeatureListBlock,
+        },
+    },
+    "PageContent",
+);
+```
+
+**2. Admin layer** -- same key:
+
+```tsx
+import { FeatureListBlock } from "@src/documents/pages/blocks/FeatureListBlock";
+
+export const PageContentBlock = createBlocksBlock({
+    name: "PageContent",
+    supportedBlocks: {
+        // ... existing blocks ...
+        featureList: FeatureListBlock,
+    },
+});
+```
+
+**3. Site layer** -- same key, **render function** syntax:
+
+```tsx
+import { FeatureListBlock } from "@src/documents/pages/blocks/FeatureListBlock";
+
+const supportedBlocks: SupportedBlocks = {
+    // ... existing blocks ...
+    featureList: (props) => <FeatureListBlock data={props} />,
+};
+```
+
+In the Site layer, the value is a **render function** `(props) => <Component data={props} />`. Some blocks use a `PageContent`-prefixed wrapper for layout purposes (e.g., `heading: (props) => <PageContentStandaloneHeadingBlock data={props} />`). Use the wrapper variant if it exists.
+
+---
+
+## Registering in Multiple Targets
+
+When a block should be in both `PageContentBlock` and `ContentGroupBlock`, add it to both. The `ContentGroupBlock` has its own inner blocks block (typically `ContentGroupContentBlock` or `ContentBlock`) defined locally inside the `ContentGroupBlock` file.
+
+Repeat the same key in all targets. Repeat the pattern in Admin and Site layers for each target.
+
+---
+
+## ContentGroupBlock Structure
+
+`ContentGroupBlock` is a **composite block** wrapping a blocks block as a child. It is itself registered inside `PageContentBlock`:
+
+```
+PageContentBlock (blocks block)
+├── contentGroup: ContentGroupBlock (composite block)
+│   ├── backgroundColor (select field)
+│   └── content: ContentGroupContentBlock (blocks block)
+│       ├── accordion, anchor, space, teaser, richText, heading, ...
+│       └── (same as PageContentBlock minus contentGroup, pageTreeIndex, and page-level-only blocks)
+├── columns: ColumnsBlock (composite block)
+│   └── columns[].content: ColumnsContentBlock (blocks block)
+│       └── accordion, anchor, richText, space, heading, callToActionList, media
+├── accordion, richText, heading, media, featureList, teaser, ...
+└── pageTreeIndex, and any other page-level-only blocks
+```
+
+---
+
+## Discovering Registration Targets
+
+1. **Search for `createBlocksBlock`** across the API directory to find all blocks blocks.
+2. **Check `PageContentBlock`** first -- it is the primary registration target.
+3. **Check `ContentGroupBlock`** -- if it exists and has similar blocks, also register there.
+4. **Inspect `ColumnsBlock`** and `AccordionBlock` -- only add blocks there if they suit constrained-width contexts.
+5. **Use the same key** in all targets.

package/skills/comet-block/references/response-summary.md

@@ -0,0 +1,102 @@
+# Response Template
+
+Use this template for the summary section at the end of **every** block creation or editing response. Include only the sections that apply — omit sections marked "conditional" when they are not relevant.
+
+---
+
+## Template
+
+```
+## Summary
+
+### Blocks created        ← omit entire section for pure edit tasks
+- **`BlockName`** — `Layer/path/to/BlockName.block.ts` (API), `Layer/path/to/BlockNameBlock.tsx` (Admin/Site)
+  Registered in: `PageContentBlock`, `ContentGroupBlock`
+- **`ListItemBlockName`** — registered in `ListBlockName`
+- **`ListBlockName`** — registered in `PageContentBlock`
+
+### Blocks edited          ← omit entire section for pure creation tasks
+- **`BlockName`** — added `fieldName` (string), removed `oldField`, changed `image` from `PixelImageBlock` → `DamImageBlock`
+
+### Migrations created     ← CONDITIONAL: only include if a migration was created
+- **`BlockNameV2Migration`** — `api/src/documents/pages/blocks/migrations/block-name.migration.ts`
+  Reason: [brief reason, e.g., "renamed `headline` → `title`", "added required `variant` field"]
+
+### Fixtures
+- **`BlockNameFixtureService`** — `api/src/db/fixtures/blocks/block-name-fixture.service.ts`
+- **`ListItemBlockNameFixtureService`** — `api/src/db/fixtures/blocks/list-item-block-name-fixture.service.ts`
+  ← omit this section if no fixture services were created or modified
+```
+
+---
+
+## Rules
+
+**Created blocks section:**
+
+- List every new block file created. Include both the list block and its item block as separate entries.
+- For each block, show its registration target(s). If registered in multiple parents, list all: `registered in \`PageContentBlock\` and \`ContentGroupBlock\``.
+- If the item block is "registered in" a list block, make that explicit: `registered in \`TeaserListBlock\``.
+
+**Edited blocks section:**
+
+- Describe each change concisely: `added \`fieldName\` (type)`, `removed \`fieldName\``, `changed \`fieldName\` from X → Y`.
+- List each changed block as a separate bullet.
+
+**Migrations section (conditional):**
+
+- Include only when one or more migration classes were created.
+- State the migration class name and file path.
+- Give a one-line reason (what data shape changed and why).
+
+**Fixtures section:**
+
+- Include when fixture services were created or meaningfully updated.
+- Omit entirely when no fixture work was done.
+- List each fixture service separately with its file path.
+- If an existing fixture was only wired (not created), note it as "updated `ParentFixtureService` to include `BlockNameFixtureService`".
+
+---
+
+## Example — Block creation with list block and migration
+
+```
+## Summary
+
+### Blocks created
+- **`TeaserItemBlock`** — registered in `TeaserListBlock`
+- **`TeaserListBlock`** — registered in `PageContentBlock`, `ContentGroupBlock`
+
+### Migrations created
+- **`TeaserListBlockV2Migration`** — `api/src/documents/pages/blocks/migrations/teaser-list-block.migration.ts`
+  Reason: added required `variant` field (existing data defaults to `"primary"`)
+
+### Fixtures
+- **`TeaserItemBlockFixtureService`** — `api/src/db/fixtures/blocks/teaser-item-block-fixture.service.ts`
+- **`TeaserListBlockFixtureService`** — `api/src/db/fixtures/blocks/teaser-list-block-fixture.service.ts`
+```
+
+---
+
+## Example — Editing an existing block, no migration
+
+```
+## Summary
+
+### Blocks edited
+- **`HeroBlock`** — added `subtitle` (string, optional), changed `image` from `PixelImageBlock` → `DamImageBlock`
+
+### Fixtures
+- Updated **`HeroBlockFixtureService`** — added `subtitle`, updated `image` field to `DamImageBlock` input format
+```
+
+---
+
+## Example — Pure creation, no fixtures
+
+```
+## Summary
+
+### Blocks created
+- **`QuoteBlock`** — registered in `PageContentBlock`
+```

package/skills/comet-block/references/rich-text.md

@@ -0,0 +1,309 @@
+# RichText Block Rules
+
+Detailed rules for creating and configuring RichText blocks in Comet. Load this file when a block contains a rich text field.
+
+---
+
+## Overview
+
+Two usage modes:
+
+1. **Shared project-wide `RichTextBlock`** — defined once in `common/blocks/` and reused wherever full rich text is needed.
+2. **Scoped `RichTextBlock`** — a locally defined `createRichTextBlock(...)` call inside the composite block file, configured for a specific purpose (single-line eyebrow, heading-only field, etc.).
+
+The API block is always the shared one. Per-field configuration is **Admin-only**.
+
+---
+
+## API Side
+
+The API block is project-wide regardless of how many Admin-side scoped variants exist.
+
+```ts
+// api/src/common/blocks/rich-text.block.ts
+import { createRichTextBlock } from "@comet/cms-api";
+import { LinkBlock } from "@src/common/blocks/link.block";
+
+export const RichTextBlock = createRichTextBlock({ link: LinkBlock });
+```
+
+Options: `link` (required — the inline link block) and `indexSearchText` (optional boolean, defaults to `true`).
+
+Use as a child block in composite blocks:
+
+```ts
+import { RichTextBlock } from "@src/common/blocks/rich-text.block";
+
+class MyBlockData extends BlockData {
+    @ChildBlock(RichTextBlock)
+    description: BlockDataInterface;
+}
+
+class MyBlockInput extends BlockInput {
+    @ChildBlockInput(RichTextBlock)
+    description: ExtractBlockInput<typeof RichTextBlock>;
+
+    transformToBlockData(): MyBlockData {
+        return blockInputToData(MyBlockData, this);
+    }
+}
+```
+
+---
+
+## Admin Side
+
+```ts
+import { createRichTextBlock } from "@comet/cms-admin";
+```
+
+Admin options: `link` (required), `rte` (partial `IRteOptions` — spread over defaults), `minHeight` (pixels, default ~150px), `tags`.
+
+### Key `rte` options
+
+| Option              | Purpose                                                           |
+| ------------------- | ----------------------------------------------------------------- |
+| `supports`          | Array of toolbar features to enable (see values below)            |
+| `maxBlocks`         | Max paragraphs — set to `1` for single-line fields                |
+| `standardBlockType` | Default block type, e.g. `"header-one"` or `"paragraph-standard"` |
+| `blocktypeMap`      | Add custom block types or relabel existing ones                   |
+
+**Available `supports` values:** `"bold"`, `"italic"`, `"underline"`, `"strikethrough"`, `"sub"`, `"sup"`, `"header-one"` through `"header-six"`, `"ordered-list"`, `"unordered-list"`, `"blockquote"`, `"history"`, `"link"`, `"links-remove"`, `"non-breaking-space"`, `"soft-hyphen"`.
+
+**Default set** includes all of the above except `"underline"` and `"blockquote"`.
+
+**Link rule:** when a `link` block is configured, always include `"link"` and `"links-remove"` in `supports` unless the field is intentionally link-free.
+
+---
+
+## Configuration Patterns
+
+### Pattern 1: Shared Full RichTextBlock
+
+Defined once per project in `common/blocks/`. No `rte` overrides needed for a standard full-featured editor.
+
+```tsx
+// admin/src/common/blocks/RichTextBlock.tsx
+import { createRichTextBlock } from "@comet/cms-admin";
+import { LinkBlock } from "./LinkBlock";
+
+export const RichTextBlock = createRichTextBlock({ link: LinkBlock });
+```
+
+When projects need custom paragraph variants, configure `standardBlockType` and `blocktypeMap`:
+
+> **Note:** `"paragraph-standard"` and `"paragraph-small"` below are **examples only**. The actual block type keys are entirely project-defined. Always check the project's `RichTextBlock` definition to see which custom block types are in use — or whether custom block types are used at all.
+
+```tsx
+export const RichTextBlock = createRichTextBlock({
+    link: LinkBlock,
+    rte: {
+        standardBlockType: "paragraph-standard",
+        blocktypeMap: {
+            "paragraph-standard": {
+                label: <FormattedMessage id="richTextBlock.paragraphStandard" defaultMessage="Paragraph Standard" />,
+            },
+            "paragraph-small": {
+                label: <FormattedMessage id="richTextBlock.paragraphSmall" defaultMessage="Paragraph Small" />,
+                renderConfig: {
+                    element: (props) => <Typography paragraph variant="body2" {...props} />,
+                },
+            },
+        },
+    },
+});
+```
+
+### Pattern 2: Single-Line Inline Field
+
+For eyebrows, subtitles, captions — any field that should be a single line of formatted text.
+
+Key settings:
+
+- `maxBlocks: 1` — prevents Enter from creating new paragraphs
+- `minHeight: 0` — compact editor height
+
+```tsx
+const DescriptionRichTextBlock = createRichTextBlock({
+    link: LinkBlock,
+    rte: {
+        maxBlocks: 1,
+        supports: ["bold", "italic", "sub", "sup", "non-breaking-space", "soft-hyphen", "link", "links-remove"],
+    },
+    minHeight: 0,
+});
+```
+
+### Pattern 3: Heading-Only Field
+
+For single-line heading/title fields where the user selects a heading level from a dropdown.
+
+Key settings:
+
+- `maxBlocks: 1` + `minHeight: 0` — single compact line
+- `standardBlockType: "header-one"` — new content defaults to heading 1
+- `blocktypeMap` — only add if the project uses custom heading label names. **Check existing RTE blocks in the project** to see how heading levels are labelled and match that convention. If no custom labels are used, omit `blocktypeMap`.
+
+```tsx
+const HeadlineRichTextBlock = createRichTextBlock({
+    link: LinkBlock,
+    rte: {
+        maxBlocks: 1,
+        supports: [
+            "header-one",
+            "header-two",
+            "header-three",
+            "header-four",
+            "header-five",
+            "header-six",
+            "bold",
+            "italic",
+            "sub",
+            "sup",
+            "non-breaking-space",
+            "soft-hyphen",
+        ],
+        standardBlockType: "header-one",
+    },
+    minHeight: 0,
+});
+```
+
+### Pattern 4: Limited Feature Set
+
+When the full RTE is too powerful for the context but multiline content is still needed.
+
+```tsx
+const BaseRichTextBlock = createRichTextBlock({
+    link: ExternalLinkBlock,
+    rte: {
+        supports: ["bold", "italic", "header-one", "header-two", "header-three", "link", "links-remove"],
+    },
+});
+```
+
+---
+
+## `blocktypeMap` Patterns
+
+### Adding Custom Block Types
+
+Custom block types are arbitrary strings outside Draft.js defaults. Define them in `blocktypeMap` and set `standardBlockType` if the custom type should be the default.
+
+> **Note:** `"paragraph-standard"` and `"paragraph-small"` below are **examples only**. Block type keys are entirely project-defined — always look at the project's `RichTextBlock` definition to see what custom types are actually configured.
+
+```tsx
+blocktypeMap: {
+    "paragraph-standard": {
+        label: <FormattedMessage id="richTextBlock.paragraphStandard" defaultMessage="Paragraph Standard" />,
+    },
+    "paragraph-small": {
+        label: <FormattedMessage id="richTextBlock.paragraphSmall" defaultMessage="Paragraph Small" />,
+        renderConfig: {
+            element: (props) => <Typography paragraph variant="body2" {...props} />,
+        },
+    },
+},
+```
+
+When `standardBlockType` is set to something other than `"unstyled"`, the `"unstyled"` block type is hidden from the dropdown.
+
+### Relabeling Existing Block Types
+
+Override just `label` to rename existing types without changing behavior:
+
+```tsx
+blocktypeMap: {
+    "header-one": {
+        label: <FormattedMessage id="headingBlock.size600" defaultMessage="Size 600" />,
+    },
+},
+```
+
+---
+
+## Naming Conventions
+
+**Shared RichTextBlock:**
+
+- API: `api/src/common/blocks/rich-text.block.ts`
+- Admin: `admin/src/common/blocks/RichTextBlock.tsx`
+- Site: `site/src/common/blocks/RichTextBlock.tsx`
+- Export name: `RichTextBlock`
+
+**Scoped RichTextBlock:** name descriptively as `{Purpose}RichTextBlock` (e.g., `EyebrowRichTextBlock`, `HeadlineRichTextBlock`, `DescriptionRichTextBlock`). Define as a non-exported `const` inside the composite block file:
+
+```tsx
+// Inside admin/src/documents/pages/blocks/TeaserItemBlock.tsx
+
+const DescriptionRichTextBlock = createRichTextBlock({
+    link: LinkBlock,
+    rte: { maxBlocks: 1, supports: ["bold", "italic", "sub", "sup", "non-breaking-space", "soft-hyphen", "link", "links-remove"] },
+    minHeight: 0,
+});
+
+export const TeaserItemBlock = createCompositeBlock({
+    name: "TeaserItem",
+    blocks: {
+        description: {
+            block: DescriptionRichTextBlock,
+            title: <FormattedMessage id="teaserItemBlock.description" defaultMessage="Description" />,
+        },
+    },
+});
+```
+
+---
+
+## Site Side
+
+```tsx
+import { hasRichTextBlockContent, type PropsWithData, withPreview } from "@comet/site-nextjs";
+import { type RichTextBlockData } from "@src/blocks.generated";
+```
+
+Use `hasRichTextBlockContent` to conditionally render:
+
+```tsx
+{
+    hasRichTextBlockContent(description) && <RichTextBlock data={description} />;
+}
+```
+
+When custom block types are added in the Admin, add matching entries in the site's `blocks` renderer map. The keys must exactly match what is defined in the project's Admin-side `RichTextBlock` configuration — `"paragraph-standard"` and `"paragraph-small"` below are **examples only**:
+
+```tsx
+blocks: {
+    "paragraph-standard": createTextBlockRenderFn({ bottomSpacing: true }),
+    "paragraph-small": createTextBlockRenderFn({ variant: "paragraph200", bottomSpacing: true }),
+},
+```
+
+Do **not** wrap `RichTextBlock` in a `Typography` component — the block already defines its own typography through its renderers; wrapping produces conflicting styles.
+
+---
+
+## Decision Guide
+
+| Scenario                                                      | Use Shared | Create Scoped              |
+| ------------------------------------------------------------- | ---------- | -------------------------- |
+| General content area with full formatting                     | Yes        | No                         |
+| Short description or subtitle (single-line, basic formatting) | No         | Yes — single-line pattern  |
+| Heading with size dropdown                                    | No         | Yes — heading-only pattern |
+| Eyebrow text                                                  | No         | Yes — single-line pattern  |
+| Email campaign with different link block                      | No         | Yes — different link block |
+| Content area with fewer features than default                 | No         | Yes — limited feature set  |
+
+**Rule of thumb:** if the field needs `maxBlocks`, a custom `supports` set, a custom `standardBlockType`, or a different `link` block — create a scoped RichTextBlock.
+
+---
+
+## Common Pitfalls
+
+1. **Forgetting `minHeight: 0`** with `maxBlocks: 1` — editor area is unnecessarily tall for a single-line field.
+2. **Adding custom block types in Admin without updating the site** — site renderers must include all custom block type keys or content using those types renders as nothing.
+3. **Setting `standardBlockType` to a custom type without defining it in `blocktypeMap`** — the dropdown label renders incorrectly.
+4. **Trying to customize the API block per-field** — the API block is shared; all per-field customization is Admin-only.
+5. **Exporting scoped RichTextBlocks** — they must remain private (`const` without `export`) in the composite block file.
+6. **Omitting `"link"` and `"links-remove"` when a link block is configured** — editors cannot add or remove links without these in `supports`.
+7. **Wrapping `RichTextBlock` in `Typography` on the site** — produces double-wrapped, incorrectly styled output.