@flowstack-ui/brick 0.1.9 → 0.1.12

package/dist/agents/avatar.md

@@ -0,0 +1,49 @@
+# Avatar agent guide
+
+## Purpose
+
+Present one compact person or entity identity with a finished fixed-square image/fallback recipe and optional visual status ring.
+
+## Use when
+
+- A person, organization, workspace, or other named entity needs a compact fixed-square identity token with explicit fallback content.
+
+## Choose something else when
+
+- A larger editorial or profile portrait needs an authored aspect ratio, crop, focal position, or responsive measure. Use Image.
+- A count or dot must attach to an identity. Use NotificationBadge composed around Avatar.
+
+## Required composition
+
+- Provide explicit alt and fallback; keep Avatar passive and let an owning Button or Link provide interaction, focus, and the functional accessible name.
+- Keep visible identity or status text nearby when the image or status ring alone would be ambiguous or consequential.
+
+## Rules
+
+- **MUST:** Use Avatar for compact fixed-square identity presentation, not generic media or larger editorial portraits.
+- **MUST:** Decide alt from context: preserve meaningful identity when Avatar adds it, and use alt="" only when adjacent text or the owning control already supplies the same identity.
+- **MUST:** Pass the same source to the Atom-backed Root and Image path, preserve idle/loading/loaded/error state, and keep explicit fallback content durable through missing, changed, delayed, and failed images.
+- **MUST:** Supply explicit localized fallback content; do not generate initials or infer identity from a filename.
+- **MUST:** Keep Avatar passive; wrap it with the public Button or Link that owns any action or destination.
+- **MUST:** Provide separate accessible status text when a status ring communicates meaningful availability.
+- **MUST:** Choose the nearest named Avatar size, including 2xl through 5xl for larger square profile identities, instead of overriding --brick-avatar-size inline; use Image for authored non-square portrait media.
+- **MUST:** Load styles.css or core.css plus avatar.css.
+
+## Common mistakes
+
+- **Avoid:** Forcing a large 4:5 profile portrait into Avatar, using alt="" merely because a name appears somewhere nearby, generating fallback initials inside Brick, or treating the status ring as an announcement. **Instead:** Use Image for authored portrait media, make the alt decision from the specific context, provide explicit fallback content, and keep meaningful status in text.
+
+## Validation checklist
+
+- Check missing, idle, loading, loaded, changed-source, and error paths; delayed fallback timing; fixed square size; crop; informative and decorative naming; passive semantics; nearby identity/status text; light/dark/forced colors; zoom; and RTL.
+- Confirm a named Avatar size is used, CSS is loaded, and any owning Button, Link, or NotificationBadge preserves its own public contract.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/avatar`
+- `image`
+- `button`
+- `link`
+- `notification-badge`
+- `badge`
+- `status`

package/dist/agents/badge.json

@@ -5,7 +5,7 @@
   "package": "@flowstack-ui/brick",
   "layer": "brick",
   "kind": "component",
-  "purpose": "Present a short passive category, status, or metadata label with a complete Brick visual recipe.",
+  "purpose": "Present a short passive category, status, metadata label, or compact circular passive marker with a complete Brick visual recipe.",
   "useWhen": [
     "A short non-interactive label needs a bounded visual treatment that remains understandable in its surrounding content."
   ],
@@ -16,7 +16,7 @@
     }
   ],
   "composition": [
-    "Place the short label directly in Badge; when an icon or separately styled Text is necessary, keep those children passive and let Badge own their spacing and foreground."
+    "Place the short label directly in Badge; when an icon or separately styled Text is necessary, keep those children passive and let Badge own their spacing and foreground. Use size=xl with shape=circle only for a deliberate passive empty-state icon well."
   ],
   "rules": [
     {
@@ -24,6 +24,11 @@
       "level": "must",
       "statement": "Keep Badge passive; do not add click, press, selection, or disclosure behavior to it."
     },
+    {
+      "id": "badge-context-live",
+      "level": "must",
+      "statement": "Keep every count or status understandable from visible text or its owning control without relying on color, shape, or placement, and never assume Badge announces changes or joins a sibling control name automatically."
+    },
     {
       "id": "badge-inherited-text",
       "level": "must",
@@ -37,7 +42,12 @@
     {
       "id": "badge-short-label",
       "level": "must",
-      "statement": "Keep the label short and do not use Badge as a container for explanatory prose."
+      "statement": "Keep the label short and atomic; Badge stays on one line, so use ordinary Text for explanatory or prose-length content."
+    },
+    {
+      "id": "badge-circle",
+      "level": "must",
+      "statement": "Use shape=circle only for one compact passive icon or single character with nearby context; use IconButton for an action and Status for a dot-and-label state."
     },
     {
       "id": "badge-css",
@@ -47,18 +57,26 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Nesting default-tone Text in a Badge, manually spacing an icon and label, or using Badge as an eyebrow solely for uppercase styling.",
-      "correction": "Use plain Badge text when possible, tone=inherit for nested Text, Badge's own gap for children, and Text variant=eyebrow for a short editorial heading introduction."
+      "mistake": "Nesting default-tone Text in a Badge, manually spacing an icon and label, using a padded rounded Badge for a circular verification marker, or using Badge as an eyebrow solely for uppercase styling.",
+      "correction": "Use plain Badge text when possible, tone=inherit for nested Text, Badge's own gap for children, shape=circle for a passive icon marker, and Text variant=eyebrow for a short editorial heading introduction."
     }
   ],
   "validation": [
-    "Check label brevity, passive semantics, child spacing, foreground contrast for every variant and tone, zoom, forced colors, and RTL.",
-    "Confirm nested Text inherits the Badge foreground and CSS is loaded."
+    "Check label brevity, one-line atomic sizing, passive semantics, child spacing, foreground contrast for every variant and tone, zoom, forced colors, and RTL.",
+    "Confirm nested Text inherits the Badge foreground, circle geometry remains exactly square, and CSS is loaded."
   ],
   "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "badge",
+      "versionPolicy": "installed-exact"
+    },
     "text",
     "icon",
     "notification-badge",
-    "button"
+    "button",
+    "status",
+    "z-stack"
   ]
 }

package/dist/agents/badge.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Present a short passive category, status, or metadata label with a complete Brick visual recipe.
+Present a short passive category, status, metadata label, or compact circular passive marker with a complete Brick visual recipe.
 
 ## Use when
 
@@ -14,28 +14,33 @@ Present a short passive category, status, or metadata label with a complete Bric
 
 ## Required composition
 
-- Place the short label directly in Badge; when an icon or separately styled Text is necessary, keep those children passive and let Badge own their spacing and foreground.
+- Place the short label directly in Badge; when an icon or separately styled Text is necessary, keep those children passive and let Badge own their spacing and foreground. Use size=xl with shape=circle only for a deliberate passive empty-state icon well.
 
 ## Rules
 
 - **MUST:** Keep Badge passive; do not add click, press, selection, or disclosure behavior to it.
+- **MUST:** Keep every count or status understandable from visible text or its owning control without relying on color, shape, or placement, and never assume Badge announces changes or joins a sibling control name automatically.
 - **MUST:** When composing Text inside Badge, use tone=inherit unless that Text intentionally communicates a separate semantic tone, so the Badge recipe continues to own foreground contrast.
 - **MUST:** Rely on Badge's gap for an icon and label instead of literal whitespace, wrapper margins, or positional offsets.
-- **MUST:** Keep the label short and do not use Badge as a container for explanatory prose.
+- **MUST:** Keep the label short and atomic; Badge stays on one line, so use ordinary Text for explanatory or prose-length content.
+- **MUST:** Use shape=circle only for one compact passive icon or single character with nearby context; use IconButton for an action and Status for a dot-and-label state.
 - **MUST:** Load styles.css or core.css plus badge.css.
 
 ## Common mistakes
 
-- **Avoid:** Nesting default-tone Text in a Badge, manually spacing an icon and label, or using Badge as an eyebrow solely for uppercase styling. **Instead:** Use plain Badge text when possible, tone=inherit for nested Text, Badge's own gap for children, and Text variant=eyebrow for a short editorial heading introduction.
+- **Avoid:** Nesting default-tone Text in a Badge, manually spacing an icon and label, using a padded rounded Badge for a circular verification marker, or using Badge as an eyebrow solely for uppercase styling. **Instead:** Use plain Badge text when possible, tone=inherit for nested Text, Badge's own gap for children, shape=circle for a passive icon marker, and Text variant=eyebrow for a short editorial heading introduction.
 
 ## Validation checklist
 
-- Check label brevity, passive semantics, child spacing, foreground contrast for every variant and tone, zoom, forced colors, and RTL.
-- Confirm nested Text inherits the Badge foreground and CSS is loaded.
+- Check label brevity, one-line atomic sizing, passive semantics, child spacing, foreground contrast for every variant and tone, zoom, forced colors, and RTL.
+- Confirm nested Text inherits the Badge foreground, circle geometry remains exactly square, and CSS is loaded.
 
 ## Related guidance
 
+- `@flowstack-ui/atom/agents/badge`
 - `text`
 - `icon`
 - `notification-badge`
 - `button`
+- `status`
+- `z-stack`

package/dist/agents/bleed.json

@@ -0,0 +1,54 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "bleed",
+  "name": "Bleed",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Extend authored content across a parent inset with responsive logical spacing.",
+  "useWhen": [
+    "Edge media or artwork must cross its immediate container padding."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The problem is size, paint, ordinary arrangement, or unrelated positioning.",
+      "useInstead": "Frame, Surface, Stack, Grid, or application layout"
+    }
+  ],
+  "composition": [
+    "Place Bleed inside the owner of the inset it crosses and keep meaningful media or content semantics on the authored child."
+  ],
+  "rules": [
+    {
+      "id": "bleed-positive-input",
+      "level": "must",
+      "statement": "Use public non-negative spacing values; Bleed owns the negative conversion."
+    },
+    {
+      "id": "bleed-axis-first",
+      "level": "should",
+      "statement": "Prefer inline or block for an axis and directional props only for a genuine one-edge exception."
+    },
+    {
+      "id": "bleed-verify",
+      "level": "must",
+      "statement": "Verify narrow widths, RTL, zoom, and horizontal overflow."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Bleed to fix an incorrect Container measure.",
+      "correction": "Correct the owning layout first."
+    }
+  ],
+  "validation": [
+    "Confirm the intended edges align with the parent's outer boundary.",
+    "Confirm the page does not gain horizontal overflow."
+  ],
+  "related": [
+    "frame",
+    "stack",
+    "surface",
+    "image"
+  ]
+}

package/dist/agents/bleed.md

@@ -0,0 +1,39 @@
+# Bleed agent guide
+
+## Purpose
+
+Extend authored content across a parent inset with responsive logical spacing.
+
+## Use when
+
+- Edge media or artwork must cross its immediate container padding.
+
+## Choose something else when
+
+- The problem is size, paint, ordinary arrangement, or unrelated positioning. Use Frame, Surface, Stack, Grid, or application layout.
+
+## Required composition
+
+- Place Bleed inside the owner of the inset it crosses and keep meaningful media or content semantics on the authored child.
+
+## Rules
+
+- **MUST:** Use public non-negative spacing values; Bleed owns the negative conversion.
+- **SHOULD:** Prefer inline or block for an axis and directional props only for a genuine one-edge exception.
+- **MUST:** Verify narrow widths, RTL, zoom, and horizontal overflow.
+
+## Common mistakes
+
+- **Avoid:** Using Bleed to fix an incorrect Container measure. **Instead:** Correct the owning layout first.
+
+## Validation checklist
+
+- Confirm the intended edges align with the parent's outer boundary.
+- Confirm the page does not gain horizontal overflow.
+
+## Related guidance
+
+- `frame`
+- `stack`
+- `surface`
+- `image`

package/dist/agents/blockquote.json

@@ -0,0 +1,68 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "blockquote",
+  "name": "Blockquote",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Compose an extended quotation, source URL, and optional attribution with correct native structure and finished Brick styling.",
+  "useWhen": [
+    "An extended quotation and optional attribution form one self-contained content unit."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The quotation is inline within a sentence.",
+      "useInstead": "native q inside the surrounding content owner"
+    },
+    {
+      "condition": "The interface is a testimonial card with media, ratings, or actions.",
+      "useInstead": "Card or a product Block composed with Blockquote"
+    }
+  ],
+  "composition": [
+    "Place Blockquote.Content and optional Blockquote.Caption as siblings inside Blockquote.Root; put the source URL on Content through cite.",
+    "Use Blockquote.Cite inside Caption only for a referenced work or source, not merely for the person quoted."
+  ],
+  "rules": [
+    {
+      "id": "blockquote-native",
+      "level": "must",
+      "statement": "Preserve figure Root, blockquote Content, sibling figcaption Caption, and native cite Cite."
+    },
+    {
+      "id": "blockquote-attribution",
+      "level": "must",
+      "statement": "Keep attribution outside Content so it is not represented as part of the quotation."
+    },
+    {
+      "id": "blockquote-recipes",
+      "level": "must",
+      "statement": "Select only the documented accent, surface, or plain variant and start, center, or end alignment."
+    },
+    {
+      "id": "blockquote-icon",
+      "level": "must",
+      "statement": "Keep Icon decorative unless a consumer intentionally overrides aria-hidden for meaningful custom content."
+    },
+    {
+      "id": "blockquote-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus blockquote.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Putting the author or source inside Blockquote.Content.",
+      "correction": "Render attribution in sibling Blockquote.Caption and use Cite only for a work or source title."
+    }
+  ],
+  "validation": [
+    "Confirm native figure, blockquote, figcaption, and cite mapping; source URL forwarding; logical alignment; selection and copy; forced colors; zoom; text spacing; localization; RTL; and CSS delivery.",
+    "Confirm Blockquote adds no tab stop, role, interaction, or application provenance policy."
+  ],
+  "related": [
+    "text",
+    "mark",
+    "interface-composition"
+  ]
+}

package/dist/agents/blockquote.md

@@ -0,0 +1,42 @@
+# Blockquote agent guide
+
+## Purpose
+
+Compose an extended quotation, source URL, and optional attribution with correct native structure and finished Brick styling.
+
+## Use when
+
+- An extended quotation and optional attribution form one self-contained content unit.
+
+## Choose something else when
+
+- The quotation is inline within a sentence. Use native q inside the surrounding content owner.
+- The interface is a testimonial card with media, ratings, or actions. Use Card or a product Block composed with Blockquote.
+
+## Required composition
+
+- Place Blockquote.Content and optional Blockquote.Caption as siblings inside Blockquote.Root; put the source URL on Content through cite.
+- Use Blockquote.Cite inside Caption only for a referenced work or source, not merely for the person quoted.
+
+## Rules
+
+- **MUST:** Preserve figure Root, blockquote Content, sibling figcaption Caption, and native cite Cite.
+- **MUST:** Keep attribution outside Content so it is not represented as part of the quotation.
+- **MUST:** Select only the documented accent, surface, or plain variant and start, center, or end alignment.
+- **MUST:** Keep Icon decorative unless a consumer intentionally overrides aria-hidden for meaningful custom content.
+- **MUST:** Load styles.css or core.css plus blockquote.css.
+
+## Common mistakes
+
+- **Avoid:** Putting the author or source inside Blockquote.Content. **Instead:** Render attribution in sibling Blockquote.Caption and use Cite only for a work or source title.
+
+## Validation checklist
+
+- Confirm native figure, blockquote, figcaption, and cite mapping; source URL forwarding; logical alignment; selection and copy; forced colors; zoom; text spacing; localization; RTL; and CSS delivery.
+- Confirm Blockquote adds no tab stop, role, interaction, or application provenance policy.
+
+## Related guidance
+
+- `text`
+- `mark`
+- `interface-composition`

package/dist/agents/button.json

@@ -39,10 +39,15 @@
   ],
   "validation": [
     "Confirm an accessible name and action semantics.",
-    "Test focus, keyboard activation, disabled/loading behavior, and contrast in every supported appearance."
+    "Test focus, keyboard activation, disabled/loading behavior, and contrast in every supported appearance; disabled labels must remain readable while ghost and outline controls stay transparent."
   ],
   "related": [
-    "@flowstack-ui/atom/agents/button",
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "button",
+      "versionPolicy": "installed-exact"
+    },
     "link",
     "form"
   ]

package/dist/agents/button.md

@@ -29,7 +29,7 @@ Render a finished accessible action or emphasized native link with Brick size, t
 ## Validation checklist
 
 - Confirm an accessible name and action semantics.
-- Test focus, keyboard activation, disabled/loading behavior, and contrast in every supported appearance.
+- Test focus, keyboard activation, disabled/loading behavior, and contrast in every supported appearance; disabled labels must remain readable while ghost and outline controls stay transparent.
 
 ## Related guidance
 

package/dist/agents/card.json

@@ -16,7 +16,8 @@
     }
   ],
   "composition": [
-    "Compose Card.Root with only the Header, Title, Description, Content, and Footer parts the subject needs."
+    "Compose Card.Root with only the Header, Title, Description, Action, Content, and Footer parts the subject needs.",
+    "Card.Action reserves a trailing Header column across the title and description rows; when compact metadata belongs beside only the title, compose that title row with HStack and omit Card.Action so the description retains the full measure."
   ],
   "rules": [
     {
@@ -33,16 +34,35 @@
       "id": "card-borderless-media",
       "level": "should",
       "statement": "Use bordered={false} when edge-to-edge authored media should meet Card's clipped outer boundary without retaining the selected recipe's border; do not remove that geometry with application CSS."
+    },
+    {
+      "id": "card-action-measure",
+      "level": "should",
+      "statement": "Use Card.Action only when every Header text row should reserve its trailing column; otherwise compose title-only metadata in a Brick HStack."
+    },
+    {
+      "id": "card-edge-media-header",
+      "level": "should",
+      "statement": "For edge media, place authored Image directly under Card.Root, then use Card.Header for topic, title, and description so the root clips outer corners and the complete text region receives Card inset."
     }
   ],
   "commonMistakes": [
     {
       "mistake": "Using Card for every spacing group.",
       "correction": "Use Stack or Surface when there is no bounded card subject."
+    },
+    {
+      "mistake": "Using Card.Action for a title-only Badge and unintentionally narrowing the description below it.",
+      "correction": "Place the title and Badge in a Brick HStack, then render Card.Description as the next full-width Header child."
+    },
+    {
+      "mistake": "Placing Card.Content directly after edge media and expecting top inset.",
+      "correction": "Use Card.Header for the introductory text anatomy."
     }
   ],
   "validation": [
     "Check heading order and explicit action names.",
+    "Check whether trailing Header content should constrain both title and description or the title row only.",
     "Check content flow, focus visibility, narrow widths, and appearance contrast."
   ],
   "related": [

package/dist/agents/card.md

@@ -14,21 +14,27 @@ Group content about one subject in a finished static compound surface with heade
 
 ## Required composition
 
-- Compose Card.Root with only the Header, Title, Description, Content, and Footer parts the subject needs.
+- Compose Card.Root with only the Header, Title, Description, Action, Content, and Footer parts the subject needs.
+- Card.Action reserves a trailing Header column across the title and description rows; when compact metadata belongs beside only the title, compose that title row with HStack and omit Card.Action so the description retains the full measure.
 
 ## Rules
 
 - **MUST:** Do not turn the whole Card into an unnamed clickable div; place explicit Link or Button controls inside or use a valid link composition.
 - **MUST:** Load styles.css or core.css plus card.css and styles for nested components.
 - **SHOULD:** Use bordered={false} when edge-to-edge authored media should meet Card's clipped outer boundary without retaining the selected recipe's border; do not remove that geometry with application CSS.
+- **SHOULD:** Use Card.Action only when every Header text row should reserve its trailing column; otherwise compose title-only metadata in a Brick HStack.
+- **SHOULD:** For edge media, place authored Image directly under Card.Root, then use Card.Header for topic, title, and description so the root clips outer corners and the complete text region receives Card inset.
 
 ## Common mistakes
 
 - **Avoid:** Using Card for every spacing group. **Instead:** Use Stack or Surface when there is no bounded card subject.
+- **Avoid:** Using Card.Action for a title-only Badge and unintentionally narrowing the description below it. **Instead:** Place the title and Badge in a Brick HStack, then render Card.Description as the next full-width Header child.
+- **Avoid:** Placing Card.Content directly after edge media and expecting top inset. **Instead:** Use Card.Header for the introductory text anatomy.
 
 ## Validation checklist
 
 - Check heading order and explicit action names.
+- Check whether trailing Header content should constrain both title and description or the title row only.
 - Check content flow, focus visibility, narrow widths, and appearance contrast.
 
 ## Related guidance

package/dist/agents/checkbox-group.json

@@ -0,0 +1,108 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "checkbox-group",
+  "name": "Checkbox Group",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Coordinate related multi-selection with structured item labels, optional descriptions, native repeated form values, and an optional aggregate parent control.",
+  "useWhen": [
+    "Several independently selectable choices belong to one named group or need a select-all parent."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The choice is independent and does not share group state.",
+      "useInstead": "Checkbox"
+    },
+    {
+      "condition": "Exactly one option must be selected.",
+      "useInstead": "Radio Group or Select"
+    },
+    {
+      "condition": "The interface needs remote option loading, search, or a generated filter engine.",
+      "useInstead": "Combobox or application-owned discovery controls"
+    }
+  ],
+  "composition": [
+    "Give Root an accessible group name directly or compose it inside Fieldset with one visible Legend and shared description or error.",
+    "Compose Root with Item children; wrap each primary label in ItemLabel and supporting text in ItemDescription when structured item relationships are needed.",
+    "Use Parent only with an explicit allValues list containing the currently selectable declared values; omit individually disabled values and never infer the collection from rendered children."
+  ],
+  "rules": [
+    {
+      "id": "checkbox-group-related-choices",
+      "level": "must",
+      "statement": "Use Checkbox Group only for related multi-selection; keep one-of-many choice, independent consent, remote search, and application filter execution in their owning patterns."
+    },
+    {
+      "id": "checkbox-group-naming",
+      "level": "must",
+      "statement": "Give Root a persistent accessible group name and every Item a complete visible associated label; placeholder or surrounding layout does not name the group."
+    },
+    {
+      "id": "checkbox-group-value-identity",
+      "level": "must",
+      "statement": "Give every Item a unique stable string value and let the application own persistence, query synchronization, result counts, and filtering side effects."
+    },
+    {
+      "id": "checkbox-group-parent-values",
+      "level": "must",
+      "statement": "Supply Parent allValues explicitly from the selectable declared set and do not include disabled choices or derive the set from DOM children."
+    },
+    {
+      "id": "checkbox-group-orientation",
+      "level": "must",
+      "statement": "Use the vertical default for scan-heavy groups and horizontal only when wrapped reading order remains clear under narrow widths, zoom, and localization."
+    },
+    {
+      "id": "checkbox-group-invalid-scope",
+      "level": "must",
+      "statement": "Keep required or invalid messaging at group scope when any eligible option can satisfy the requirement; do not paint every Item as individually invalid."
+    },
+    {
+      "id": "checkbox-group-state-form",
+      "level": "must",
+      "statement": "Preserve disabled and read-only Items, one-or-more required validity, first-enabled validation focus, Fieldset relationships, named repeated-value submission, external form association, and uncontrolled reset."
+    },
+    {
+      "id": "checkbox-group-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus checkbox-group.css and any Fieldset styles used."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Building a filter facet with unrelated standalone checkboxes and no group name.",
+      "correction": "Use one named CheckboxGroup.Root with stable Item values and keep query execution in the application."
+    },
+    {
+      "mistake": "Using Parent without an explicit current selectable set.",
+      "correction": "Pass allValues deliberately so none, mixed, and all state remain deterministic."
+    },
+    {
+      "mistake": "Adding custom row hover or focus paint around labels.",
+      "correction": "Keep the full row clickable while Brick confines visual interaction feedback to the checkbox square."
+    }
+  ],
+  "validation": [
+    "Inspect the group name, item labels and descriptions, unique values, repeated native form entries, required validity, reset, and disabled or read-only behavior.",
+    "Toggle Items and Parent with keyboard, pointer, and touch; verify none, mixed, and all states against the exact declared allValues set.",
+    "Check vertical and horizontal wrapping, long localized labels, 320 CSS pixels, 200% text, 400% zoom, RTL, dark appearance, and forced colors.",
+    "Confirm application-owned filtering, persistence, URL state, counts, and asynchronous results remain outside Checkbox Group."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "checkbox-group",
+      "versionPolicy": "installed-exact"
+    },
+    "checkbox",
+    "fieldset",
+    "radio-group",
+    "toggle-group",
+    "select",
+    "combobox",
+    "form"
+  ]
+}

package/dist/agents/checkbox-group.md

@@ -0,0 +1,56 @@
+# Checkbox Group agent guide
+
+## Purpose
+
+Coordinate related multi-selection with structured item labels, optional descriptions, native repeated form values, and an optional aggregate parent control.
+
+## Use when
+
+- Several independently selectable choices belong to one named group or need a select-all parent.
+
+## Choose something else when
+
+- The choice is independent and does not share group state. Use Checkbox.
+- Exactly one option must be selected. Use Radio Group or Select.
+- The interface needs remote option loading, search, or a generated filter engine. Use Combobox or application-owned discovery controls.
+
+## Required composition
+
+- Give Root an accessible group name directly or compose it inside Fieldset with one visible Legend and shared description or error.
+- Compose Root with Item children; wrap each primary label in ItemLabel and supporting text in ItemDescription when structured item relationships are needed.
+- Use Parent only with an explicit allValues list containing the currently selectable declared values; omit individually disabled values and never infer the collection from rendered children.
+
+## Rules
+
+- **MUST:** Use Checkbox Group only for related multi-selection; keep one-of-many choice, independent consent, remote search, and application filter execution in their owning patterns.
+- **MUST:** Give Root a persistent accessible group name and every Item a complete visible associated label; placeholder or surrounding layout does not name the group.
+- **MUST:** Give every Item a unique stable string value and let the application own persistence, query synchronization, result counts, and filtering side effects.
+- **MUST:** Supply Parent allValues explicitly from the selectable declared set and do not include disabled choices or derive the set from DOM children.
+- **MUST:** Use the vertical default for scan-heavy groups and horizontal only when wrapped reading order remains clear under narrow widths, zoom, and localization.
+- **MUST:** Keep required or invalid messaging at group scope when any eligible option can satisfy the requirement; do not paint every Item as individually invalid.
+- **MUST:** Preserve disabled and read-only Items, one-or-more required validity, first-enabled validation focus, Fieldset relationships, named repeated-value submission, external form association, and uncontrolled reset.
+- **MUST:** Load styles.css or core.css plus checkbox-group.css and any Fieldset styles used.
+
+## Common mistakes
+
+- **Avoid:** Building a filter facet with unrelated standalone checkboxes and no group name. **Instead:** Use one named CheckboxGroup.Root with stable Item values and keep query execution in the application.
+- **Avoid:** Using Parent without an explicit current selectable set. **Instead:** Pass allValues deliberately so none, mixed, and all state remain deterministic.
+- **Avoid:** Adding custom row hover or focus paint around labels. **Instead:** Keep the full row clickable while Brick confines visual interaction feedback to the checkbox square.
+
+## Validation checklist
+
+- Inspect the group name, item labels and descriptions, unique values, repeated native form entries, required validity, reset, and disabled or read-only behavior.
+- Toggle Items and Parent with keyboard, pointer, and touch; verify none, mixed, and all states against the exact declared allValues set.
+- Check vertical and horizontal wrapping, long localized labels, 320 CSS pixels, 200% text, 400% zoom, RTL, dark appearance, and forced colors.
+- Confirm application-owned filtering, persistence, URL state, counts, and asynchronous results remain outside Checkbox Group.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/checkbox-group`
+- `checkbox`
+- `fieldset`
+- `radio-group`
+- `toggle-group`
+- `select`
+- `combobox`
+- `form`