@flowstack-ui/agent-tools 0.1.0-bootstrap.0

package/public/packages/brick/0.1.11/components/radio-group.txt

@@ -0,0 +1,152 @@
+# RadioGroup
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: radio-group
+
+# RadioGroup agent guide
+
+## Purpose
+
+Present a finished short visible form choice set with exactly one selected value while Atom owns radiogroup semantics, roving focus, keyboard selection, validation, and submission.
+
+## Use when
+
+- A user must choose exactly one option from a short visible list whose choices are best compared together.
+
+## Choose something else when
+
+- Several choices may be selected, a long list should stay compact, or the controls are pressed commands rather than form answers. Use CheckboxGroup, Select, or ToggleGroup.
+
+## Required composition
+
+- Give RadioGroup.Root an accessible group name and compose one uniquely valued RadioGroup.Item per visible option. Use Fieldset with Legend, Description, and Error when the set needs visible group labeling or validation context; use name and form when the selected value must submit.
+- Root owns sm, md, or lg size and vertical or horizontal layout. Each Item owns its complete visible option label while Brick supplies the private circular control and checked dot.
+
+## Rules
+
+- **MUST:** Use RadioGroup for exactly one short visible form choice; use CheckboxGroup for independent choices, Select for a compact longer list, and ToggleGroup for pressed commands.
+- **MUST:** Give Root an accessible group name through native ARIA or Fieldset Legend and give every Item a complete visible or native accessible option name.
+- **MUST:** Give every Item a stable unique value and use value with onValueChange for controlled state or defaultValue for uncontrolled state.
+- **MUST:** Preserve the selected or first enabled Item as the one Tab stop, disabled-item skipping, looping policy, and orientation- and direction-aware Arrow, Home, End, and Space behavior.
+- **MUST:** Use readOnly when the selected value must remain focusable and submitted while preventing pointer, Space, and navigation-driven changes; do not substitute disabled.
+- **MUST:** Preserve group-level required validity, first-enabled validation focus, Fieldset state and descriptions, named hidden-radio submission, and uncontrolled form reset.
+- **SHOULD:** Use vertical for scan-heavy groups and horizontal only when wrapped DOM reading order remains clear under narrow widths, zoom, localization, and RTL.
+- **MUST:** Load styles.css or core.css plus radio-group.css and Fieldset CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Omitting the group name, giving every Item a Tab stop, using RadioGroup for independent choices, or disabling a value that should remain read-only. **Instead:** Use the named Atom-owned roving group, choose CheckboxGroup for independent choices, and preserve focus and submission with readOnly.
+- **Avoid:** Treating the private circle or surrounding layout as the option label or applying validation to every row independently. **Instead:** Label every Item with its visible content and keep shared required or invalid messaging at Root or Fieldset scope.
+
+## Validation checklist
+
+- Verify Root and Item names, unique values, controlled and uncontrolled selection, one roving Tab stop, disabled skipping, vertical and horizontal Arrow keys, Home/End, Space, looping, explicit and inherited LTR and RTL, pointer activation, and composition semantics.
+- Verify read-only focus without value changes, group-level required validation with and without name, first-enabled validation focus, Fieldset descriptions and errors, hidden submission value, form association, and uncontrolled reset.
+- Verify three sizes, vertical and wrapping horizontal layout, long labels, narrow widths, 200% text and 400% zoom, touch targets, light and dark appearance, forced colors, RTL, and complete CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/radio-group`
+- `checkbox-group`
+- `select`
+- `toggle-group`
+- `fieldset`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "radio-group",
+  "name": "RadioGroup",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished short visible form choice set with exactly one selected value while Atom owns radiogroup semantics, roving focus, keyboard selection, validation, and submission.",
+  "useWhen": [
+    "A user must choose exactly one option from a short visible list whose choices are best compared together."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Several choices may be selected, a long list should stay compact, or the controls are pressed commands rather than form answers.",
+      "useInstead": "CheckboxGroup, Select, or ToggleGroup"
+    }
+  ],
+  "composition": [
+    "Give RadioGroup.Root an accessible group name and compose one uniquely valued RadioGroup.Item per visible option. Use Fieldset with Legend, Description, and Error when the set needs visible group labeling or validation context; use name and form when the selected value must submit.",
+    "Root owns sm, md, or lg size and vertical or horizontal layout. Each Item owns its complete visible option label while Brick supplies the private circular control and checked dot."
+  ],
+  "rules": [
+    {
+      "id": "radio-group-selection",
+      "level": "must",
+      "statement": "Use RadioGroup for exactly one short visible form choice; use CheckboxGroup for independent choices, Select for a compact longer list, and ToggleGroup for pressed commands."
+    },
+    {
+      "id": "radio-group-names",
+      "level": "must",
+      "statement": "Give Root an accessible group name through native ARIA or Fieldset Legend and give every Item a complete visible or native accessible option name."
+    },
+    {
+      "id": "radio-group-values",
+      "level": "must",
+      "statement": "Give every Item a stable unique value and use value with onValueChange for controlled state or defaultValue for uncontrolled state."
+    },
+    {
+      "id": "radio-group-roving",
+      "level": "must",
+      "statement": "Preserve the selected or first enabled Item as the one Tab stop, disabled-item skipping, looping policy, and orientation- and direction-aware Arrow, Home, End, and Space behavior."
+    },
+    {
+      "id": "radio-group-readonly",
+      "level": "must",
+      "statement": "Use readOnly when the selected value must remain focusable and submitted while preventing pointer, Space, and navigation-driven changes; do not substitute disabled."
+    },
+    {
+      "id": "radio-group-form",
+      "level": "must",
+      "statement": "Preserve group-level required validity, first-enabled validation focus, Fieldset state and descriptions, named hidden-radio submission, and uncontrolled form reset."
+    },
+    {
+      "id": "radio-group-responsive",
+      "level": "should",
+      "statement": "Use vertical for scan-heavy groups and horizontal only when wrapped DOM reading order remains clear under narrow widths, zoom, localization, and RTL."
+    },
+    {
+      "id": "radio-group-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus radio-group.css and Fieldset CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Omitting the group name, giving every Item a Tab stop, using RadioGroup for independent choices, or disabling a value that should remain read-only.",
+      "correction": "Use the named Atom-owned roving group, choose CheckboxGroup for independent choices, and preserve focus and submission with readOnly."
+    },
+    {
+      "mistake": "Treating the private circle or surrounding layout as the option label or applying validation to every row independently.",
+      "correction": "Label every Item with its visible content and keep shared required or invalid messaging at Root or Fieldset scope."
+    }
+  ],
+  "validation": [
+    "Verify Root and Item names, unique values, controlled and uncontrolled selection, one roving Tab stop, disabled skipping, vertical and horizontal Arrow keys, Home/End, Space, looping, explicit and inherited LTR and RTL, pointer activation, and composition semantics.",
+    "Verify read-only focus without value changes, group-level required validation with and without name, first-enabled validation focus, Fieldset descriptions and errors, hidden submission value, form association, and uncontrolled reset.",
+    "Verify three sizes, vertical and wrapping horizontal layout, long labels, narrow widths, 200% text and 400% zoom, touch targets, light and dark appearance, forced colors, RTL, and complete CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "radio-group",
+      "versionPolicy": "installed-exact"
+    },
+    "checkbox-group",
+    "select",
+    "toggle-group",
+    "fieldset",
+    "form"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/rating.txt

@@ -0,0 +1,151 @@
+# Rating
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: rating
+
+# Rating agent guide
+
+## Purpose
+
+Collect a short ordered score, present a repeated-star aggregate, or present a compact one-star numeric summary.
+
+## Use when
+
+- A person chooses a score on a short ordered scale, or an aggregate score needs recognizable repeated-star presentation.
+
+## Choose something else when
+
+- The value is a general numeric setting, a named choice, progress, or status. Use Slider, Radio Group, Progress, or Badge.
+
+## Required composition
+
+- For input, compose Root with one Item for every endpoint and use it as the sole control in Field or name the standalone Root.
+- For aggregate product or review data, use Display with repeated stars or Summary with one star and a visible value; give either a localized label and do not use readOnly Root as a passive summary.
+
+## Rules
+
+- **MUST:** Use Root and Item only when the person can choose a score; use Display for aggregate or read-only presentation so passive content does not create a focusable slider.
+- **MUST:** Give Display and Summary a localized label that states the score and maximum, such as label="4.5 out of 5 stars"; use Summary valueText for localized visible formatting and keep adjacent review counts as ordinary text.
+- **MUST:** Provide one visible Field label for an input Rating or a complete accessible name for a standalone Root.
+- **MUST:** Use a valid ordered min and max, positive step, and Item endpoint values; keep repeated selection stable by default and enable allowClear only when clearing to the minimum is intentional.
+- **MUST:** Preserve one focusable slider Root with decorative Items, one-pointer capture, cross-item dragging, vertical page scrolling, cancellation rollback, lost-capture finalization, keyboard steps, and horizontal LTR and RTL behavior.
+- **MUST:** Preserve disabled, read-only, invalid, required-above-minimum validity, Field relationships, named hidden submission, validation focus, and uncontrolled form reset for input Rating.
+- **MUST:** Load styles.css or core.css plus rating.css.
+
+## Common mistakes
+
+- **Avoid:** Using readOnly Root to show a product's average rating, creating a focusable slider that cannot be changed. **Instead:** Use Rating.Display for aggregate scores and reserve readOnly Root for rare form review states where slider semantics remain meaningful.
+- **Avoid:** Making every star focusable, repeating the score through five accessible icons, or relying on star color alone. **Instead:** Keep one logical Root for input or one labelled Display image for aggregate output; repeated artwork stays decorative.
+- **Avoid:** Using max=1 or an ordinary star Icon to fake a compact aggregate rating. **Instead:** Use Rating.Summary so one decorative star and the visible numeric value share one localized aggregate label.
+
+## Validation checklist
+
+- For input, check pointer, touch, keyboard, fractional values, form ownership, reset, disabled, read-only, invalid, and Field relationships.
+- For Display and Summary, check the localized accessible name, absence from tab order, aggregate geometry, RTL, forced colors, zoom, and long adjacent review text.
+- Confirm CSS is loaded.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/rating`
+- `field`
+- `slider`
+- `radio-group`
+- `progress`
+- `badge`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "rating",
+  "name": "Rating",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Collect a short ordered score, present a repeated-star aggregate, or present a compact one-star numeric summary.",
+  "useWhen": [
+    "A person chooses a score on a short ordered scale, or an aggregate score needs recognizable repeated-star presentation."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value is a general numeric setting, a named choice, progress, or status.",
+      "useInstead": "Slider, Radio Group, Progress, or Badge"
+    }
+  ],
+  "composition": [
+    "For input, compose Root with one Item for every endpoint and use it as the sole control in Field or name the standalone Root.",
+    "For aggregate product or review data, use Display with repeated stars or Summary with one star and a visible value; give either a localized label and do not use readOnly Root as a passive summary."
+  ],
+  "rules": [
+    {
+      "id": "rating-input-vs-display",
+      "level": "must",
+      "statement": "Use Root and Item only when the person can choose a score; use Display for aggregate or read-only presentation so passive content does not create a focusable slider."
+    },
+    {
+      "id": "rating-display-label",
+      "level": "must",
+      "statement": "Give Display and Summary a localized label that states the score and maximum, such as label=\"4.5 out of 5 stars\"; use Summary valueText for localized visible formatting and keep adjacent review counts as ordinary text."
+    },
+    {
+      "id": "rating-input-name",
+      "level": "must",
+      "statement": "Provide one visible Field label for an input Rating or a complete accessible name for a standalone Root."
+    },
+    {
+      "id": "rating-scale-clear",
+      "level": "must",
+      "statement": "Use a valid ordered min and max, positive step, and Item endpoint values; keep repeated selection stable by default and enable allowClear only when clearing to the minimum is intentional."
+    },
+    {
+      "id": "rating-input-behavior",
+      "level": "must",
+      "statement": "Preserve one focusable slider Root with decorative Items, one-pointer capture, cross-item dragging, vertical page scrolling, cancellation rollback, lost-capture finalization, keyboard steps, and horizontal LTR and RTL behavior."
+    },
+    {
+      "id": "rating-form-state",
+      "level": "must",
+      "statement": "Preserve disabled, read-only, invalid, required-above-minimum validity, Field relationships, named hidden submission, validation focus, and uncontrolled form reset for input Rating."
+    },
+    {
+      "id": "rating-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus rating.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using readOnly Root to show a product's average rating, creating a focusable slider that cannot be changed.",
+      "correction": "Use Rating.Display for aggregate scores and reserve readOnly Root for rare form review states where slider semantics remain meaningful."
+    },
+    {
+      "mistake": "Making every star focusable, repeating the score through five accessible icons, or relying on star color alone.",
+      "correction": "Keep one logical Root for input or one labelled Display image for aggregate output; repeated artwork stays decorative."
+    },
+    {
+      "mistake": "Using max=1 or an ordinary star Icon to fake a compact aggregate rating.",
+      "correction": "Use Rating.Summary so one decorative star and the visible numeric value share one localized aggregate label."
+    }
+  ],
+  "validation": [
+    "For input, check pointer, touch, keyboard, fractional values, form ownership, reset, disabled, read-only, invalid, and Field relationships.",
+    "For Display and Summary, check the localized accessible name, absence from tab order, aggregate geometry, RTL, forced colors, zoom, and long adjacent review text.",
+    "Confirm CSS is loaded."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "rating",
+      "versionPolicy": "installed-exact"
+    },
+    "field",
+    "slider",
+    "radio-group",
+    "progress",
+    "badge"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/reorderable-list.txt

@@ -0,0 +1,130 @@
+# Reorderable List
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: reorderable-list
+
+# Reorderable List agent guide
+
+## Purpose
+
+Provide a finished list for deliberate manual ordering while Atom owns drag, touch, keyboard, focus, announcements, cancellation, and reorder state behavior.
+
+## Use when
+
+- A person needs to arrange a small linear collection into a meaningful saved order.
+
+## Choose something else when
+
+- The application is sorting data automatically or changing a table sort key. Use DataGrid or an application-owned sort control.
+- Items move between columns, tree parents, freeform coordinates, or external applications. Use A dedicated Kanban, tree, spatial, or file-transfer composition over Atom DragDrop.
+- The content is static and has no manual ordering job. Use List.
+
+## Required composition
+
+- Compose Root > Item > Handle + Content + optional Actions containing direct Move controls + DropIndicator.
+- Keep application data keyed by each Item value and update that data from Root onItemsChange; persistence, Undo, conflicts, and validation remain application-owned.
+- Let Brick move direct Actions below Content when a vertical list's own container is narrow; do not add viewport logic or duplicate the item tree for this relationship.
+
+## Rules
+
+- **MUST:** Use stable unique values for Root items and matching Item values; never use visual indexes as identity.
+- **MUST:** Provide getItemLabel plus localized aria-label values for every Handle and direct Move control.
+- **MUST:** Provide direct movement controls when drag precision, switch access, voice access, or discoverability requires a visible non-drag path.
+- **MUST:** Keep persistence, Undo, optimistic updates, server conflicts, validation, and automatic sorting outside ReorderableList.
+- **MUST:** Load styles.css or core.css plus reorderable-list.css.
+
+## Common mistakes
+
+- **Avoid:** Using ReorderableList as a sortable table, persisting inside the component, omitting accessible movement names, or making drag the only usable path. **Instead:** Choose the component by user job, keep workflow state in the application, label every control, and expose direct movement where needed.
+
+## Validation checklist
+
+- Check direct movement, keyboard lift/move/drop/cancel, mouse and touch movement, focus preservation, disabled and read-only states, and announcement copy.
+- Check that narrow vertical lists preserve a useful content measure by moving direct Actions below Content, then check horizontal overflow, RTL, zoom, reduced motion, forced colors, light and dark appearance, focus-ring containment, and insertion feedback.
+
+## Related guidance
+
+- `list`
+- `data-grid`
+- `tree`
+- `swipeable-item`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "reorderable-list",
+  "name": "Reorderable List",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a finished list for deliberate manual ordering while Atom owns drag, touch, keyboard, focus, announcements, cancellation, and reorder state behavior.",
+  "useWhen": [
+    "A person needs to arrange a small linear collection into a meaningful saved order."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The application is sorting data automatically or changing a table sort key.",
+      "useInstead": "DataGrid or an application-owned sort control"
+    },
+    {
+      "condition": "Items move between columns, tree parents, freeform coordinates, or external applications.",
+      "useInstead": "A dedicated Kanban, tree, spatial, or file-transfer composition over Atom DragDrop"
+    },
+    {
+      "condition": "The content is static and has no manual ordering job.",
+      "useInstead": "List"
+    }
+  ],
+  "composition": [
+    "Compose Root > Item > Handle + Content + optional Actions containing direct Move controls + DropIndicator.",
+    "Keep application data keyed by each Item value and update that data from Root onItemsChange; persistence, Undo, conflicts, and validation remain application-owned.",
+    "Let Brick move direct Actions below Content when a vertical list's own container is narrow; do not add viewport logic or duplicate the item tree for this relationship."
+  ],
+  "rules": [
+    {
+      "id": "reorderable-list-stable-identity",
+      "level": "must",
+      "statement": "Use stable unique values for Root items and matching Item values; never use visual indexes as identity."
+    },
+    {
+      "id": "reorderable-list-labels",
+      "level": "must",
+      "statement": "Provide getItemLabel plus localized aria-label values for every Handle and direct Move control."
+    },
+    {
+      "id": "reorderable-list-alternative",
+      "level": "must",
+      "statement": "Provide direct movement controls when drag precision, switch access, voice access, or discoverability requires a visible non-drag path."
+    },
+    {
+      "id": "reorderable-list-ownership",
+      "level": "must",
+      "statement": "Keep persistence, Undo, optimistic updates, server conflicts, validation, and automatic sorting outside ReorderableList."
+    },
+    {
+      "id": "reorderable-list-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus reorderable-list.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using ReorderableList as a sortable table, persisting inside the component, omitting accessible movement names, or making drag the only usable path.",
+      "correction": "Choose the component by user job, keep workflow state in the application, label every control, and expose direct movement where needed."
+    }
+  ],
+  "validation": [
+    "Check direct movement, keyboard lift/move/drop/cancel, mouse and touch movement, focus preservation, disabled and read-only states, and announcement copy.",
+    "Check that narrow vertical lists preserve a useful content measure by moving direct Actions below Content, then check horizontal overflow, RTL, zoom, reduced motion, forced colors, light and dark appearance, focus-ring containment, and insertion feedback."
+  ],
+  "related": [
+    "list",
+    "data-grid",
+    "tree",
+    "swipeable-item"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/scroll-area.txt

@@ -0,0 +1,110 @@
+# ScrollArea
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: scroll-area
+
+# ScrollArea agent guide
+
+## Purpose
+
+Style a bounded scroll viewport and native scrollbar presentation while preserving Atom and native input behavior.
+
+## Use when
+
+- A rail, code region, table wrapper, or bounded panel needs Brick scrollbar presentation and owned overflow behavior.
+
+## Choose something else when
+
+- Ordinary page or content overflow works with native browser scrolling. Use native overflow.
+
+## Required composition
+
+- Compose Viewport inside Root and give Root a real size constraint from its parent layout; Brick's current native scrollbar presentation needs no authored Scrollbar or Thumb parts.
+
+## Rules
+
+- **MUST:** Provide a bounded size; ScrollArea cannot create meaningful scrolling without a constrained viewport.
+- **MUST:** Identify the parent that owns the maximum or fixed block size before styling Viewport; do not apply a random height directly to the scrolling part.
+- **MUST:** Preserve wheel, trackpad, touch, keyboard, focus, and nested page scrolling.
+- **MUST:** Load styles.css or core.css plus scroll-area.css.
+
+## Common mistakes
+
+- **Avoid:** Using ScrollArea for every overflow or hiding clipped table content without horizontal scrolling. **Instead:** Use native overflow by default and add ScrollArea with explicit horizontal behavior where it improves the contract.
+
+## Validation checklist
+
+- Test both axes, mouse, trackpad, touch, keyboard, focus ring, nested scrolling, mobile tables, zoom, and RTL.
+- Confirm the parent constraint, viewport geometry, and CSS are loaded.
+
+## Related guidance
+
+- `table`
+- `data-grid`
+- `code-block`
+- `sidebar`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "scroll-area",
+  "name": "ScrollArea",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Style a bounded scroll viewport and native scrollbar presentation while preserving Atom and native input behavior.",
+  "useWhen": [
+    "A rail, code region, table wrapper, or bounded panel needs Brick scrollbar presentation and owned overflow behavior."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Ordinary page or content overflow works with native browser scrolling.",
+      "useInstead": "native overflow"
+    }
+  ],
+  "composition": [
+    "Compose Viewport inside Root and give Root a real size constraint from its parent layout; Brick's current native scrollbar presentation needs no authored Scrollbar or Thumb parts."
+  ],
+  "rules": [
+    {
+      "id": "scroll-area-bounded",
+      "level": "must",
+      "statement": "Provide a bounded size; ScrollArea cannot create meaningful scrolling without a constrained viewport."
+    },
+    {
+      "id": "scroll-area-parent-owner",
+      "level": "must",
+      "statement": "Identify the parent that owns the maximum or fixed block size before styling Viewport; do not apply a random height directly to the scrolling part."
+    },
+    {
+      "id": "scroll-area-native",
+      "level": "must",
+      "statement": "Preserve wheel, trackpad, touch, keyboard, focus, and nested page scrolling."
+    },
+    {
+      "id": "scroll-area-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus scroll-area.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using ScrollArea for every overflow or hiding clipped table content without horizontal scrolling.",
+      "correction": "Use native overflow by default and add ScrollArea with explicit horizontal behavior where it improves the contract."
+    }
+  ],
+  "validation": [
+    "Test both axes, mouse, trackpad, touch, keyboard, focus ring, nested scrolling, mobile tables, zoom, and RTL.",
+    "Confirm the parent constraint, viewport geometry, and CSS are loaded."
+  ],
+  "related": [
+    "table",
+    "data-grid",
+    "code-block",
+    "sidebar"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/section.txt

@@ -0,0 +1,118 @@
+# Section
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: section
+
+# Section agent guide
+
+## Purpose
+
+Own themeable responsive block rhythm for major semantic page and application regions.
+
+## Use when
+
+- A thematic page or application region needs consistent large vertical rhythm beyond local component spacing.
+
+## Choose something else when
+
+- The need is child arrangement, inline measure, visual paint, or a complete content pattern. Use Stack/Grid, Container, Surface, or a qualified Block.
+
+## Required composition
+
+- Place Container inside Section for measured content; compose Surface with asChild around Section when paint must cover the Section rhythm; use Stack or Grid inside for child relationships.
+
+## Rules
+
+- **MUST:** Use Section's named responsive rhythm instead of repeating large page-section padding CSS.
+- **MUST:** Use the default section host only for a thematic grouping, normally with a heading; select as=div when spacing alone has no sectioning meaning.
+- **MUST:** Keep paint in Surface, inline measure in Container, and child arrangement in Stack or Grid rather than adding those responsibilities to Section.
+- **MUST:** Choose a named recipe first; customize documented Section variables only when the theme or one deliberate region needs a value the scale cannot express.
+- **MUST:** Load styles.css or core.css plus section.css.
+
+## Common mistakes
+
+- **Avoid:** Using Stack gap for page rhythm, Surface inset as section spacing, or Section as a generic div around every group. **Instead:** Assign each responsibility to Section, Surface, Container, Stack, or Grid and use as=div only when Section rhythm is useful without section semantics.
+
+## Validation checklist
+
+- Check named and responsive rhythm at constrained and wide widths, zoom, RTL, and vertical writing modes.
+- Confirm the section has appropriate document meaning and that Surface asChild composition produces one host when full-width paint is needed.
+
+## Related guidance
+
+- `container`
+- `surface`
+- `stack`
+- `grid`
+- `interface-composition`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "section",
+  "name": "Section",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Own themeable responsive block rhythm for major semantic page and application regions.",
+  "useWhen": [
+    "A thematic page or application region needs consistent large vertical rhythm beyond local component spacing."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The need is child arrangement, inline measure, visual paint, or a complete content pattern.",
+      "useInstead": "Stack/Grid, Container, Surface, or a qualified Block"
+    }
+  ],
+  "composition": [
+    "Place Container inside Section for measured content; compose Surface with asChild around Section when paint must cover the Section rhythm; use Stack or Grid inside for child relationships."
+  ],
+  "rules": [
+    {
+      "id": "section-rhythm-owner",
+      "level": "must",
+      "statement": "Use Section's named responsive rhythm instead of repeating large page-section padding CSS."
+    },
+    {
+      "id": "section-semantic-host",
+      "level": "must",
+      "statement": "Use the default section host only for a thematic grouping, normally with a heading; select as=div when spacing alone has no sectioning meaning."
+    },
+    {
+      "id": "section-boundaries",
+      "level": "must",
+      "statement": "Keep paint in Surface, inline measure in Container, and child arrangement in Stack or Grid rather than adding those responsibilities to Section."
+    },
+    {
+      "id": "section-customization",
+      "level": "must",
+      "statement": "Choose a named recipe first; customize documented Section variables only when the theme or one deliberate region needs a value the scale cannot express."
+    },
+    {
+      "id": "section-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus section.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Stack gap for page rhythm, Surface inset as section spacing, or Section as a generic div around every group.",
+      "correction": "Assign each responsibility to Section, Surface, Container, Stack, or Grid and use as=div only when Section rhythm is useful without section semantics."
+    }
+  ],
+  "validation": [
+    "Check named and responsive rhythm at constrained and wide widths, zoom, RTL, and vertical writing modes.",
+    "Confirm the section has appropriate document meaning and that Surface asChild composition produces one host when full-width paint is needed."
+  ],
+  "related": [
+    "container",
+    "surface",
+    "stack",
+    "grid",
+    "interface-composition"
+  ]
+}
+```