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

package/public/packages/atom/0.24.0/components/number-input.txt

@@ -0,0 +1,124 @@
+# NumberInput
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: number-input
+
+# NumberInput agent guide
+
+## Purpose
+
+Edit an exact numeric value through text and spinbutton stepping with parsing, formatting, limits, Field validation, and optional native form submission.
+
+## Use when
+
+- A value is truly numeric and users should type an exact value or increment and decrement it.
+
+## Choose something else when
+
+- The text merely contains digits, spatial adjustment by feel is primary, or the value is read-only progress. Use Input, Slider, or Progress.
+
+## Required composition
+
+- Use Root alone for its automatic Input, use the render callback for the legacy custom-control path, or provide static compound children containing exactly one Input with optional Increment and Decrement buttons. Give the spinbutton an accessible name and localize step-button action labels when necessary.
+
+## Rules
+
+- **MUST:** Use NumberInput only for values that can be meaningfully stepped and clamped; postal codes, phone numbers, account numbers, and similar identifiers remain text Input values.
+- **MUST:** Use number or null controlled state with onValueChange, preserve intermediate display text while editing, and treat null as an intentional empty numeric value.
+- **MUST:** Keep parser and formatter reversible for valid values, choose positive step and appropriate precision, and decide whether clampOnBlur should normalize out-of-range input.
+- **MUST:** Preserve Input's spinbutton name, numeric ARIA, Arrow/Page/Home/End keys, disabled/read-only/required/invalid state, and native validity.
+- **MUST:** Use Increment and Decrement only inside Root, preserve input focus on pointer activation, aria-controls, boundary disabled state, and localized accessible action names.
+- **MUST:** Keep the visible Input as validity owner and the named hidden parsed value as submission-only, including external form association, Field reporting, and uncontrolled reset.
+
+## Common mistakes
+
+- **Avoid:** Using NumberInput for digit-like identifiers, rendering an automatic and compound Input together, formatting without a matching parser, or submitting the formatted display string as the numeric value. **Instead:** Choose text semantics for identifiers, use one composition path, keep parsing and formatting symmetric, and preserve the hidden parsed submission value.
+
+## Validation checklist
+
+- Verify controlled number and null state, uncontrolled default, intermediate typing, parsing, formatting, inferred and explicit precision, min/max, clampOnBlur, step and largeStep, Arrow/Page/Home/End, empty state, disabled/read-only behavior, and boundary step buttons with pointer/touch focus preservation.
+- Verify automatic, static one-Input, and render-callback paths; accessible name and value text; required and numeric native validity; inline/native Field reporting; hidden parsed name/form submission; external form; reset; native props; refs; asChild; and render composition.
+
+## Related guidance
+
+- `input`
+- `slider`
+- `progress`
+- `field`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "number-input",
+  "name": "NumberInput",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Edit an exact numeric value through text and spinbutton stepping with parsing, formatting, limits, Field validation, and optional native form submission.",
+  "useWhen": [
+    "A value is truly numeric and users should type an exact value or increment and decrement it."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The text merely contains digits, spatial adjustment by feel is primary, or the value is read-only progress.",
+      "useInstead": "Input, Slider, or Progress"
+    }
+  ],
+  "composition": [
+    "Use Root alone for its automatic Input, use the render callback for the legacy custom-control path, or provide static compound children containing exactly one Input with optional Increment and Decrement buttons. Give the spinbutton an accessible name and localize step-button action labels when necessary."
+  ],
+  "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 text Input values."
+    },
+    {
+      "id": "number-input-controlled-empty",
+      "level": "must",
+      "statement": "Use number or null controlled state with onValueChange, preserve intermediate display text while editing, and treat null as an intentional empty numeric value."
+    },
+    {
+      "id": "number-input-parse-format",
+      "level": "must",
+      "statement": "Keep parser and formatter reversible for valid values, choose positive step and appropriate precision, and decide whether clampOnBlur should normalize out-of-range input."
+    },
+    {
+      "id": "number-input-spinbutton",
+      "level": "must",
+      "statement": "Preserve Input's spinbutton name, numeric ARIA, Arrow/Page/Home/End keys, disabled/read-only/required/invalid state, and native validity."
+    },
+    {
+      "id": "number-input-step-buttons",
+      "level": "must",
+      "statement": "Use Increment and Decrement only inside Root, preserve input focus on pointer activation, aria-controls, boundary disabled state, and localized accessible action names."
+    },
+    {
+      "id": "number-input-form",
+      "level": "must",
+      "statement": "Keep the visible Input as validity owner and the named hidden parsed value as submission-only, including external form association, Field reporting, and uncontrolled reset."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using NumberInput for digit-like identifiers, rendering an automatic and compound Input together, formatting without a matching parser, or submitting the formatted display string as the numeric value.",
+      "correction": "Choose text semantics for identifiers, use one composition path, keep parsing and formatting symmetric, and preserve the hidden parsed submission value."
+    }
+  ],
+  "validation": [
+    "Verify controlled number and null state, uncontrolled default, intermediate typing, parsing, formatting, inferred and explicit precision, min/max, clampOnBlur, step and largeStep, Arrow/Page/Home/End, empty state, disabled/read-only behavior, and boundary step buttons with pointer/touch focus preservation.",
+    "Verify automatic, static one-Input, and render-callback paths; accessible name and value text; required and numeric native validity; inline/native Field reporting; hidden parsed name/form submission; external form; reset; native props; refs; asChild; and render composition."
+  ],
+  "related": [
+    "input",
+    "slider",
+    "progress",
+    "field",
+    "form"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/otp-field.txt

@@ -0,0 +1,122 @@
+# OTPField
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: otp-field
+
+# OTPField agent guide
+
+## Purpose
+
+Coordinate a short one-time verification code across visible character cells as one logical field with filtering, paste distribution, roving focus, completion, validation, and combined form submission.
+
+## Use when
+
+- A short one-time code from a message is entered or pasted into visually separated character cells.
+
+## Choose something else when
+
+- The user chooses a reusable secret or the value belongs in one ordinary text box. Use PasswordToggleField or Input.
+
+## Required composition
+
+- Give Root a clear accessible group name and render one Input for each normalized length position, normally relying on render order for indices. Add Separator only for decorative grouping, and localize generated cell labels with getInputLabel.
+
+## Rules
+
+- **MUST:** Match the visible Input count and stable order to Root length; use explicit index only when composition genuinely requires an override.
+- **MUST:** Choose numeric, alphabetic, alphanumeric, or a safe custom pattern that accepts exactly the intended characters, and preserve filtering for typing and paste.
+- **MUST:** Name Root through native ARIA or Field, localize every generated position label, keep Separator aria-hidden, and do not add unsupported aria-required to role=group.
+- **MUST:** Preserve one roving Tab stop, render-order registration, character advance, Arrow/Home/End, Backspace/Delete, paste distribution, disabled/read-only state, and focus movement.
+- **MUST:** Treat onComplete and especially autoSubmit as product effects: enable autoSubmit only when a complete accepted code should intentionally submit the associated form.
+- **MUST:** Keep required validity on the first visible cell and the named combined hidden value submission-only, including Field invalid mirroring, external form association, and uncontrolled reset.
+
+## Common mistakes
+
+- **Avoid:** Using OTPField for a password, rendering a different number of cells than length, leaving English generated cell labels in a localized product, or auto-submitting without explicit workflow intent. **Instead:** Use the correct secret/text input, align cells to length, localize getInputLabel, and treat completion submission as an explicit application decision.
+
+## Validation checklist
+
+- Verify controlled/uncontrolled full value, length, render-order and explicit indices, numeric/alphabetic/alphanumeric/custom filtering, typing replacement, accepted paste distribution, Backspace/Delete, Arrow/Home/End, one roving Tab stop, 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 and external form, reset, separators, asChild/render, and refs.
+
+## Related guidance
+
+- `password-toggle-field`
+- `input`
+- `field`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "otp-field",
+  "name": "OTPField",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Coordinate a short one-time verification code across visible character cells as one logical field with filtering, paste distribution, roving focus, completion, validation, and combined form submission.",
+  "useWhen": [
+    "A short one-time code from a message is entered or pasted into visually separated character cells."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The user chooses a reusable secret or the value belongs in one ordinary text box.",
+      "useInstead": "PasswordToggleField or Input"
+    }
+  ],
+  "composition": [
+    "Give Root a clear accessible group name and render one Input for each normalized length position, normally relying on render order for indices. Add Separator only for decorative grouping, and localize generated cell labels with getInputLabel."
+  ],
+  "rules": [
+    {
+      "id": "otp-cell-count",
+      "level": "must",
+      "statement": "Match the visible Input count and stable order to Root length; use explicit index only when composition genuinely requires an override."
+    },
+    {
+      "id": "otp-filter",
+      "level": "must",
+      "statement": "Choose numeric, alphabetic, alphanumeric, or a safe custom pattern that accepts exactly the intended characters, and preserve filtering for typing and paste."
+    },
+    {
+      "id": "otp-labels",
+      "level": "must",
+      "statement": "Name Root through native ARIA or Field, localize every generated position label, keep Separator aria-hidden, and do not add unsupported aria-required to role=group."
+    },
+    {
+      "id": "otp-focus-input",
+      "level": "must",
+      "statement": "Preserve one roving Tab stop, render-order registration, character advance, Arrow/Home/End, Backspace/Delete, paste distribution, disabled/read-only state, and focus movement."
+    },
+    {
+      "id": "otp-completion",
+      "level": "must",
+      "statement": "Treat onComplete and especially autoSubmit as product effects: enable autoSubmit only when a complete accepted code should intentionally submit the associated form."
+    },
+    {
+      "id": "otp-form",
+      "level": "must",
+      "statement": "Keep required validity on the first visible cell and the named combined hidden value submission-only, including Field invalid mirroring, external form association, and uncontrolled reset."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using OTPField for a password, rendering a different number of cells than length, leaving English generated cell labels in a localized product, or auto-submitting without explicit workflow intent.",
+      "correction": "Use the correct secret/text input, align cells to length, localize getInputLabel, and treat completion submission as an explicit application decision."
+    }
+  ],
+  "validation": [
+    "Verify controlled/uncontrolled full value, length, render-order and explicit indices, numeric/alphabetic/alphanumeric/custom filtering, typing replacement, accepted paste distribution, Backspace/Delete, Arrow/Home/End, one roving Tab stop, 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 and external form, reset, separators, asChild/render, and refs."
+  ],
+  "related": [
+    "password-toggle-field",
+    "input",
+    "field",
+    "form"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/pagination.txt

@@ -0,0 +1,111 @@
+# Pagination
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: pagination
+
+# Pagination agent guide
+
+## Purpose
+
+Represent movement through ordered result pages with named navigation, current-page state, and link or controlled activation semantics.
+
+## Use when
+
+- A collection or result set is divided into ordered pages.
+
+## Choose something else when
+
+- The relationship is page ancestry, local panels, or sequential article navigation. Use Breadcrumb, Tabs, or ordinary links.
+
+## Required composition
+
+- Compose Root and List with Page items plus Previous, Next, and Ellipsis as needed.
+- For URL-backed results, provide Root getPageHref so Item, Previous, and Next render native anchors; derive controlled Root page from the current route.
+
+## Rules
+
+- **MUST:** Expose exactly one current page and keep page labels meaningful to assistive technology.
+- **MUST:** Use Root getPageHref when pages have URLs so native navigation, sharing, reload, and modified-click behavior continue to work.
+- **MUST:** In link mode, let the browser or router own navigation; do not depend on onPageChange or replace native anchor behavior with button activation.
+
+## Common mistakes
+
+- **Avoid:** Rendering URL-backed pages as buttons or composing an anchor while Root remains in button mode. **Instead:** Provide Root getPageHref; optionally enhance its generated anchors through onClick without breaking modified clicks.
+- **Avoid:** Rendering disabled previous or next controls as active links, or using pagination for ancestry. **Instead:** Boundary controls must expose disabled semantics without an href; use Breadcrumb for hierarchy.
+
+## Validation checklist
+
+- Confirm current, first, last, previous, next, disabled, and ellipsis states.
+- Confirm each control has a unique accessible name and URL-backed pages expose real destinations.
+- In link mode, verify reload, copy/share URL, Back/Forward, Cmd/Ctrl-click, and disabled boundary controls without href.
+
+## Related guidance
+
+- `breadcrumb`
+- `link`
+- `button`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "pagination",
+  "name": "Pagination",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Represent movement through ordered result pages with named navigation, current-page state, and link or controlled activation semantics.",
+  "useWhen": [
+    "A collection or result set is divided into ordered pages."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The relationship is page ancestry, local panels, or sequential article navigation.",
+      "useInstead": "Breadcrumb, Tabs, or ordinary links"
+    }
+  ],
+  "composition": [
+    "Compose Root and List with Page items plus Previous, Next, and Ellipsis as needed.",
+    "For URL-backed results, provide Root getPageHref so Item, Previous, and Next render native anchors; derive controlled Root page from the current route."
+  ],
+  "rules": [
+    {
+      "id": "pagination-current",
+      "level": "must",
+      "statement": "Expose exactly one current page and keep page labels meaningful to assistive technology."
+    },
+    {
+      "id": "pagination-link-semantics",
+      "level": "must",
+      "statement": "Use Root getPageHref when pages have URLs so native navigation, sharing, reload, and modified-click behavior continue to work."
+    },
+    {
+      "id": "pagination-link-ownership",
+      "level": "must",
+      "statement": "In link mode, let the browser or router own navigation; do not depend on onPageChange or replace native anchor behavior with button activation."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Rendering URL-backed pages as buttons or composing an anchor while Root remains in button mode.",
+      "correction": "Provide Root getPageHref; optionally enhance its generated anchors through onClick without breaking modified clicks."
+    },
+    {
+      "mistake": "Rendering disabled previous or next controls as active links, or using pagination for ancestry.",
+      "correction": "Boundary controls must expose disabled semantics without an href; use Breadcrumb for hierarchy."
+    }
+  ],
+  "validation": [
+    "Confirm current, first, last, previous, next, disabled, and ellipsis states.",
+    "Confirm each control has a unique accessible name and URL-backed pages expose real destinations.",
+    "In link mode, verify reload, copy/share URL, Back/Forward, Cmd/Ctrl-click, and disabled boundary controls without href."
+  ],
+  "related": [
+    "breadcrumb",
+    "link",
+    "button"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/password-toggle-field.txt

@@ -0,0 +1,116 @@
+# PasswordToggleField
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: password-toggle-field
+
+# PasswordToggleField agent guide
+
+## Purpose
+
+Provide a native password input with controlled or uncontrolled reveal state, an accessible show/hide action, Field validation, and form-safe password restoration.
+
+## Use when
+
+- A reusable password input benefits from an explicit keyboard-accessible action that lets users verify what they typed and revealing it is acceptable for the product's privacy model.
+
+## Choose something else when
+
+- The value is ordinary text, a one-time verification code, or policy forbids revealing the secret. Use Input, OTPField, or a password Input without a reveal control.
+
+## Required composition
+
+- Compose Root with one Input and a Toggle; add Icon only when the styled layer needs decorative visible/hidden content. Give Input an accessible Field or native label and localize Root showLabel and hideLabel for the Toggle action.
+
+## Rules
+
+- **MUST:** Include the visibility action only when revealing the password is acceptable for the product's security, privacy, observation, 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:** Give Toggle localized state-aware Show and Hide action labels; do not add aria-pressed because the changing action label communicates the available action.
+- **MUST:** Preserve Input focus on Toggle pointer down while keeping Toggle keyboard reachable by Tab, Enter, and Space.
+- **MUST:** Route controlled visible through onVisibleChange or use defaultVisible, preserve disabled/read-only/required/invalid Field behavior, restore uncontrolled visibility on reset, and restore type=password before native submission.
+
+## Common mistakes
+
+- **Avoid:** Adding reveal where policy forbids it, using aria-pressed with changing Show/Hide labels, moving pointer focus away from Input, or allowing form submission 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.
+
+## Validation checklist
+
+- Verify Input label, autocomplete and native props, controlled/uncontrolled visibility, password/text switching, localized Show/Hide Toggle labels, decorative Icon state, pointer focus preservation, keyboard Tab/Enter/Space, disabled and read-only behavior, and asChild/render Toggle composition.
+- Verify Field ID, label, description and error inheritance with native overrides, required/invalid inline and native validation, reset to defaultVisible, type=password restoration before form submission, external form association, and no unintended live-region or aria-pressed semantics.
+
+## Related guidance
+
+- `input`
+- `otp-field`
+- `field`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "password-toggle-field",
+  "name": "PasswordToggleField",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide a native password input with controlled or uncontrolled reveal state, an accessible show/hide action, Field validation, and form-safe password restoration.",
+  "useWhen": [
+    "A reusable password input benefits from an explicit keyboard-accessible action that lets users verify what they typed and revealing it is acceptable for the product's privacy model."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value is ordinary text, a one-time verification code, or policy forbids revealing the secret.",
+      "useInstead": "Input, OTPField, or a password Input without a reveal control"
+    }
+  ],
+  "composition": [
+    "Compose Root with one Input and a Toggle; add Icon only when the styled layer needs decorative visible/hidden content. Give Input an accessible Field or native label and localize Root showLabel and hideLabel for the Toggle action."
+  ],
+  "rules": [
+    {
+      "id": "password-reveal-policy",
+      "level": "must",
+      "statement": "Include the visibility action only when revealing the password is acceptable for the product's security, privacy, observation, and shared-device context."
+    },
+    {
+      "id": "password-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-label",
+      "level": "must",
+      "statement": "Give Toggle localized state-aware Show and Hide action labels; do not add aria-pressed because the changing action label communicates the available action."
+    },
+    {
+      "id": "password-focus",
+      "level": "must",
+      "statement": "Preserve Input focus on Toggle pointer down while keeping Toggle keyboard reachable by Tab, Enter, and Space."
+    },
+    {
+      "id": "password-state-form",
+      "level": "must",
+      "statement": "Route controlled visible through onVisibleChange or use defaultVisible, preserve disabled/read-only/required/invalid Field behavior, restore uncontrolled visibility on reset, and restore type=password before native submission."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Adding reveal where policy forbids it, using aria-pressed with changing Show/Hide labels, moving pointer focus away from Input, or allowing form submission 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."
+    }
+  ],
+  "validation": [
+    "Verify Input label, autocomplete and native props, controlled/uncontrolled visibility, password/text switching, localized Show/Hide Toggle labels, decorative Icon state, pointer focus preservation, keyboard Tab/Enter/Space, disabled and read-only behavior, and asChild/render Toggle composition.",
+    "Verify Field ID, label, description and error inheritance with native overrides, required/invalid inline and native validation, reset to defaultVisible, type=password restoration before form submission, external form association, and no unintended live-region or aria-pressed semantics."
+  ],
+  "related": [
+    "input",
+    "otp-field",
+    "field",
+    "form"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/popover.txt

@@ -0,0 +1,122 @@
+# Popover
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: popover
+
+# Popover agent guide
+
+## Purpose
+
+Present a small interactive panel anchored to a trigger or explicit anchor with positioning, dismissal, focus, portal, and optional modal behavior.
+
+## Use when
+
+- A compact set of interactive controls or supporting content belongs near its trigger and needs collision-aware positioning and managed dismissal.
+
+## Choose something else when
+
+- The content is non-interactive help, a passive preview, or a larger blocking task. Use Tooltip, HoverCard, or Dialog.
+
+## Required composition
+
+- Compose Root around Content; add Trigger for local activation or omit it for controlled and triggerless workflows, add Anchor only when positioning must use another reference, and use Portal only when Content must leave its DOM location. Inside Content, use Title or native labeling for the accessible name, add Description and Close only when needed, and add Arrow only when the styled layer needs a pointer; when present, Arrow must be a direct Content child.
+
+## Rules
+
+- **MUST:** Give Content an accessible name with one Title or native aria-label or aria-labelledby; use Description or native aria-describedby only when descriptive text is present.
+- **MUST:** Keep the default non-modal behavior for compact attached work; set modal only when the panel must trap focus, isolate the background, and lock document scrolling.
+- **MUST:** Use onInteractOutside and preventDefault to veto dismissal; do not replace Atom's completed-interaction, focus-out, Escape, and nested controlled-layer handling.
+- **MUST:** Preserve hover opening without focus movement, touch-safe Content focus, keyboard and pointer initial focus, outside-destination focus, and final-focus restoration unless explicit targets are required.
+- **SHOULD:** Use Anchor only when positioning must reference a different element than Trigger, and style from resolved data-side and available-size variables rather than assuming the requested placement always wins.
+- **MUST:** Keep Arrow as a direct Content child so it remains outside the generated viewport wrapper and can align with the resolved floating placement.
+
+## Common mistakes
+
+- **Avoid:** Using Popover for tooltip-like text, forcing it modal for every menu-sized panel, closing it with ad hoc document listeners, or placing Arrow inside an authored viewport wrapper. **Instead:** Choose by interaction job, keep ordinary popovers non-modal, use the preventable outside-interaction contract, and place Arrow directly under Content.
+
+## Validation checklist
+
+- Verify click and hover trigger modes, delays, controlled state, disabled state, accessible relationships, keyboard, pointer, touch, and hover focus behavior, Escape, outside interaction, focus-out dismissal, Close, and focus destination or restoration.
+- Verify explicit Anchor and Trigger positioning, collision shifts and flips, LTR and RTL, available-size variables, direct Arrow geometry, nested portalled controlled layers, modal focus and isolation, and exit presence.
+
+## Related guidance
+
+- `tooltip`
+- `hover-card`
+- `dialog`
+- `direction`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "popover",
+  "name": "Popover",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Present a small interactive panel anchored to a trigger or explicit anchor with positioning, dismissal, focus, portal, and optional modal behavior.",
+  "useWhen": [
+    "A compact set of interactive controls or supporting content belongs near its trigger and needs collision-aware positioning and managed dismissal."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content is non-interactive help, a passive preview, or a larger blocking task.",
+      "useInstead": "Tooltip, HoverCard, or Dialog"
+    }
+  ],
+  "composition": [
+    "Compose Root around Content; add Trigger for local activation or omit it for controlled and triggerless workflows, add Anchor only when positioning must use another reference, and use Portal only when Content must leave its DOM location. Inside Content, use Title or native labeling for the accessible name, add Description and Close only when needed, and add Arrow only when the styled layer needs a pointer; when present, Arrow must be a direct Content child."
+  ],
+  "rules": [
+    {
+      "id": "popover-accessible-name",
+      "level": "must",
+      "statement": "Give Content an accessible name with one Title or native aria-label or aria-labelledby; use 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 compact attached work; set modal only when the panel must trap focus, isolate the background, and lock document scrolling."
+    },
+    {
+      "id": "popover-outside-interaction",
+      "level": "must",
+      "statement": "Use onInteractOutside and preventDefault to veto dismissal; do not replace Atom's completed-interaction, focus-out, Escape, and nested controlled-layer handling."
+    },
+    {
+      "id": "popover-focus-policy",
+      "level": "must",
+      "statement": "Preserve hover opening without focus movement, touch-safe Content focus, keyboard and pointer initial focus, outside-destination focus, and final-focus restoration unless explicit targets are required."
+    },
+    {
+      "id": "popover-anchor-positioning",
+      "level": "should",
+      "statement": "Use Anchor only when positioning must reference a different element than Trigger, and style from resolved data-side and available-size variables rather than assuming the requested placement always wins."
+    },
+    {
+      "id": "popover-arrow-anatomy",
+      "level": "must",
+      "statement": "Keep Arrow as a direct Content child so it remains outside the generated viewport wrapper and can align with the resolved floating placement."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Popover for tooltip-like text, forcing it modal for every menu-sized panel, closing it with ad hoc document listeners, or placing Arrow inside an authored viewport wrapper.",
+      "correction": "Choose by interaction job, keep ordinary popovers non-modal, use the preventable outside-interaction contract, and place Arrow directly under Content."
+    }
+  ],
+  "validation": [
+    "Verify click and hover trigger modes, delays, controlled state, disabled state, accessible relationships, keyboard, pointer, touch, and hover focus behavior, Escape, outside interaction, focus-out dismissal, Close, and focus destination or restoration.",
+    "Verify explicit Anchor and Trigger positioning, collision shifts and flips, LTR and RTL, available-size variables, direct Arrow geometry, nested portalled controlled layers, modal focus and isolation, and exit presence."
+  ],
+  "related": [
+    "tooltip",
+    "hover-card",
+    "dialog",
+    "direction"
+  ]
+}
+```