@flowstack-ui/brick 0.1.9 → 0.1.12

package/dist/agents/otp-field.json

@@ -0,0 +1,87 @@
+{
+  "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/dist/agents/otp-field.md

@@ -0,0 +1,48 @@
+# 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`

package/dist/agents/pagination.json

@@ -16,13 +16,25 @@
     }
   ],
   "composition": [
-    "Compose Root and List with Previous, Page, Ellipsis, and Next parts; use real destinations when each page has a URL."
+    "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": "Adapt visible page ranges at narrow widths without removing previous/next meaning or current-page state."
+      "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",
@@ -32,13 +44,22 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Using Pagination for previous/next documentation guides or allowing controls to wrap into an unreadable grid.",
-      "correction": "Use ordinary guide navigation links and reserve Pagination for numbered collections."
+      "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.",
-    "Confirm URL pages are links and CSS is loaded."
+    "For URL mode, confirm real href values, reload, share, Back/Forward, Cmd/Ctrl-click, and inert boundary links.",
+    "Confirm CSS is loaded."
   ],
   "related": [
     "breadcrumb",

package/dist/agents/pagination.md

@@ -14,21 +14,28 @@ Present polished movement through ordered result pages with current, boundary, a
 
 ## Required composition
 
-- Compose Root and List with Previous, Page, Ellipsis, and Next parts; use real destinations when each page has a URL.
+- 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:** Adapt visible page ranges at narrow widths without removing previous/next meaning or current-page state.
+- **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:** Using Pagination for previous/next documentation guides or allowing controls to wrap into an unreadable grid. **Instead:** Use ordinary guide navigation links and reserve Pagination for numbered collections.
+- **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.
-- Confirm URL pages are links and CSS is loaded.
+- For URL mode, confirm real href values, reload, share, Back/Forward, Cmd/Ctrl-click, and inert boundary links.
+- Confirm CSS is loaded.
 
 ## Related guidance
 

package/dist/agents/password-toggle-field.json

@@ -0,0 +1,87 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "password-toggle-field",
+  "name": "PasswordToggleField",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present finished native password entry with a named reveal action while Atom owns visibility, type switching, focus retention, Field validation, reset, and submission safety.",
+  "useWhen": [
+    "A reusable password benefits from an explicit keyboard-accessible reveal action and revealing it is acceptable for the product's privacy model."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value is ordinary text or a one-time code, or security, observation, or shared-device policy forbids revealing the secret.",
+      "useInstead": "Input, OTPField, or Input with type=password without a reveal control"
+    }
+  ],
+  "composition": [
+    "Compose a visible Field.Label, then PasswordToggleField.Root with exactly one Input and Toggle. Let Toggle render Brick's private default Icon or supply decorative product artwork without replacing its action name.",
+    "Choose the Input-family recipe, size, shape, and width on Root; set autocomplete deliberately and localize Root showLabel and hideLabel as the next available actions."
+  ],
+  "rules": [
+    {
+      "id": "password-toggle-policy",
+      "level": "must",
+      "statement": "Include the reveal action only when it is acceptable for the product's security, privacy, observation, recording, and shared-device context."
+    },
+    {
+      "id": "password-toggle-input-owner",
+      "level": "must",
+      "statement": "Keep Input as the native value, naming, autocomplete, validity, and submission owner while Atom changes only its owned type between password and text."
+    },
+    {
+      "id": "password-toggle-action-name",
+      "level": "must",
+      "statement": "Provide localized state-aware showLabel and hideLabel values that describe the next action; do not add aria-pressed because the changing action name communicates the available action."
+    },
+    {
+      "id": "password-toggle-focus",
+      "level": "must",
+      "statement": "Preserve Input focus on Toggle pointer down while keeping Toggle sequentially keyboard reachable by Tab, Enter, and Space."
+    },
+    {
+      "id": "password-toggle-state-form",
+      "level": "must",
+      "statement": "Use visible with onVisibleChange or defaultVisible, preserve Field disabled/read-only/required/invalid behavior, reset uncontrolled visibility, and let Atom restore type=password before native submission."
+    },
+    {
+      "id": "password-toggle-application-policy",
+      "level": "must",
+      "statement": "Keep password strength, generation, confirmation, storage, authentication, clipboard, and security policy in the application or service."
+    },
+    {
+      "id": "password-toggle-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus password-toggle-field.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Adding reveal where policy forbids it, using an unlabeled eye or aria-pressed, moving pointer focus from Input, or submitting while the DOM input remains type=text.",
+      "correction": "Apply the privacy decision first and preserve Atom's state-aware action, focus, reset, validation, and submit-time password restoration."
+    },
+    {
+      "mistake": "Writing a second visibility state, replacing Field relationships, or moving password policy into the styled component.",
+      "correction": "Use the complete Root, Input, Toggle, and optional Icon anatomy and keep product policy in the application."
+    }
+  ],
+  "validation": [
+    "Verify visible Field naming, autocomplete, native props, controlled and uncontrolled visibility, password/text switching, localized Show/Hide actions, decorative Icon state, pointer focus retention, keyboard Tab/Enter/Space, disabled/read-only behavior, custom Toggle composition, and refs.",
+    "Verify Field ID, label, description, and error inheritance with native overrides; required/invalid inline and native validation; reset to defaultVisible; type=password restoration before submission; external form; and no unintended live-region or aria-pressed semantics.",
+    "Verify all recipes, sizes, allowed shapes, width modes, long localization, narrow width, zoom, RTL, light and dark appearance, forced colors, hover, focus, invalid, disabled, and read-only paint."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "password-toggle-field",
+      "versionPolicy": "installed-exact"
+    },
+    "field",
+    "input",
+    "otp-field",
+    "form",
+    "button"
+  ]
+}

package/dist/agents/password-toggle-field.md

@@ -0,0 +1,48 @@
+# PasswordToggleField agent guide
+
+## Purpose
+
+Present finished native password entry with a named reveal action while Atom owns visibility, type switching, focus retention, Field validation, reset, and submission safety.
+
+## Use when
+
+- A reusable password benefits from an explicit keyboard-accessible reveal action and revealing it is acceptable for the product's privacy model.
+
+## Choose something else when
+
+- The value is ordinary text or a one-time code, or security, observation, or shared-device policy forbids revealing the secret. Use Input, OTPField, or Input with type=password without a reveal control.
+
+## Required composition
+
+- Compose a visible Field.Label, then PasswordToggleField.Root with exactly one Input and Toggle. Let Toggle render Brick's private default Icon or supply decorative product artwork without replacing its action name.
+- Choose the Input-family recipe, size, shape, and width on Root; set autocomplete deliberately and localize Root showLabel and hideLabel as the next available actions.
+
+## Rules
+
+- **MUST:** Include the reveal action only when it is acceptable for the product's security, privacy, observation, recording, and shared-device context.
+- **MUST:** Keep Input as the native value, naming, autocomplete, validity, and submission owner while Atom changes only its owned type between password and text.
+- **MUST:** Provide localized state-aware showLabel and hideLabel values that describe the next action; do not add aria-pressed because the changing action name communicates the available action.
+- **MUST:** Preserve Input focus on Toggle pointer down while keeping Toggle sequentially keyboard reachable by Tab, Enter, and Space.
+- **MUST:** Use visible with onVisibleChange or defaultVisible, preserve Field disabled/read-only/required/invalid behavior, reset uncontrolled visibility, and let Atom restore type=password before native submission.
+- **MUST:** Keep password strength, generation, confirmation, storage, authentication, clipboard, and security policy in the application or service.
+- **MUST:** Load styles.css or core.css plus password-toggle-field.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Adding reveal where policy forbids it, using an unlabeled eye or aria-pressed, moving pointer focus from Input, or submitting while the DOM input remains type=text. **Instead:** Apply the privacy decision first and preserve Atom's state-aware action, focus, reset, validation, and submit-time password restoration.
+- **Avoid:** Writing a second visibility state, replacing Field relationships, or moving password policy into the styled component. **Instead:** Use the complete Root, Input, Toggle, and optional Icon anatomy and keep product policy in the application.
+
+## Validation checklist
+
+- Verify visible Field naming, autocomplete, native props, controlled and uncontrolled visibility, password/text switching, localized Show/Hide actions, decorative Icon state, pointer focus retention, keyboard Tab/Enter/Space, disabled/read-only behavior, custom Toggle composition, and refs.
+- Verify Field ID, label, description, and error inheritance with native overrides; required/invalid inline and native validation; reset to defaultVisible; type=password restoration before submission; external form; and no unintended live-region or aria-pressed semantics.
+- Verify all recipes, sizes, allowed shapes, width modes, long localization, narrow width, zoom, RTL, light and dark appearance, forced colors, hover, focus, invalid, disabled, and read-only paint.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/password-toggle-field`
+- `field`
+- `input`
+- `otp-field`
+- `form`
+- `button`

package/dist/agents/popover.json

@@ -0,0 +1,114 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "popover",
+  "name": "Popover",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished compact click-open interactive panel anchored to a trigger or explicit anchor while Atom owns placement, dismissal, focus, portal, and optional modal behavior.",
+  "useWhen": [
+    "A trigger needs a small contextual panel for details, filters, or compact editing that belongs near its point of invocation."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content is noninteractive help, a passive hover preview, a command or option collection, or a larger blocking task.",
+      "useInstead": "Tooltip, HoverCard, Menu, Select or Combobox, or Dialog"
+    },
+    {
+      "condition": "The task should enter from a screen edge or remain as persistent page content.",
+      "useInstead": "Drawer or an in-page Brick composition"
+    }
+  ],
+  "composition": [
+    "Compose Popover.Root with Popover.Trigger and Popover.Portal; add Popover.Anchor only when positioning must reference an element other than Trigger. Inside Popover.Content, arrange Header with Title and optional Description, Body, Footer, and Close as needed; keep Arrow as a direct Content child.",
+    "Use density=compact for concise filter and utility panels. When a local Appearance scope owns the trigger, portal into that scope or apply the same Appearance to Content because ordinary portal ancestry does not preserve the local theme boundary."
+  ],
+  "rules": [
+    {
+      "id": "popover-click-context",
+      "level": "must",
+      "statement": "Use Brick Popover for compact click-open interactive work; choose Menu, Select, or Combobox when the panel's job is command or option selection, and Dialog for a larger blocking workflow."
+    },
+    {
+      "id": "popover-complete-anatomy",
+      "level": "must",
+      "statement": "Keep Trigger and portalled Content inside one Root, use Anchor only for a distinct positioning reference, and use the public structure parts instead of recreating panel spacing or hierarchy with private selectors."
+    },
+    {
+      "id": "popover-accessible-name",
+      "level": "must",
+      "statement": "Give Content an accessible name with one visible Title or an explicit native aria-label or aria-labelledby; add Description or native aria-describedby only when descriptive text is present."
+    },
+    {
+      "id": "popover-modal-choice",
+      "level": "must",
+      "statement": "Keep the default non-modal behavior for ordinary attached work; set modal only when the compact panel must trap focus, isolate the background, and lock document scrolling."
+    },
+    {
+      "id": "popover-visible-close",
+      "level": "must",
+      "statement": "Provide a visible Close when modal is enabled or when outside interaction, Escape, and trigger toggling do not make the dismissal path obvious."
+    },
+    {
+      "id": "popover-focus-dismissal",
+      "level": "must",
+      "statement": "Use the owned initial and final focus targets and onInteractOutside preventDefault contract when customization is required; do not replace Atom's focus-out, Escape, completed-interaction, restoration, and nested-layer handling."
+    },
+    {
+      "id": "popover-density",
+      "level": "must",
+      "statement": "Use the comfortable default for ordinary contextual work and density=compact for concise filter and utility panels; do not recreate compact rhythm with private selectors."
+    },
+    {
+      "id": "popover-theme-scope",
+      "level": "must",
+      "statement": "When Content leaves a local Appearance scope through Portal, reproduce that scope on the portalled visual root or target a container inside it."
+    },
+    {
+      "id": "popover-positioning-arrow",
+      "level": "must",
+      "statement": "Style from resolved data-side and available-size variables, keep Arrow as a direct Content child, and preserve its shared border and surface paint instead of assuming requested placement or independently recoloring it."
+    },
+    {
+      "id": "popover-responsive",
+      "level": "should",
+      "statement": "Keep the panel compact and verify collision shifts and flips, constrained scrolling, action reachability, zoom, touch input, narrow viewports, and LTR and RTL placement."
+    },
+    {
+      "id": "popover-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus popover.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Hand-positioning a floating div, using Popover for a menu or tooltip, forcing it modal for every utility panel, or closing it with ad hoc document listeners.",
+      "correction": "Choose by interaction job, use complete Popover anatomy, keep ordinary popovers non-modal, and use the preventable outside-interaction contract."
+    },
+    {
+      "mistake": "Assuming portalled Content inherits a nearby Appearance scope or placing Arrow inside an authored viewport wrapper.",
+      "correction": "Make the portal scope explicit and keep Arrow directly under Content so placement and finished surface paint remain intact."
+    }
+  ],
+  "validation": [
+    "Verify trigger and Content naming, controlled and disabled state, keyboard, pointer, and touch opening, initial focus, Tab behavior, Close, Escape, outside interaction, focus-out dismissal, outside focus destination, and trigger restoration.",
+    "Verify explicit Anchor positioning, collision shifts and flips at every supported side, LTR and RTL, available-size variables, direct Arrow geometry, constrained scrolling, nested portalled controlled layers, zoom, and narrow viewports.",
+    "When modal is enabled, verify a visible close path, focus containment, background isolation, scroll lock, and exit presence; check light and dark Appearance on actual portalled Content and required CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "popover",
+      "versionPolicy": "installed-exact"
+    },
+    "dialog",
+    "drawer",
+    "dropdown-menu",
+    "select",
+    "combobox",
+    "hover-card",
+    "tooltip",
+    "appearance"
+  ]
+}

package/dist/agents/popover.md

@@ -0,0 +1,56 @@
+# Popover agent guide
+
+## Purpose
+
+Present a finished compact click-open interactive panel anchored to a trigger or explicit anchor while Atom owns placement, dismissal, focus, portal, and optional modal behavior.
+
+## Use when
+
+- A trigger needs a small contextual panel for details, filters, or compact editing that belongs near its point of invocation.
+
+## Choose something else when
+
+- The content is noninteractive help, a passive hover preview, a command or option collection, or a larger blocking task. Use Tooltip, HoverCard, Menu, Select or Combobox, or Dialog.
+- The task should enter from a screen edge or remain as persistent page content. Use Drawer or an in-page Brick composition.
+
+## Required composition
+
+- Compose Popover.Root with Popover.Trigger and Popover.Portal; add Popover.Anchor only when positioning must reference an element other than Trigger. Inside Popover.Content, arrange Header with Title and optional Description, Body, Footer, and Close as needed; keep Arrow as a direct Content child.
+- Use density=compact for concise filter and utility panels. When a local Appearance scope owns the trigger, portal into that scope or apply the same Appearance to Content because ordinary portal ancestry does not preserve the local theme boundary.
+
+## Rules
+
+- **MUST:** Use Brick Popover for compact click-open interactive work; choose Menu, Select, or Combobox when the panel's job is command or option selection, and Dialog for a larger blocking workflow.
+- **MUST:** Keep Trigger and portalled Content inside one Root, use Anchor only for a distinct positioning reference, and use the public structure parts instead of recreating panel spacing or hierarchy with private selectors.
+- **MUST:** Give Content an accessible name with one visible Title or an explicit native aria-label or aria-labelledby; add Description or native aria-describedby only when descriptive text is present.
+- **MUST:** Keep the default non-modal behavior for ordinary attached work; set modal only when the compact panel must trap focus, isolate the background, and lock document scrolling.
+- **MUST:** Provide a visible Close when modal is enabled or when outside interaction, Escape, and trigger toggling do not make the dismissal path obvious.
+- **MUST:** Use the owned initial and final focus targets and onInteractOutside preventDefault contract when customization is required; do not replace Atom's focus-out, Escape, completed-interaction, restoration, and nested-layer handling.
+- **MUST:** Use the comfortable default for ordinary contextual work and density=compact for concise filter and utility panels; do not recreate compact rhythm with private selectors.
+- **MUST:** When Content leaves a local Appearance scope through Portal, reproduce that scope on the portalled visual root or target a container inside it.
+- **MUST:** Style from resolved data-side and available-size variables, keep Arrow as a direct Content child, and preserve its shared border and surface paint instead of assuming requested placement or independently recoloring it.
+- **SHOULD:** Keep the panel compact and verify collision shifts and flips, constrained scrolling, action reachability, zoom, touch input, narrow viewports, and LTR and RTL placement.
+- **MUST:** Load styles.css or core.css plus popover.css.
+
+## Common mistakes
+
+- **Avoid:** Hand-positioning a floating div, using Popover for a menu or tooltip, forcing it modal for every utility panel, or closing it with ad hoc document listeners. **Instead:** Choose by interaction job, use complete Popover anatomy, keep ordinary popovers non-modal, and use the preventable outside-interaction contract.
+- **Avoid:** Assuming portalled Content inherits a nearby Appearance scope or placing Arrow inside an authored viewport wrapper. **Instead:** Make the portal scope explicit and keep Arrow directly under Content so placement and finished surface paint remain intact.
+
+## Validation checklist
+
+- Verify trigger and Content naming, controlled and disabled state, keyboard, pointer, and touch opening, initial focus, Tab behavior, Close, Escape, outside interaction, focus-out dismissal, outside focus destination, and trigger restoration.
+- Verify explicit Anchor positioning, collision shifts and flips at every supported side, LTR and RTL, available-size variables, direct Arrow geometry, constrained scrolling, nested portalled controlled layers, zoom, and narrow viewports.
+- When modal is enabled, verify a visible close path, focus containment, background isolation, scroll lock, and exit presence; check light and dark Appearance on actual portalled Content and required CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/popover`
+- `dialog`
+- `drawer`
+- `dropdown-menu`
+- `select`
+- `combobox`
+- `hover-card`
+- `tooltip`
+- `appearance`

package/dist/agents/progress-circle.json

@@ -0,0 +1,85 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "progress-circle",
+  "name": "ProgressCircle",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present compact circular read-only task progress with Brick-owned SVG ring geometry while Atom Progress owns progressbar semantics, normalized range state, and determinate or indeterminate behavior.",
+  "useWhen": [
+    "Ongoing measurable or indeterminate work needs compact circular feedback in a card, toolbar, dialog, or other bounded region."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Linear space communicates change more clearly, the value is a stable measurement or user input, stages matter, or the finished layout is loading.",
+      "useInstead": "Progress, the native meter element, Slider, Steps, or Skeleton"
+    }
+  ],
+  "composition": [
+    "Give ProgressCircle.Root a concise Label or native accessible name, pass a measurable value or null/omit it for indeterminate work, then compose one Circle with Brick-owned Track before Indicator. Add optional Value and Label outside Circle.",
+    "Choose size, thickness, cap, and tone on Root. Keep SVG geometry decorative, preserve clockwise motion independent of RTL, and keep application aria-busy state and announcements outside ProgressCircle."
+  ],
+  "rules": [
+    {
+      "id": "progress-circle-name",
+      "level": "must",
+      "statement": "Give Root an accessible task name through Label or native ARIA; Circle, Track, Indicator, and visible Value are decorative or silent and do not replace that name."
+    },
+    {
+      "id": "progress-circle-state",
+      "level": "must",
+      "statement": "Use a numeric value only for measurable work, pass null or omit it for indeterminate work, and preserve Atom's truthful min/max normalization, clamping, state, and aria-valuenow behavior."
+    },
+    {
+      "id": "progress-circle-brick-anatomy",
+      "level": "must",
+      "statement": "Treat Circle, Track, and Indicator as Brick-owned fixed SVG presentation over Atom Progress context; keep one Circle, order Track before Indicator, and do not override viewBox, radius, circumference, dash array, or dash offset."
+    },
+    {
+      "id": "progress-circle-semantic-owner",
+      "level": "must",
+      "statement": "Keep Root as the only progressbar and announcement path, keep SVG anatomy aria-hidden and unfocusable, and do not make circular progress keyboard adjustable or use it for static measurement."
+    },
+    {
+      "id": "progress-circle-value",
+      "level": "should",
+      "statement": "Localize optional visible Value and provide aria-valuetext when the numeric range needs domain wording; do not assume the decorative Value changes Root's accessible value text."
+    },
+    {
+      "id": "progress-circle-responsive",
+      "level": "must",
+      "statement": "Keep the ring square, contained within its surrounding region, clockwise in LTR and RTL, label wrapping intact, track visible, and reduced-motion indeterminate state understandable as a static arc."
+    },
+    {
+      "id": "progress-circle-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus progress-circle.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using an unlabeled decorative spinner, adding progressbar semantics to SVG, passing zero for unknown work, or reversing the ring in RTL.",
+      "correction": "Name Atom-backed Root, use indeterminate null state, keep Brick SVG silent, and retain clockwise geometry."
+    },
+    {
+      "mistake": "Overriding component-owned SVG radius or dash geometry or using ProgressCircle for capacity or input.",
+      "correction": "Use public size/thickness/cap/tone recipes and choose native meter or Slider for other semantic jobs."
+    }
+  ],
+  "validation": [
+    "Verify Root naming, determinate loading/complete and indeterminate state, aria-valuenow presence/absence, clamping, invalid-range normalization, custom value text, localized visible Value, and Atom state propagation.",
+    "Verify one Root progressbar, one decorative Circle, Track before Indicator, fixed component-owned geometry, silent/unfocusable SVG, no keyboard interaction, native props, refs, and supported composition.",
+    "Verify five sizes, three thicknesses, both caps, all tones, square containment, long labels, zoom, clockwise LTR/RTL behavior, track contrast, light/dark appearance, forced colors, and reduced motion."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "progress",
+      "versionPolicy": "installed-exact"
+    },
+    "progress",
+    "slider",
+    "skeleton"
+  ]
+}