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

package/public/packages/atom/0.24.0/components/context-menu.txt

@@ -0,0 +1,114 @@
+# ContextMenu
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: context-menu
+
+# ContextMenu agent guide
+
+## Purpose
+
+Open the shared Menu command model at the invocation point of a secondary-click, keyboard context-menu action, or cancel-safe touch and pen long press.
+
+## Use when
+
+- Commands belong to the exact file, row, canvas object, or region a user invokes contextually and every important command also has a discoverable route.
+
+## Choose something else when
+
+- The actions need a visible button, are the only route to an important task, or belong to a persistent application command bar. Use DropdownMenu, visible controls, or Menubar.
+
+## Required composition
+
+- Compose Root with Trigger wrapping the owned target region and Content. Add Portal and Arrow only when needed; compose Content from the shared Menu Item, selection, grouping, separator, and paired submenu parts.
+
+## Rules
+
+- **MUST:** Provide another visible or keyboard-discoverable route to every important action; ContextMenu must remain an enhancement rather than the only access path.
+- **MUST:** Keep Trigger as a behavior wrapper without invented button semantics and preserve the wrapped target's native semantics and actions through asChild or render composition.
+- **MUST:** Preserve secondary-click coordinates, keyboard anchor behavior, cross-trigger handoff, and the cancel-safe 700 ms touch and pen long press with its movement, scroll, multi-pointer, and native-event cancellation.
+- **MUST:** Give Content an explicit ariaLabel when the non-semantic Trigger cannot provide an appropriate menu label.
+- **MUST:** Preserve the shared Menu item roles, real focus, typeahead, disabled navigation, selection close policy, submenus, modal ownership, outside dismissal, and focus restoration.
+
+## Common mistakes
+
+- **Avoid:** Making right-click the only route to an action, adding button semantics to the target wrapper, or implementing a second long-press and point-positioning system. **Instead:** Keep visible alternatives, preserve target semantics, and use ContextMenu's owned invocation and Menu contracts.
+
+## Validation checklist
+
+- Verify secondary click at changing coordinates, keyboard invocation, preventDefault consumer handling, transfer between registered targets, disabled state, and touch and pen long press cancellation for movement, scroll, release, cancellation, second pointer, native contextmenu, and unmount.
+- Verify Content naming, item focus and typeahead, selection roles and close policies, submenu behavior, Tab and Escape, outside dismissal, modal isolation, parent-modal portals, LTR and RTL, and focus return.
+
+## Related guidance
+
+- `menu`
+- `dropdown-menu`
+- `menubar`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "context-menu",
+  "name": "ContextMenu",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Open the shared Menu command model at the invocation point of a secondary-click, keyboard context-menu action, or cancel-safe touch and pen long press.",
+  "useWhen": [
+    "Commands belong to the exact file, row, canvas object, or region a user invokes contextually and every important command also has a discoverable route."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The actions need a visible button, are the only route to an important task, or belong to a persistent application command bar.",
+      "useInstead": "DropdownMenu, visible controls, or Menubar"
+    }
+  ],
+  "composition": [
+    "Compose Root with Trigger wrapping the owned target region and Content. Add Portal and Arrow only when needed; compose Content from the shared Menu Item, selection, grouping, separator, and paired submenu parts."
+  ],
+  "rules": [
+    {
+      "id": "context-menu-discoverability",
+      "level": "must",
+      "statement": "Provide another visible or keyboard-discoverable route to every important action; ContextMenu must remain an enhancement rather than the only access path."
+    },
+    {
+      "id": "context-menu-trigger-semantics",
+      "level": "must",
+      "statement": "Keep Trigger as a behavior wrapper without invented button semantics and preserve the wrapped target's native semantics and actions through asChild or render composition."
+    },
+    {
+      "id": "context-menu-input",
+      "level": "must",
+      "statement": "Preserve secondary-click coordinates, keyboard anchor behavior, cross-trigger handoff, and the cancel-safe 700 ms touch and pen long press with its movement, scroll, multi-pointer, and native-event cancellation."
+    },
+    {
+      "id": "context-menu-label",
+      "level": "must",
+      "statement": "Give Content an explicit ariaLabel when the non-semantic Trigger cannot provide an appropriate menu label."
+    },
+    {
+      "id": "context-menu-shared-contract",
+      "level": "must",
+      "statement": "Preserve the shared Menu item roles, real focus, typeahead, disabled navigation, selection close policy, submenus, modal ownership, outside dismissal, and focus restoration."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Making right-click the only route to an action, adding button semantics to the target wrapper, or implementing a second long-press and point-positioning system.",
+      "correction": "Keep visible alternatives, preserve target semantics, and use ContextMenu's owned invocation and Menu contracts."
+    }
+  ],
+  "validation": [
+    "Verify secondary click at changing coordinates, keyboard invocation, preventDefault consumer handling, transfer between registered targets, disabled state, and touch and pen long press cancellation for movement, scroll, release, cancellation, second pointer, native contextmenu, and unmount.",
+    "Verify Content naming, item focus and typeahead, selection roles and close policies, submenu behavior, Tab and Escape, outside dismissal, modal isolation, parent-modal portals, LTR and RTL, and focus return."
+  ],
+  "related": [
+    "menu",
+    "dropdown-menu",
+    "menubar"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/data-grid.txt

@@ -0,0 +1,136 @@
+# DataGrid
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: data-grid
+
+# DataGrid agent guide
+
+## Purpose
+
+Provide a flat ARIA grid with one Root focus target, active-descendant cell navigation, optional row selection, indexed semantics, and actionable column-header boundaries.
+
+## Use when
+
+- A flat row-and-column dataset needs two-dimensional keyboard cell navigation, optional row selection, or interactive grid headers.
+
+## Choose something else when
+
+- People only read and compare tabular values without composite cell navigation or row selection. Use Table.
+- Rows expand into a parent-child hierarchy, or the application expects Atom to own sorting, editing, filtering, resizing, or virtualization. Use TreeGrid or an application composition around DataGrid and the relevant utility.
+
+## Required composition
+
+- Give Root an accessible name and accurate total counts, then compose Caption when useful, Header and Body rowgroups, uniquely valued and accurately indexed Rows, indexed ColumnHeader and Cell parts, and Footer only for summaries. Configure selection and controlled active-cell state deliberately.
+
+## Rules
+
+- **MUST:** Give Root an accessible name and provide stable one-based row and column indexes plus accurate rowCount and columnCount, including the logical full collection when rows are paged or virtualized.
+- **MUST:** Keep DOM focus on Root and preserve aria-activedescendant, Arrow movement, Home and End, whole-grid movement, disabled-cell skipping, RTL mirroring, loop, and wrapRows policy.
+- **MUST:** Align scalar, array, or null state with selectionMode; give selectable rows stable unique values; and use selectable=false for header or summary rows that remain navigable but cannot be selected.
+- **MUST:** Preserve controlled or uncontrolled active-cell and selection state, disabled behavior, and read-only navigation without selection mutation.
+- **MUST:** Use ColumnHeader onAction for equivalent pointer and active-header Enter activation, keep sortDirection truthful, and leave sorting and data reordering to the application.
+- **MUST:** When windowing, preserve logical indexes and totals and keep the active descendant mounted or move active state before its cell leaves the DOM; Virtualizer supplies geometry, not grid semantics or focus management.
+
+## Common mistakes
+
+- **Avoid:** Using DataGrid for a read-only table or adding independent Tab stops to every cell. **Instead:** Use Table for read-only comparison and keep DataGrid Root as the composite focus owner.
+- **Avoid:** Using visible array indexes as unstable identity, omitting logical counts during virtualization, or expecting sortDirection to sort rows. **Instead:** Keep durable row values, logical one-based coordinates and totals, and application-owned sorting synchronized with header metadata.
+
+## Validation checklist
+
+- Verify grid, rowgroup, row, columnheader, and gridcell relationships; Root naming; one-based logical indexes and totals; and active-descendant IDs against the final DOM.
+- Exercise LTR and RTL Arrow navigation, vertical column preservation, Home and End, whole-grid movement, loop and wrapRows boundaries, disabled cells, pointer activation, and consumer cancellation.
+- Verify none, single, and multiple controlled and uncontrolled selection; nonselectable rows; disabled and read-only state; actionable header pointer and Enter parity; and truthful sort metadata.
+- For paged or virtualized data, verify offscreen totals and positions remain accurate and focus never references an unmounted cell.
+
+## Related guidance
+
+- `table`
+- `tree-grid`
+- `collection`
+- `virtualizer`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "data-grid",
+  "name": "DataGrid",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide a flat ARIA grid with one Root focus target, active-descendant cell navigation, optional row selection, indexed semantics, and actionable column-header boundaries.",
+  "useWhen": [
+    "A flat row-and-column dataset needs two-dimensional keyboard cell navigation, optional row selection, or interactive grid headers."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "People only read and compare tabular values without composite cell navigation or row selection.",
+      "useInstead": "Table"
+    },
+    {
+      "condition": "Rows expand into a parent-child hierarchy, or the application expects Atom to own sorting, editing, filtering, resizing, or virtualization.",
+      "useInstead": "TreeGrid or an application composition around DataGrid and the relevant utility"
+    }
+  ],
+  "composition": [
+    "Give Root an accessible name and accurate total counts, then compose Caption when useful, Header and Body rowgroups, uniquely valued and accurately indexed Rows, indexed ColumnHeader and Cell parts, and Footer only for summaries. Configure selection and controlled active-cell state deliberately."
+  ],
+  "rules": [
+    {
+      "id": "data-grid-name-indexes",
+      "level": "must",
+      "statement": "Give Root an accessible name and provide stable one-based row and column indexes plus accurate rowCount and columnCount, including the logical full collection when rows are paged or virtualized."
+    },
+    {
+      "id": "data-grid-focus",
+      "level": "must",
+      "statement": "Keep DOM focus on Root and preserve aria-activedescendant, Arrow movement, Home and End, whole-grid movement, disabled-cell skipping, RTL mirroring, loop, and wrapRows policy."
+    },
+    {
+      "id": "data-grid-selection",
+      "level": "must",
+      "statement": "Align scalar, array, or null state with selectionMode; give selectable rows stable unique values; and use selectable=false for header or summary rows that remain navigable but cannot be selected."
+    },
+    {
+      "id": "data-grid-state-boundary",
+      "level": "must",
+      "statement": "Preserve controlled or uncontrolled active-cell and selection state, disabled behavior, and read-only navigation without selection mutation."
+    },
+    {
+      "id": "data-grid-header-action",
+      "level": "must",
+      "statement": "Use ColumnHeader onAction for equivalent pointer and active-header Enter activation, keep sortDirection truthful, and leave sorting and data reordering to the application."
+    },
+    {
+      "id": "data-grid-virtualization",
+      "level": "must",
+      "statement": "When windowing, preserve logical indexes and totals and keep the active descendant mounted or move active state before its cell leaves the DOM; Virtualizer supplies geometry, not grid semantics or focus management."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using DataGrid for a read-only table or adding independent Tab stops to every cell.",
+      "correction": "Use Table for read-only comparison and keep DataGrid Root as the composite focus owner."
+    },
+    {
+      "mistake": "Using visible array indexes as unstable identity, omitting logical counts during virtualization, or expecting sortDirection to sort rows.",
+      "correction": "Keep durable row values, logical one-based coordinates and totals, and application-owned sorting synchronized with header metadata."
+    }
+  ],
+  "validation": [
+    "Verify grid, rowgroup, row, columnheader, and gridcell relationships; Root naming; one-based logical indexes and totals; and active-descendant IDs against the final DOM.",
+    "Exercise LTR and RTL Arrow navigation, vertical column preservation, Home and End, whole-grid movement, loop and wrapRows boundaries, disabled cells, pointer activation, and consumer cancellation.",
+    "Verify none, single, and multiple controlled and uncontrolled selection; nonselectable rows; disabled and read-only state; actionable header pointer and Enter parity; and truthful sort metadata.",
+    "For paged or virtualized data, verify offscreen totals and positions remain accurate and focus never references an unmounted cell."
+  ],
+  "related": [
+    "table",
+    "tree-grid",
+    "collection",
+    "virtualizer"
+  ]
+}
+```

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

@@ -0,0 +1,116 @@
+# Dialog
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: dialog
+
+# Dialog agent guide
+
+## Purpose
+
+Present an ordinary blocking task, form, or information surface with modal focus, dismissal, labeling, portal, background-isolation, and scroll-lock behavior.
+
+## Use when
+
+- A user must focus on a temporary blocking task, form, or information surface before returning to the underlying application.
+
+## Choose something else when
+
+- The user must make an urgent consequential choice, the task is a side sheet, or the panel is small, attached, and should usually remain non-modal. Use AlertDialog, Drawer, or Popover.
+
+## Required composition
+
+- Compose Root around Content; add Trigger for local activation or omit it for controlled and triggerless workflows, and use Portal only when the layer must leave its DOM location. When Overlay is rendered, keep it as a sibling of Content. Inside Content, use Title or native labeling for the accessible name, add Description only when useful, and add Close only when the task needs an owned close control.
+
+## Rules
+
+- **MUST:** Render Overlay and Content as siblings inside Portal; never nest Content beneath the aria-hidden Overlay.
+- **MUST:** Give Content an accessible name with one Title or native aria-label or aria-labelledby; render Description only when useful or provide an explicit native description relationship.
+- **MUST:** Use Dialog-owned focus containment and restoration, background isolation, scroll locking, Escape handling, direct-target backdrop dismissal, and nested top-layer behavior instead of recreating them.
+- **MUST:** Mount descendant interactive portals inside Content when possible; otherwise register an unavoidable consumer-owned third-party portal with Modal.Branch.
+- **SHOULD:** Use initialFocus or finalFocus for explicit workflow targets and preserve Dialog's touch-safe content focus and restoration fallbacks for ordinary use.
+
+## Common mistakes
+
+- **Avoid:** Putting Content inside Overlay, omitting an accessible name, or adding custom document listeners and focus traps around Dialog. **Instead:** Keep Overlay and Content siblings, label Content, and rely on the Dialog and shared Modal contracts.
+
+## Validation checklist
+
+- Verify trigger semantics, accessible name and optional description, keyboard, pointer, touch, and programmatic initial focus, Tab containment, Close, top-layer Escape, direct-target backdrop dismissal, and focus restoration.
+- Verify controlled state, nested dialogs and descendant portals, background isolation, document scroll lock, long-content scrolling, exit presence, and authored-style cleanup.
+
+## Related guidance
+
+- `alert-dialog`
+- `modal`
+- `drawer`
+- `popover`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "dialog",
+  "name": "Dialog",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Present an ordinary blocking task, form, or information surface with modal focus, dismissal, labeling, portal, background-isolation, and scroll-lock behavior.",
+  "useWhen": [
+    "A user must focus on a temporary blocking task, form, or information surface before returning to the underlying application."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The user must make an urgent consequential choice, the task is a side sheet, or the panel is small, attached, and should usually remain non-modal.",
+      "useInstead": "AlertDialog, Drawer, or Popover"
+    }
+  ],
+  "composition": [
+    "Compose Root around Content; add Trigger for local activation or omit it for controlled and triggerless workflows, and use Portal only when the layer must leave its DOM location. When Overlay is rendered, keep it as a sibling of Content. Inside Content, use Title or native labeling for the accessible name, add Description only when useful, and add Close only when the task needs an owned close control."
+  ],
+  "rules": [
+    {
+      "id": "dialog-sibling-overlay",
+      "level": "must",
+      "statement": "Render Overlay and Content as siblings inside Portal; never nest Content beneath the aria-hidden Overlay."
+    },
+    {
+      "id": "dialog-accessible-name",
+      "level": "must",
+      "statement": "Give Content an accessible name with one Title or native aria-label or aria-labelledby; render Description only when useful or provide an explicit native description relationship."
+    },
+    {
+      "id": "dialog-owned-modal-behavior",
+      "level": "must",
+      "statement": "Use Dialog-owned focus containment and restoration, background isolation, scroll locking, Escape handling, direct-target backdrop dismissal, and nested top-layer behavior instead of recreating them."
+    },
+    {
+      "id": "dialog-descendant-portals",
+      "level": "must",
+      "statement": "Mount descendant interactive portals inside Content when possible; otherwise register an unavoidable consumer-owned third-party portal with Modal.Branch."
+    },
+    {
+      "id": "dialog-focus-targets",
+      "level": "should",
+      "statement": "Use initialFocus or finalFocus for explicit workflow targets and preserve Dialog's touch-safe content focus and restoration fallbacks for ordinary use."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Putting Content inside Overlay, omitting an accessible name, or adding custom document listeners and focus traps around Dialog.",
+      "correction": "Keep Overlay and Content siblings, label Content, and rely on the Dialog and shared Modal contracts."
+    }
+  ],
+  "validation": [
+    "Verify trigger semantics, accessible name and optional description, keyboard, pointer, touch, and programmatic initial focus, Tab containment, Close, top-layer Escape, direct-target backdrop dismissal, and focus restoration.",
+    "Verify controlled state, nested dialogs and descendant portals, background isolation, document scroll lock, long-content scrolling, exit presence, and authored-style cleanup."
+  ],
+  "related": [
+    "alert-dialog",
+    "modal",
+    "drawer",
+    "popover"
+  ]
+}
+```

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

@@ -0,0 +1,132 @@
+# Direction
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: direction
+
+# Direction agent guide
+
+## Purpose
+
+Provide left-to-right or right-to-left React context for Atom-owned keyboard, placement, gesture, and navigation behavior without rendering a DOM wrapper.
+
+## Use when
+
+- A subtree of Atom components must mirror direction-aware behavior for a left-to-right or right-to-left interface.
+
+## Choose something else when
+
+- Only document text direction needs to change, one component already has an accurate local dir prop, or visual mirroring is being attempted without semantic direction. Use the native dir attribute, the component's local dir prop, or direction-aware higher-layer styling.
+
+## Required composition
+
+- Set native dir and the appropriate language on the semantic HTML subtree, then wrap the matching Atom subtree in Direction.Provider with the same ltr or rtl value. Let a component-specific dir prop override context only for a deliberately different nested behavior direction.
+
+## Rules
+
+- **MUST:** Pair Direction.Provider with the matching native dir attribute because context mirrors Atom behavior but does not set browser text, punctuation, layout, or assistive-technology direction.
+- **MUST:** Use only ltr or rtl and keep Provider, native dir, written language, and content direction consistent; omitted context resolves to ltr.
+- **MUST:** Scope Provider to the Atom subtree whose behavior shares the direction and use nested Providers only at genuine bidirectional boundaries.
+- **MUST:** Treat a component's explicit dir prop as the local behavior override and verify it intentionally differs before overriding shared context.
+- **MUST:** Do not expect Provider to render a wrapper, role, ARIA attribute, data attribute, or styling hook.
+- **MUST:** Verify semantic start and end, Arrow keys, expand and collapse keys, placement, gestures, and focus movement in both directions for every composed primitive that owns direction-aware behavior.
+
+## Common mistakes
+
+- **Avoid:** Wrapping components in Direction.Provider without setting native dir on the document subtree. **Instead:** Set native dir for browser and assistive-technology semantics and use Provider for matching Atom behavior.
+- **Avoid:** Using CSS transforms to mirror controls or assuming every Arrow key should reverse in RTL. **Instead:** Use semantic direction and test each primitive's documented logical and spatial keyboard contract.
+- **Avoid:** Passing conflicting Provider and component-local directions accidentally. **Instead:** Choose one subtree direction and reserve local dir overrides for intentional nested behavior boundaries.
+
+## Validation checklist
+
+- Verify useDirection returns ltr outside a Provider and the nearest ltr or rtl value inside nested Providers, with no rendered wrapper or added attributes.
+- Inspect the final semantic subtree for matching native dir and language and test text, punctuation, focus order, logical start and end, and assistive-technology interpretation.
+- Exercise direction-aware Atom components in LTR and RTL, including horizontal navigation, tree expansion, popup placement, swipe or drag gestures, and any deliberate local dir override.
+
+## Related guidance
+
+- `menu`
+- `popover`
+- `tree-grid`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "direction",
+  "name": "Direction",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide left-to-right or right-to-left React context for Atom-owned keyboard, placement, gesture, and navigation behavior without rendering a DOM wrapper.",
+  "useWhen": [
+    "A subtree of Atom components must mirror direction-aware behavior for a left-to-right or right-to-left interface."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Only document text direction needs to change, one component already has an accurate local dir prop, or visual mirroring is being attempted without semantic direction.",
+      "useInstead": "the native dir attribute, the component's local dir prop, or direction-aware higher-layer styling"
+    }
+  ],
+  "composition": [
+    "Set native dir and the appropriate language on the semantic HTML subtree, then wrap the matching Atom subtree in Direction.Provider with the same ltr or rtl value. Let a component-specific dir prop override context only for a deliberately different nested behavior direction."
+  ],
+  "rules": [
+    {
+      "id": "direction-native-pair",
+      "level": "must",
+      "statement": "Pair Direction.Provider with the matching native dir attribute because context mirrors Atom behavior but does not set browser text, punctuation, layout, or assistive-technology direction."
+    },
+    {
+      "id": "direction-value",
+      "level": "must",
+      "statement": "Use only ltr or rtl and keep Provider, native dir, written language, and content direction consistent; omitted context resolves to ltr."
+    },
+    {
+      "id": "direction-scope",
+      "level": "must",
+      "statement": "Scope Provider to the Atom subtree whose behavior shares the direction and use nested Providers only at genuine bidirectional boundaries."
+    },
+    {
+      "id": "direction-local-override",
+      "level": "must",
+      "statement": "Treat a component's explicit dir prop as the local behavior override and verify it intentionally differs before overriding shared context."
+    },
+    {
+      "id": "direction-no-dom",
+      "level": "must",
+      "statement": "Do not expect Provider to render a wrapper, role, ARIA attribute, data attribute, or styling hook."
+    },
+    {
+      "id": "direction-behavior-test",
+      "level": "must",
+      "statement": "Verify semantic start and end, Arrow keys, expand and collapse keys, placement, gestures, and focus movement in both directions for every composed primitive that owns direction-aware behavior."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Wrapping components in Direction.Provider without setting native dir on the document subtree.",
+      "correction": "Set native dir for browser and assistive-technology semantics and use Provider for matching Atom behavior."
+    },
+    {
+      "mistake": "Using CSS transforms to mirror controls or assuming every Arrow key should reverse in RTL.",
+      "correction": "Use semantic direction and test each primitive's documented logical and spatial keyboard contract."
+    },
+    {
+      "mistake": "Passing conflicting Provider and component-local directions accidentally.",
+      "correction": "Choose one subtree direction and reserve local dir overrides for intentional nested behavior boundaries."
+    }
+  ],
+  "validation": [
+    "Verify useDirection returns ltr outside a Provider and the nearest ltr or rtl value inside nested Providers, with no rendered wrapper or added attributes.",
+    "Inspect the final semantic subtree for matching native dir and language and test text, punctuation, focus order, logical start and end, and assistive-technology interpretation.",
+    "Exercise direction-aware Atom components in LTR and RTL, including horizontal navigation, tree expansion, popup placement, swipe or drag gestures, and any deliberate local dir override."
+  ],
+  "related": [
+    "menu",
+    "popover",
+    "tree-grid"
+  ]
+}
+```

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

@@ -0,0 +1,94 @@
+# Divider
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: divider
+
+# Divider agent guide
+
+## Purpose
+
+Separate nearby content decoratively or with static separator semantics.
+
+## Use when
+
+- Two nearby content groups need a visual or meaningful static boundary.
+
+## Choose something else when
+
+- The boundary is draggable or changes a value. Use an interactive splitter with value and keyboard behavior.
+
+## Required composition
+
+- Use Divider.Root and keep decorative=true unless assistive technology must perceive the separation.
+
+## Rules
+
+- **MUST:** Choose decorative or semantic behavior from meaning, not from the desired line style.
+- **MUST:** Do not make Divider focusable or use it as a resize handle.
+
+## Common mistakes
+
+- **Avoid:** Exposing every visual line as a separator. **Instead:** Keep purely visual boundaries decorative.
+
+## Validation checklist
+
+- Confirm decorative dividers are absent from the accessibility tree.
+- Confirm semantic vertical dividers expose the correct orientation.
+
+## Related guidance
+
+- `toolbar`
+- `app-bar`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "divider",
+  "name": "Divider",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Separate nearby content decoratively or with static separator semantics.",
+  "useWhen": [
+    "Two nearby content groups need a visual or meaningful static boundary."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The boundary is draggable or changes a value.",
+      "useInstead": "an interactive splitter with value and keyboard behavior"
+    }
+  ],
+  "composition": [
+    "Use Divider.Root and keep decorative=true unless assistive technology must perceive the separation."
+  ],
+  "rules": [
+    {
+      "id": "divider-semantic-intent",
+      "level": "must",
+      "statement": "Choose decorative or semantic behavior from meaning, not from the desired line style."
+    },
+    {
+      "id": "divider-not-interactive",
+      "level": "must",
+      "statement": "Do not make Divider focusable or use it as a resize handle."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Exposing every visual line as a separator.",
+      "correction": "Keep purely visual boundaries decorative."
+    }
+  ],
+  "validation": [
+    "Confirm decorative dividers are absent from the accessibility tree.",
+    "Confirm semantic vertical dividers expose the correct orientation."
+  ],
+  "related": [
+    "toolbar",
+    "app-bar"
+  ]
+}
+```