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

package/public/packages/brick/0.1.11/components/notification-badge.txt

@@ -0,0 +1,148 @@
+# NotificationBadge
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: notification-badge
+
+# NotificationBadge agent guide
+
+## Purpose
+
+Overlay a Brick-owned visual count or dot on exactly one element while Atom Badge supplies only the passive span host and the child or nearby content owns all accessible notification meaning.
+
+## Use when
+
+- One icon, Avatar, Button, or other single element needs compact visual notification metadata whose full meaning is present in the owning control name or nearby text.
+
+## Choose something else when
+
+- The content is an inline label or status, must announce automatically, performs an action itself, or the count would be the only accessible notification meaning. Use Badge, Status, a deliberately chosen live-region pattern, Button, or visible Text.
+
+## Required composition
+
+- Wrap exactly one React element in NotificationBadge and choose either count mode or dot mode, then choose tone, size, logical placement, and overlap for the child's shape. Include count or status meaning in the child control's accessible name or nearby visible status text.
+- Use count with a finite non-negative integer and deliberate max/showZero policy, or dot=true without count-only props. Keep child sizing, clipping, responsive placement, live announcements, and state effects outside NotificationBadge.
+
+## Rules
+
+- **MUST:** Wrap exactly one React element and keep NotificationBadge passive; the child retains its own element, interaction, focus, semantics, and accessible name.
+- **MUST:** Treat the visual indicator, count normalization, maximum formatting, visibility, logical placement, overlap, and overlay geometry as Brick-owned; Atom Badge supplies only a passive span root, not notification behavior.
+- **MUST:** Choose either dot mode or count mode; use only finite non-negative integer counts, understand invalid max falls back to 99, and use showZero deliberately because zero otherwise hides.
+- **MUST:** Keep the private indicator aria-hidden and include meaningful count or status in the owning control's accessible name/description or nearby visible text because an overlaid sibling is not incorporated automatically.
+- **MUST:** Do not assume changing count announces or add live semantics to the private indicator; use one deliberate application-owned live path only when urgency and frequency justify it.
+- **MUST:** Choose circular or rectangular overlap from the child geometry, preserve logical placement in RTL, and verify child clipping, focus rings, count growth, zoom, and responsive size without using physical offsets.
+- **MUST:** Load styles.css or core.css plus badge.css and the stylesheet for the wrapped Brick child.
+
+## Common mistakes
+
+- **Avoid:** Using the visual count as the only name, expecting it to announce, making the wrapper interactive, or passing count and dot together. **Instead:** Name the owning control or provide visible text, keep announcements application-owned, leave interaction on the child, and choose one visual mode.
+- **Avoid:** Using physical placement for RTL, circular overlap on a rectangular child by habit, or allowing the child to clip the indicator or focus ring. **Instead:** Choose logical placement and overlap from actual geometry and verify the complete composed boundary at responsive sizes.
+
+## Validation checklist
+
+- Verify one child; count and dot modes; valid, zero, invalid, and above-max counts; fallback max; showZero; invisible; all tones/sizes/placements/overlaps; root ref; native span props; and absence of unsupported asChild.
+- Verify indicator is aria-hidden, child semantics and focus remain intact, count meaning appears exactly once in the owning name/description or visible text, updates do not announce implicitly, and any application live path is not duplicated.
+- Verify single-digit circles and multi-digit pills, logical RTL placement, rectangular/circular overlap, child clipping, focus visibility, narrow layout, zoom, light/dark appearance, forced colors, and wrapped Avatar/Button/Icon geometry.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/badge`
+- `badge`
+- `avatar`
+- `button`
+- `icon-button`
+- `status`
+- `text`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "notification-badge",
+  "name": "NotificationBadge",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Overlay a Brick-owned visual count or dot on exactly one element while Atom Badge supplies only the passive span host and the child or nearby content owns all accessible notification meaning.",
+  "useWhen": [
+    "One icon, Avatar, Button, or other single element needs compact visual notification metadata whose full meaning is present in the owning control name or nearby text."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content is an inline label or status, must announce automatically, performs an action itself, or the count would be the only accessible notification meaning.",
+      "useInstead": "Badge, Status, a deliberately chosen live-region pattern, Button, or visible Text"
+    }
+  ],
+  "composition": [
+    "Wrap exactly one React element in NotificationBadge and choose either count mode or dot mode, then choose tone, size, logical placement, and overlap for the child's shape. Include count or status meaning in the child control's accessible name or nearby visible status text.",
+    "Use count with a finite non-negative integer and deliberate max/showZero policy, or dot=true without count-only props. Keep child sizing, clipping, responsive placement, live announcements, and state effects outside NotificationBadge."
+  ],
+  "rules": [
+    {
+      "id": "notification-badge-one-child",
+      "level": "must",
+      "statement": "Wrap exactly one React element and keep NotificationBadge passive; the child retains its own element, interaction, focus, semantics, and accessible name."
+    },
+    {
+      "id": "notification-badge-brick-owner",
+      "level": "must",
+      "statement": "Treat the visual indicator, count normalization, maximum formatting, visibility, logical placement, overlap, and overlay geometry as Brick-owned; Atom Badge supplies only a passive span root, not notification behavior."
+    },
+    {
+      "id": "notification-badge-mode",
+      "level": "must",
+      "statement": "Choose either dot mode or count mode; use only finite non-negative integer counts, understand invalid max falls back to 99, and use showZero deliberately because zero otherwise hides."
+    },
+    {
+      "id": "notification-badge-accessible-context",
+      "level": "must",
+      "statement": "Keep the private indicator aria-hidden and include meaningful count or status in the owning control's accessible name/description or nearby visible text because an overlaid sibling is not incorporated automatically."
+    },
+    {
+      "id": "notification-badge-live-boundary",
+      "level": "must",
+      "statement": "Do not assume changing count announces or add live semantics to the private indicator; use one deliberate application-owned live path only when urgency and frequency justify it."
+    },
+    {
+      "id": "notification-badge-responsive",
+      "level": "must",
+      "statement": "Choose circular or rectangular overlap from the child geometry, preserve logical placement in RTL, and verify child clipping, focus rings, count growth, zoom, and responsive size without using physical offsets."
+    },
+    {
+      "id": "notification-badge-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus badge.css and the stylesheet for the wrapped Brick child."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using the visual count as the only name, expecting it to announce, making the wrapper interactive, or passing count and dot together.",
+      "correction": "Name the owning control or provide visible text, keep announcements application-owned, leave interaction on the child, and choose one visual mode."
+    },
+    {
+      "mistake": "Using physical placement for RTL, circular overlap on a rectangular child by habit, or allowing the child to clip the indicator or focus ring.",
+      "correction": "Choose logical placement and overlap from actual geometry and verify the complete composed boundary at responsive sizes."
+    }
+  ],
+  "validation": [
+    "Verify one child; count and dot modes; valid, zero, invalid, and above-max counts; fallback max; showZero; invisible; all tones/sizes/placements/overlaps; root ref; native span props; and absence of unsupported asChild.",
+    "Verify indicator is aria-hidden, child semantics and focus remain intact, count meaning appears exactly once in the owning name/description or visible text, updates do not announce implicitly, and any application live path is not duplicated.",
+    "Verify single-digit circles and multi-digit pills, logical RTL placement, rectangular/circular overlap, child clipping, focus visibility, narrow layout, zoom, light/dark appearance, forced colors, and wrapped Avatar/Button/Icon geometry."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "badge",
+      "versionPolicy": "installed-exact"
+    },
+    "badge",
+    "avatar",
+    "button",
+    "icon-button",
+    "status",
+    "text"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/number-input.txt

@@ -0,0 +1,150 @@
+# NumberInput
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: number-input
+
+# NumberInput agent guide
+
+## Purpose
+
+Present finished exact numeric entry with typing and step actions while Atom owns parsing, formatting, limits, spinbutton keyboard behavior, validation, and numeric form submission.
+
+## Use when
+
+- A value is genuinely numeric and a person should type an exact value or adjust it in known increments.
+
+## Choose something else when
+
+- Digits identify something, adjustment by feel is primary, a small fixed set is valid, or the value is read-only completion. Use Input, Slider, Select or RadioGroup, or Progress.
+
+## Required composition
+
+- Compose a visibly labelled Field with NumberInput.Root containing exactly one NumberInput.Input plus optional NumberInput.Increment and NumberInput.Decrement. Name both step actions because their default artwork is decorative.
+- Choose outline, soft, or underline plus sm, md, or lg and an allowed shape on Root. Keep formatter and parser reversible, use number or null controlled state, and keep units and application quantity policy outside the component.
+
+## Rules
+
+- **MUST:** Use NumberInput only for values that can be meaningfully stepped and clamped; postal codes, phone numbers, account numbers, and similar identifiers remain Input values.
+- **MUST:** Render exactly one NumberInput.Input inside Root and keep Increment and Decrement inside that same Root so Atom retains numeric state, focus, limits, and aria-controls ownership.
+- **MUST:** Use number or null with value and onValueChange for controlled state, preserve intermediate editing, keep formatter and parser reversible, choose positive step and suitable precision, and decide clampOnBlur deliberately.
+- **MUST:** Give Input a visible Field label or equivalent accessible name and give Increment and Decrement localized action names while preserving spinbutton ARIA, Arrow/Page/Home/End keys, native validity, and pointer focus retention.
+- **MUST:** Keep the visible Input as validity owner and Root's named parsed value as the submission contract, including external form association, Field reporting, reset, disabled, read-only, required, and invalid state.
+- **MUST:** Keep the shrinkable input and fixed logical-end action column contained at narrow widths and in RTL; preserve coarse-pointer step targets and do not use viewport width as a touch proxy.
+- **MUST:** Load styles.css or core.css plus number-input.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Using NumberInput for digit-like identifiers, rendering more than one Input, formatting without a matching parser, or submitting display text as the numeric value. **Instead:** Choose Input for identifiers, keep one compound Input, make parsing and formatting symmetric, and preserve Atom's parsed form contract.
+- **Avoid:** Leaving decorative step buttons unnamed or adding unit selection and business limits inside the component. **Instead:** Name both actions and keep units, inventory rules, calculations, and other application policy at the application boundary.
+
+## Validation checklist
+
+- Verify controlled number and null state, uncontrolled default, intermediate typing, parsing, formatting, precision, min/max, clampOnBlur, step and largeStep, Arrow/Page/Home/End, empty state, boundary action state, and pointer/touch focus preservation.
+- Verify visible naming, localized step-action names, required and numeric native validity, Field reporting, named parsed submission, external form, reset, disabled/read-only behavior, refs, native props, and custom action children.
+- Verify outline, soft, and underline recipes; all sizes and allowed shapes; full-width and intrinsic layouts; narrow width, coarse pointer, RTL, zoom, forced colors, light and dark appearance, focus, invalid, and disabled paint.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/number-input`
+- `input`
+- `slider`
+- `progress`
+- `select`
+- `radio-group`
+- `field`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "number-input",
+  "name": "NumberInput",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present finished exact numeric entry with typing and step actions while Atom owns parsing, formatting, limits, spinbutton keyboard behavior, validation, and numeric form submission.",
+  "useWhen": [
+    "A value is genuinely numeric and a person should type an exact value or adjust it in known increments."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Digits identify something, adjustment by feel is primary, a small fixed set is valid, or the value is read-only completion.",
+      "useInstead": "Input, Slider, Select or RadioGroup, or Progress"
+    }
+  ],
+  "composition": [
+    "Compose a visibly labelled Field with NumberInput.Root containing exactly one NumberInput.Input plus optional NumberInput.Increment and NumberInput.Decrement. Name both step actions because their default artwork is decorative.",
+    "Choose outline, soft, or underline plus sm, md, or lg and an allowed shape on Root. Keep formatter and parser reversible, use number or null controlled state, and keep units and application quantity policy outside the component."
+  ],
+  "rules": [
+    {
+      "id": "number-input-numeric-domain",
+      "level": "must",
+      "statement": "Use NumberInput only for values that can be meaningfully stepped and clamped; postal codes, phone numbers, account numbers, and similar identifiers remain Input values."
+    },
+    {
+      "id": "number-input-one-input",
+      "level": "must",
+      "statement": "Render exactly one NumberInput.Input inside Root and keep Increment and Decrement inside that same Root so Atom retains numeric state, focus, limits, and aria-controls ownership."
+    },
+    {
+      "id": "number-input-state-format",
+      "level": "must",
+      "statement": "Use number or null with value and onValueChange for controlled state, preserve intermediate editing, keep formatter and parser reversible, choose positive step and suitable precision, and decide clampOnBlur deliberately."
+    },
+    {
+      "id": "number-input-accessibility",
+      "level": "must",
+      "statement": "Give Input a visible Field label or equivalent accessible name and give Increment and Decrement localized action names while preserving spinbutton ARIA, Arrow/Page/Home/End keys, native validity, and pointer focus retention."
+    },
+    {
+      "id": "number-input-form",
+      "level": "must",
+      "statement": "Keep the visible Input as validity owner and Root's named parsed value as the submission contract, including external form association, Field reporting, reset, disabled, read-only, required, and invalid state."
+    },
+    {
+      "id": "number-input-responsive",
+      "level": "must",
+      "statement": "Keep the shrinkable input and fixed logical-end action column contained at narrow widths and in RTL; preserve coarse-pointer step targets and do not use viewport width as a touch proxy."
+    },
+    {
+      "id": "number-input-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus number-input.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using NumberInput for digit-like identifiers, rendering more than one Input, formatting without a matching parser, or submitting display text as the numeric value.",
+      "correction": "Choose Input for identifiers, keep one compound Input, make parsing and formatting symmetric, and preserve Atom's parsed form contract."
+    },
+    {
+      "mistake": "Leaving decorative step buttons unnamed or adding unit selection and business limits inside the component.",
+      "correction": "Name both actions and keep units, inventory rules, calculations, and other application policy at the application boundary."
+    }
+  ],
+  "validation": [
+    "Verify controlled number and null state, uncontrolled default, intermediate typing, parsing, formatting, precision, min/max, clampOnBlur, step and largeStep, Arrow/Page/Home/End, empty state, boundary action state, and pointer/touch focus preservation.",
+    "Verify visible naming, localized step-action names, required and numeric native validity, Field reporting, named parsed submission, external form, reset, disabled/read-only behavior, refs, native props, and custom action children.",
+    "Verify outline, soft, and underline recipes; all sizes and allowed shapes; full-width and intrinsic layouts; narrow width, coarse pointer, RTL, zoom, forced colors, light and dark appearance, focus, invalid, and disabled paint."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "number-input",
+      "versionPolicy": "installed-exact"
+    },
+    "input",
+    "slider",
+    "progress",
+    "select",
+    "radio-group",
+    "field",
+    "form"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/otp-field.txt

@@ -0,0 +1,146 @@
+# OTPField
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: otp-field
+
+# OTPField agent guide
+
+## Purpose
+
+Present one short verification, recovery, or pairing code as finished segmented entry while Atom owns filtering, paste distribution, roving focus, completion, validation, reset, and combined-value submission.
+
+## Use when
+
+- A person enters or pastes a short one-time code supplied through another channel into visually separated cells.
+
+## Choose something else when
+
+- The value is a reusable password, permanent PIN, numeric quantity, arbitrary identifier, or ordinary variable-length text. Use PasswordToggleField, NumberInput, or Input according to the actual entry job.
+
+## Required composition
+
+- Compose one visibly labelled Field with OTPField.Root, then render exactly one OTPField.Input for each normalized length position in stable logical source order. Add aria-hidden Separator only for deliberate visual grouping; layout wrappers may group cells without creating separate values.
+- Give Root one accessible group name, character type, length, and submission name. Localize getInputLabel for every position and treat autoSubmit and autoFocus as explicit application workflow decisions.
+
+## Rules
+
+- **MUST:** Treat all cells as one logical code, match visible Input count and order to Root length, and never create independent application state, validation, or submission names for each cell.
+- **MUST:** Choose numeric, alphabetic, alphanumeric, or a safe custom pattern that accepts exactly the intended characters and preserve the same filtering for typing and paste.
+- **MUST:** Name Root through Field or native ARIA, localize every generated position label, keep Separator decorative, and do not add unsupported aria-required to role=group.
+- **MUST:** Preserve one roving Tab stop, render-order registration, replacement and advance, Arrow/Home/End, Backspace/Delete, complete-code paste, disabled/read-only state, and logical source order in RTL.
+- **MUST:** Enable autoSubmit only when a complete accepted code should intentionally submit the associated form, with application-owned pending, verification, error, retry, and focus recovery behavior; choose autoFocus just as deliberately.
+- **MUST:** Keep required validity on the first visible cell and Root's named combined value submission-only, including Field invalid mirroring, external form association, and uncontrolled reset.
+- **MUST:** Load styles.css or core.css plus otp-field.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Building unrelated character inputs, rendering a different cell count than length, blocking paste, reversing cells in RTL, leaving generated labels unlocalized, or auto-submitting by habit. **Instead:** Use one named OTPField value, align cells to length and logical order, preserve Atom entry behavior, localize labels, and make submission an explicit application decision.
+- **Avoid:** Putting code delivery, expiry, resend, attempt limits, rate limiting, or verification inside the component. **Instead:** Keep security and workflow policy in the application or service and let OTPField report value and completion only.
+
+## Validation checklist
+
+- Verify controlled and uncontrolled full value, length, render-order and explicit indices, all filters, typing replacement, accepted paste distribution, Backspace/Delete, Arrow/Home/End, one roving Tab stop, deliberate autoFocus, mask display, disabled/read-only behavior, and localized cell labels.
+- Verify onComplete timing, intentional autoSubmit, Root and Field naming/descriptions, required validity on the first cell, invalid state across cells, inline/native validation focus, combined named value, external form, reset, separators, native props, render composition, and refs.
+- Verify deliberate wrapping and grouping, 320 CSS pixels, 200% text, 400% zoom, RTL logical order, touch targets, long localized labels, focus visibility, forced colors, and every supported appearance.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/otp-field`
+- `password-toggle-field`
+- `number-input`
+- `input`
+- `field`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "otp-field",
+  "name": "OTPField",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present one short verification, recovery, or pairing code as finished segmented entry while Atom owns filtering, paste distribution, roving focus, completion, validation, reset, and combined-value submission.",
+  "useWhen": [
+    "A person enters or pastes a short one-time code supplied through another channel into visually separated cells."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value is a reusable password, permanent PIN, numeric quantity, arbitrary identifier, or ordinary variable-length text.",
+      "useInstead": "PasswordToggleField, NumberInput, or Input according to the actual entry job"
+    }
+  ],
+  "composition": [
+    "Compose one visibly labelled Field with OTPField.Root, then render exactly one OTPField.Input for each normalized length position in stable logical source order. Add aria-hidden Separator only for deliberate visual grouping; layout wrappers may group cells without creating separate values.",
+    "Give Root one accessible group name, character type, length, and submission name. Localize getInputLabel for every position and treat autoSubmit and autoFocus as explicit application workflow decisions."
+  ],
+  "rules": [
+    {
+      "id": "otp-field-one-value",
+      "level": "must",
+      "statement": "Treat all cells as one logical code, match visible Input count and order to Root length, and never create independent application state, validation, or submission names for each cell."
+    },
+    {
+      "id": "otp-field-filter",
+      "level": "must",
+      "statement": "Choose numeric, alphabetic, alphanumeric, or a safe custom pattern that accepts exactly the intended characters and preserve the same filtering for typing and paste."
+    },
+    {
+      "id": "otp-field-labels",
+      "level": "must",
+      "statement": "Name Root through Field or native ARIA, localize every generated position label, keep Separator decorative, and do not add unsupported aria-required to role=group."
+    },
+    {
+      "id": "otp-field-focus-input",
+      "level": "must",
+      "statement": "Preserve one roving Tab stop, render-order registration, replacement and advance, Arrow/Home/End, Backspace/Delete, complete-code paste, disabled/read-only state, and logical source order in RTL."
+    },
+    {
+      "id": "otp-field-completion",
+      "level": "must",
+      "statement": "Enable autoSubmit only when a complete accepted code should intentionally submit the associated form, with application-owned pending, verification, error, retry, and focus recovery behavior; choose autoFocus just as deliberately."
+    },
+    {
+      "id": "otp-field-form",
+      "level": "must",
+      "statement": "Keep required validity on the first visible cell and Root's named combined value submission-only, including Field invalid mirroring, external form association, and uncontrolled reset."
+    },
+    {
+      "id": "otp-field-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus otp-field.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Building unrelated character inputs, rendering a different cell count than length, blocking paste, reversing cells in RTL, leaving generated labels unlocalized, or auto-submitting by habit.",
+      "correction": "Use one named OTPField value, align cells to length and logical order, preserve Atom entry behavior, localize labels, and make submission an explicit application decision."
+    },
+    {
+      "mistake": "Putting code delivery, expiry, resend, attempt limits, rate limiting, or verification inside the component.",
+      "correction": "Keep security and workflow policy in the application or service and let OTPField report value and completion only."
+    }
+  ],
+  "validation": [
+    "Verify controlled and uncontrolled full value, length, render-order and explicit indices, all filters, typing replacement, accepted paste distribution, Backspace/Delete, Arrow/Home/End, one roving Tab stop, deliberate autoFocus, mask display, disabled/read-only behavior, and localized cell labels.",
+    "Verify onComplete timing, intentional autoSubmit, Root and Field naming/descriptions, required validity on the first cell, invalid state across cells, inline/native validation focus, combined named value, external form, reset, separators, native props, render composition, and refs.",
+    "Verify deliberate wrapping and grouping, 320 CSS pixels, 200% text, 400% zoom, RTL logical order, touch targets, long localized labels, focus visibility, forced colors, and every supported appearance."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "otp-field",
+      "versionPolicy": "installed-exact"
+    },
+    "password-toggle-field",
+    "number-input",
+    "input",
+    "field",
+    "form"
+  ]
+}
+```

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

@@ -0,0 +1,124 @@
+# Pagination
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: pagination
+
+# Pagination agent guide
+
+## Purpose
+
+Present polished movement through ordered result pages with current, boundary, and ellipsis states.
+
+## Use when
+
+- A result set or collection is divided into multiple ordered pages.
+
+## Choose something else when
+
+- The controls move between guide articles, ancestors, or local panels. Use Link composition, Breadcrumb, or Tabs.
+
+## Required composition
+
+- Compose Root and List with Previous, Items or explicit Item and Ellipsis parts, and Next.
+- For URL-backed results, provide Root getPageHref and derive controlled page from the current route; keep fetching, sorting, filters, and post-load focus in the application.
+- Use boundaryVariant="outline" when only Previous and Next need outlined boundary treatment; keep numbered items on their normal current and interaction recipes.
+
+## Rules
+
+- **MUST:** Use Root getPageHref for URL-backed pages so controls are real anchors and native reload, sharing, history, and modified clicks continue to work.
+- **MUST:** Keep the authored range in one scrollable inline row at narrow widths without removing previous/next meaning or current-page state.
+- **MUST:** Use Root boundaryVariant rather than styling Previous and Next individually when the same boundary treatment repeats across a Pagination.
+- **MUST:** Load styles.css or core.css plus pagination.css.
+
+## Common mistakes
+
+- **Avoid:** Rendering URL-backed pages as buttons, composing anchors while Root remains in button mode, or using Pagination for previous/next documentation guides. **Instead:** Select link mode with Root getPageHref; use ordinary guide navigation links when page numbers do not carry meaning.
+- **Avoid:** Allowing controls to wrap into an unreadable grid or leaving boundary anchors live. **Instead:** Keep the list in its owned inline overflow and verify boundary links have no href and leave sequential focus.
+- **Avoid:** Adding local border-color styles to Previous and Next to imitate an outlined Pagination. **Instead:** Set boundaryVariant="outline" on Pagination.Root so Brick owns the complete light, dark, hover, disabled, and forced-color treatment.
+
+## Validation checklist
+
+- Check first, middle, last, current, disabled, ellipsis, long labels, narrow widths, focus, touch targets, and RTL.
+- For URL mode, confirm real href values, reload, share, Back/Forward, Cmd/Ctrl-click, and inert boundary links.
+- Confirm CSS is loaded.
+
+## Related guidance
+
+- `breadcrumb`
+- `link`
+- `button`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "pagination",
+  "name": "Pagination",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present polished movement through ordered result pages with current, boundary, and ellipsis states.",
+  "useWhen": [
+    "A result set or collection is divided into multiple ordered pages."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The controls move between guide articles, ancestors, or local panels.",
+      "useInstead": "Link composition, Breadcrumb, or Tabs"
+    }
+  ],
+  "composition": [
+    "Compose Root and List with Previous, Items or explicit Item and Ellipsis parts, and Next.",
+    "For URL-backed results, provide Root getPageHref and derive controlled page from the current route; keep fetching, sorting, filters, and post-load focus in the application.",
+    "Use boundaryVariant=\"outline\" when only Previous and Next need outlined boundary treatment; keep numbered items on their normal current and interaction recipes."
+  ],
+  "rules": [
+    {
+      "id": "pagination-url-mode",
+      "level": "must",
+      "statement": "Use Root getPageHref for URL-backed pages so controls are real anchors and native reload, sharing, history, and modified clicks continue to work."
+    },
+    {
+      "id": "pagination-responsive",
+      "level": "must",
+      "statement": "Keep the authored range in one scrollable inline row at narrow widths without removing previous/next meaning or current-page state."
+    },
+    {
+      "id": "pagination-boundary-treatment",
+      "level": "must",
+      "statement": "Use Root boundaryVariant rather than styling Previous and Next individually when the same boundary treatment repeats across a Pagination."
+    },
+    {
+      "id": "pagination-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus pagination.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Rendering URL-backed pages as buttons, composing anchors while Root remains in button mode, or using Pagination for previous/next documentation guides.",
+      "correction": "Select link mode with Root getPageHref; use ordinary guide navigation links when page numbers do not carry meaning."
+    },
+    {
+      "mistake": "Allowing controls to wrap into an unreadable grid or leaving boundary anchors live.",
+      "correction": "Keep the list in its owned inline overflow and verify boundary links have no href and leave sequential focus."
+    },
+    {
+      "mistake": "Adding local border-color styles to Previous and Next to imitate an outlined Pagination.",
+      "correction": "Set boundaryVariant=\"outline\" on Pagination.Root so Brick owns the complete light, dark, hover, disabled, and forced-color treatment."
+    }
+  ],
+  "validation": [
+    "Check first, middle, last, current, disabled, ellipsis, long labels, narrow widths, focus, touch targets, and RTL.",
+    "For URL mode, confirm real href values, reload, share, Back/Forward, Cmd/Ctrl-click, and inert boundary links.",
+    "Confirm CSS is loaded."
+  ],
+  "related": [
+    "breadcrumb",
+    "link",
+    "button"
+  ]
+}
+```