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

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

@@ -0,0 +1,120 @@
+# Menubar
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: menubar
+
+# Menubar agent guide
+
+## Purpose
+
+Coordinate a persistent application-style set of top-level menus with menubar semantics, roving trigger focus, adjacent-menu handoff, and shared Menu content behavior.
+
+## Use when
+
+- A desktop-like application has several persistent command groups such as File, Edit, and View that must behave as one keyboard menubar.
+
+## Choose something else when
+
+- There is one temporary command menu, ordinary website navigation, a normal link list, or only a few independent buttons. Use DropdownMenu, NavigationMenu, NavList, Toolbar, or Button.
+
+## Required composition
+
+- Give Root an accessible name and compose one or more uniquely valued Menu scopes, each with Trigger and Content. Use shared Menu items and add Portal, Arrow, grouping, selection items, separators, or paired submenus only when required.
+
+## Rules
+
+- **MUST:** Give the role=menubar Root an accessible name and keep each top-level Trigger as its role=menuitem child with one roving tab stop.
+- **MUST:** Provide a unique value for every top-level Menu and keep its Trigger and Content inside that Menu scope.
+- **MUST:** Match orientation to the rendered arrangement and preserve direction-aware top-level Arrow movement, adjacent open-menu handoff, and nested submenu keys in LTR and RTL.
+- **MUST:** Preserve Menu's real item focus, typeahead, selection roles, disabled navigation, close policies, submenus, Tab exit across the complete Root, Escape stack, portals, and parent-modal ownership.
+- **MUST:** When Root, Trigger, Content, or shared retained parts use asChild or render, preserve Atom roles, refs, handlers, native props, ARIA, data state, and children.
+
+## Common mistakes
+
+- **Avoid:** Using Menubar as styled website navigation, omitting its accessible name, duplicating top-level values, or implementing each heading as an independent dropdown. **Instead:** Use Menubar only for application command groups and preserve its single roving, orientation-aware top-level ownership.
+
+## Validation checklist
+
+- Verify Root naming and orientation, unique menu values, one top-level tab stop, Home/End, horizontal and vertical Arrow movement, LTR and RTL, pointer and touch opening, keyboard first/last opening, hover switching, controlled active value, disabled triggers, and adjacent-menu focus ownership.
+- Verify shared item roles, typeahead, checkbox and radio state, submenus, selection close policy, whole-root Tab exit, top-layer Escape, focus return, portals, parent-modal focus registration, and asChild/render composition.
+
+## Related guidance
+
+- `menu`
+- `dropdown-menu`
+- `context-menu`
+- `navigation-menu`
+- `nav-list`
+- `toolbar`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "menubar",
+  "name": "Menubar",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Coordinate a persistent application-style set of top-level menus with menubar semantics, roving trigger focus, adjacent-menu handoff, and shared Menu content behavior.",
+  "useWhen": [
+    "A desktop-like application has several persistent command groups such as File, Edit, and View that must behave as one keyboard menubar."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "There is one temporary command menu, ordinary website navigation, a normal link list, or only a few independent buttons.",
+      "useInstead": "DropdownMenu, NavigationMenu, NavList, Toolbar, or Button"
+    }
+  ],
+  "composition": [
+    "Give Root an accessible name and compose one or more uniquely valued Menu scopes, each with Trigger and Content. Use shared Menu items and add Portal, Arrow, grouping, selection items, separators, or paired submenus only when required."
+  ],
+  "rules": [
+    {
+      "id": "menubar-root-semantics",
+      "level": "must",
+      "statement": "Give the role=menubar Root an accessible name and keep each top-level Trigger as its role=menuitem child with one roving tab stop."
+    },
+    {
+      "id": "menubar-unique-menu-values",
+      "level": "must",
+      "statement": "Provide a unique value for every top-level Menu and keep its Trigger and Content inside that Menu scope."
+    },
+    {
+      "id": "menubar-orientation-direction",
+      "level": "must",
+      "statement": "Match orientation to the rendered arrangement and preserve direction-aware top-level Arrow movement, adjacent open-menu handoff, and nested submenu keys in LTR and RTL."
+    },
+    {
+      "id": "menubar-shared-content",
+      "level": "must",
+      "statement": "Preserve Menu's real item focus, typeahead, selection roles, disabled navigation, close policies, submenus, Tab exit across the complete Root, Escape stack, portals, and parent-modal ownership."
+    },
+    {
+      "id": "menubar-composition-merge",
+      "level": "must",
+      "statement": "When Root, Trigger, Content, or shared retained parts use asChild or render, preserve Atom roles, refs, handlers, native props, ARIA, data state, and children."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Menubar as styled website navigation, omitting its accessible name, duplicating top-level values, or implementing each heading as an independent dropdown.",
+      "correction": "Use Menubar only for application command groups and preserve its single roving, orientation-aware top-level ownership."
+    }
+  ],
+  "validation": [
+    "Verify Root naming and orientation, unique menu values, one top-level tab stop, Home/End, horizontal and vertical Arrow movement, LTR and RTL, pointer and touch opening, keyboard first/last opening, hover switching, controlled active value, disabled triggers, and adjacent-menu focus ownership.",
+    "Verify shared item roles, typeahead, checkbox and radio state, submenus, selection close policy, whole-root Tab exit, top-layer Escape, focus return, portals, parent-modal focus registration, and asChild/render composition."
+  ],
+  "related": [
+    "menu",
+    "dropdown-menu",
+    "context-menu",
+    "navigation-menu",
+    "nav-list",
+    "toolbar"
+  ]
+}
+```

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

@@ -0,0 +1,118 @@
+# Modal
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: modal
+
+# Modal agent guide
+
+## Purpose
+
+Provide the shared headless foundation for custom modal-family primitives, including state, layer ownership, focus containment and restoration, background isolation, scroll locking, dismissal, and portal branches.
+
+## Use when
+
+- A primitive author must build a custom blocking layer whose behavior cannot be expressed by Dialog, AlertDialog, or Drawer and must reuse Atom's modal ownership contract.
+
+## Choose something else when
+
+- An application needs an ordinary modal task, an urgent consequential decision, a modal side sheet, or a small attached interactive panel. Use Dialog, AlertDialog, Drawer, or Popover.
+
+## Required composition
+
+- Compose Root around the custom content owner; add Trigger for local activation or omit it for controlled and triggerless workflows, and use Portal only when the content must leave its DOM location. Build the content owner with useModalContent, spread its contentProps onto the focusable content element, and compose the returned presenceRef with the content ref.
+- Place Title when it supplies the accessible name, Description when descriptive context is needed, and Close when the surface needs an owned close control. Native labeling can replace Title, and controlled workflows can close without Close. Register consumer-owned third-party portals with Branch only when they cannot be mounted inside the content element.
+
+## Rules
+
+- **MUST:** Use Modal as a primitive-authoring foundation, not as a shortcut around the purpose-built Dialog, AlertDialog, Drawer, or Popover contracts.
+- **MUST:** Apply every useModalContent contentProp and the composed presenceRef to the real content element so role, ARIA, focus, presence, isolation, and layer ownership remain intact.
+- **MUST:** Give the owned content an accessible name with one Title or native aria-label or aria-labelledby; add Description or a native description relationship when the contract requires one.
+- **MUST:** Prefer mounting descendant portals inside the content; otherwise wrap only the same-document third-party portal owner with Branch so focus, isolation, and scrolling recognize it.
+- **SHOULD:** Use initialFocus and finalFocus only for explicit workflow targets; preserve the built-in touch-safe initial focus, top-layer containment, and restoration fallbacks unless the workflow intentionally disables them.
+
+## Common mistakes
+
+- **Avoid:** Rendering a custom role=dialog node while using only Root state, or treating an arbitrary portalled descendant as automatically inside the modal. **Instead:** Build the content through useModalContent and either mount descendant layers inside it or register an unavoidable third-party portal with Branch.
+
+## Validation checklist
+
+- Verify controlled and uncontrolled state, accessible naming, initial focus for keyboard, pointer, touch, and programmatic opening, Tab containment, top-layer Escape and backdrop behavior, exit presence, scroll lock, and final-focus restoration.
+- Verify nested modal ownership and every registered Branch with keyboard focus, wheel and touch scrolling, background isolation, unmount cleanup, and same-document portal containers.
+
+## Related guidance
+
+- `dialog`
+- `alert-dialog`
+- `drawer`
+- `popover`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "modal",
+  "name": "Modal",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide the shared headless foundation for custom modal-family primitives, including state, layer ownership, focus containment and restoration, background isolation, scroll locking, dismissal, and portal branches.",
+  "useWhen": [
+    "A primitive author must build a custom blocking layer whose behavior cannot be expressed by Dialog, AlertDialog, or Drawer and must reuse Atom's modal ownership contract."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "An application needs an ordinary modal task, an urgent consequential decision, a modal side sheet, or a small attached interactive panel.",
+      "useInstead": "Dialog, AlertDialog, Drawer, or Popover"
+    }
+  ],
+  "composition": [
+    "Compose Root around the custom content owner; add Trigger for local activation or omit it for controlled and triggerless workflows, and use Portal only when the content must leave its DOM location. Build the content owner with useModalContent, spread its contentProps onto the focusable content element, and compose the returned presenceRef with the content ref.",
+    "Place Title when it supplies the accessible name, Description when descriptive context is needed, and Close when the surface needs an owned close control. Native labeling can replace Title, and controlled workflows can close without Close. Register consumer-owned third-party portals with Branch only when they cannot be mounted inside the content element."
+  ],
+  "rules": [
+    {
+      "id": "modal-foundation-only",
+      "level": "must",
+      "statement": "Use Modal as a primitive-authoring foundation, not as a shortcut around the purpose-built Dialog, AlertDialog, Drawer, or Popover contracts."
+    },
+    {
+      "id": "modal-content-contract",
+      "level": "must",
+      "statement": "Apply every useModalContent contentProp and the composed presenceRef to the real content element so role, ARIA, focus, presence, isolation, and layer ownership remain intact."
+    },
+    {
+      "id": "modal-accessible-name",
+      "level": "must",
+      "statement": "Give the owned content an accessible name with one Title or native aria-label or aria-labelledby; add Description or a native description relationship when the contract requires one."
+    },
+    {
+      "id": "modal-branch-scope",
+      "level": "must",
+      "statement": "Prefer mounting descendant portals inside the content; otherwise wrap only the same-document third-party portal owner with Branch so focus, isolation, and scrolling recognize it."
+    },
+    {
+      "id": "modal-focus-policy",
+      "level": "should",
+      "statement": "Use initialFocus and finalFocus only for explicit workflow targets; preserve the built-in touch-safe initial focus, top-layer containment, and restoration fallbacks unless the workflow intentionally disables them."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Rendering a custom role=dialog node while using only Root state, or treating an arbitrary portalled descendant as automatically inside the modal.",
+      "correction": "Build the content through useModalContent and either mount descendant layers inside it or register an unavoidable third-party portal with Branch."
+    }
+  ],
+  "validation": [
+    "Verify controlled and uncontrolled state, accessible naming, initial focus for keyboard, pointer, touch, and programmatic opening, Tab containment, top-layer Escape and backdrop behavior, exit presence, scroll lock, and final-focus restoration.",
+    "Verify nested modal ownership and every registered Branch with keyboard focus, wheel and touch scrolling, background isolation, unmount cleanup, and same-document portal containers."
+  ],
+  "related": [
+    "dialog",
+    "alert-dialog",
+    "drawer",
+    "popover"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/multi-select.txt

@@ -0,0 +1,120 @@
+# MultiSelect
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: multi-select
+
+# MultiSelect agent guide
+
+## Purpose
+
+Choose several predefined values from a compact button-owned popup listbox with persistent toggling, value summary, positioning, validation, and native multiple-select form behavior.
+
+## Use when
+
+- Users choose several values from a predefined moderate collection and the options should remain collapsed until requested.
+
+## Choose something else when
+
+- A short choice set should stay visible, the collection should remain visible, only one value is allowed, or editable filtering, arbitrary tags, creation, range selection, or virtualization is required. Use CheckboxGroup, Listbox, Select, Combobox, or a higher-layer specialized control.
+
+## Required composition
+
+- Compose Root with an accessible Trigger containing optional Value and Icon, then one Content or Listbox with uniquely valued Items and ItemText. Add Portal, Viewport, groups and labels, separators, scroll buttons, indicators, and Arrow only as required by the popup.
+
+## Rules
+
+- **MUST:** Keep Trigger as a named button rather than role=combobox, and keep Content as the focusable aria-multiselectable listbox that owns required and read-only semantics.
+- **MUST:** Use deduplicated array state for value and defaultValue, route controlled changes through onValueChange, and keep Content open while Items toggle.
+- **MUST:** Give every Item a stable unique value and ItemText or label so summaries, option names, typeahead, and native options exist while the popup is closed.
+- **MUST:** Preserve popup focus, Arrow and Home/End movement, typeahead, Space/Enter toggling without close, Escape focus restoration, Tab dismissal, disabled skipping, and completed preventable outside dismissal.
+- **MUST:** Preserve the hidden native multiple select's complete option set, repeated selected values, name, form, disabled state, required validity, reset, and invalid-focus redirection to Trigger.
+
+## Common mistakes
+
+- **Avoid:** Giving Trigger combobox semantics, closing after every selection, using MultiSelect for arbitrary tag creation, or deriving form options only from an open popup. **Instead:** Keep the button/listbox model, persistent toggling, predefined scope, and statically registered native option contract.
+
+## Validation checklist
+
+- Verify Trigger and listbox naming, controlled/uncontrolled arrays and open state, deduplication, zero/one/many Value summaries and renderValue, popup focus, Arrow/Home/End, typeahead, Space/Enter toggling without close, disabled Items, Escape, Tab, outside activation, and focus restoration.
+- Verify read-only on listbox rather than Trigger, Field relationships, hidden multiple-select options and repeated submission, required inline/native validation, external form, reset, groups, indicators, Viewport and scroll buttons, portals, direction, collision placement, and nested-modal behavior.
+
+## Related guidance
+
+- `select`
+- `listbox`
+- `combobox`
+- `checkbox-group`
+- `field`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "multi-select",
+  "name": "MultiSelect",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Choose several predefined values from a compact button-owned popup listbox with persistent toggling, value summary, positioning, validation, and native multiple-select form behavior.",
+  "useWhen": [
+    "Users choose several values from a predefined moderate collection and the options should remain collapsed until requested."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A short choice set should stay visible, the collection should remain visible, only one value is allowed, or editable filtering, arbitrary tags, creation, range selection, or virtualization is required.",
+      "useInstead": "CheckboxGroup, Listbox, Select, Combobox, or a higher-layer specialized control"
+    }
+  ],
+  "composition": [
+    "Compose Root with an accessible Trigger containing optional Value and Icon, then one Content or Listbox with uniquely valued Items and ItemText. Add Portal, Viewport, groups and labels, separators, scroll buttons, indicators, and Arrow only as required by the popup."
+  ],
+  "rules": [
+    {
+      "id": "multi-select-trigger-listbox",
+      "level": "must",
+      "statement": "Keep Trigger as a named button rather than role=combobox, and keep Content as the focusable aria-multiselectable listbox that owns required and read-only semantics."
+    },
+    {
+      "id": "multi-select-array-state",
+      "level": "must",
+      "statement": "Use deduplicated array state for value and defaultValue, route controlled changes through onValueChange, and keep Content open while Items toggle."
+    },
+    {
+      "id": "multi-select-item-text",
+      "level": "must",
+      "statement": "Give every Item a stable unique value and ItemText or label so summaries, option names, typeahead, and native options exist while the popup is closed."
+    },
+    {
+      "id": "multi-select-keyboard",
+      "level": "must",
+      "statement": "Preserve popup focus, Arrow and Home/End movement, typeahead, Space/Enter toggling without close, Escape focus restoration, Tab dismissal, disabled skipping, and completed preventable outside dismissal."
+    },
+    {
+      "id": "multi-select-form",
+      "level": "must",
+      "statement": "Preserve the hidden native multiple select's complete option set, repeated selected values, name, form, disabled state, required validity, reset, and invalid-focus redirection to Trigger."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Giving Trigger combobox semantics, closing after every selection, using MultiSelect for arbitrary tag creation, or deriving form options only from an open popup.",
+      "correction": "Keep the button/listbox model, persistent toggling, predefined scope, and statically registered native option contract."
+    }
+  ],
+  "validation": [
+    "Verify Trigger and listbox naming, controlled/uncontrolled arrays and open state, deduplication, zero/one/many Value summaries and renderValue, popup focus, Arrow/Home/End, typeahead, Space/Enter toggling without close, disabled Items, Escape, Tab, outside activation, and focus restoration.",
+    "Verify read-only on listbox rather than Trigger, Field relationships, hidden multiple-select options and repeated submission, required inline/native validation, external form, reset, groups, indicators, Viewport and scroll buttons, portals, direction, collision placement, and nested-modal behavior."
+  ],
+  "related": [
+    "select",
+    "listbox",
+    "combobox",
+    "checkbox-group",
+    "field",
+    "form"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/nav-list.txt

@@ -0,0 +1,104 @@
+# NavList
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: nav-list
+
+# NavList agent guide
+
+## Purpose
+
+Structure persistent, optionally grouped and collapsible navigation lists with current-destination state.
+
+## Use when
+
+- A sidebar, rail, drawer, or page region contains a persistent list of routes, optionally grouped into sections.
+
+## Choose something else when
+
+- Navigation opens disclosure panels from a top bar or switches local tab panels. Use NavigationMenu or Tabs.
+
+## Required composition
+
+- Compose Root > List > Item > Link; use Section with SectionLabel and SectionContent, adding SectionTrigger only when the section is actually collapsible.
+
+## Rules
+
+- **MUST:** Use Link parts for destinations and expose the current destination through the component contract.
+- **MUST:** Use a SectionTrigger only when it controls the associated SectionContent.
+- **MUST:** Style collapsible SectionContent from its data-state and measured content-size hooks; Atom keeps exit content mounted through the animation lifecycle.
+
+## Common mistakes
+
+- **Avoid:** Using generic clickable rows for routes or adding a disclosure trigger to a static heading. **Instead:** Use NavList.Link for routes and SectionLabel alone for non-collapsible groups.
+
+## Validation checklist
+
+- Confirm navigation and section labels are meaningful and current state matches the route.
+- Confirm collapsed content is not keyboard reachable and trigger state is announced.
+
+## Related guidance
+
+- `navigation-menu`
+- `sidebar`
+- `drawer`
+- `link`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "nav-list",
+  "name": "NavList",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Structure persistent, optionally grouped and collapsible navigation lists with current-destination state.",
+  "useWhen": [
+    "A sidebar, rail, drawer, or page region contains a persistent list of routes, optionally grouped into sections."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Navigation opens disclosure panels from a top bar or switches local tab panels.",
+      "useInstead": "NavigationMenu or Tabs"
+    }
+  ],
+  "composition": [
+    "Compose Root > List > Item > Link; use Section with SectionLabel and SectionContent, adding SectionTrigger only when the section is actually collapsible."
+  ],
+  "rules": [
+    {
+      "id": "nav-list-links",
+      "level": "must",
+      "statement": "Use Link parts for destinations and expose the current destination through the component contract."
+    },
+    {
+      "id": "nav-list-section-trigger",
+      "level": "must",
+      "statement": "Use a SectionTrigger only when it controls the associated SectionContent."
+    },
+    {
+      "id": "nav-list-section-motion",
+      "level": "must",
+      "statement": "Style collapsible SectionContent from its data-state and measured content-size hooks; Atom keeps exit content mounted through the animation lifecycle."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using generic clickable rows for routes or adding a disclosure trigger to a static heading.",
+      "correction": "Use NavList.Link for routes and SectionLabel alone for non-collapsible groups."
+    }
+  ],
+  "validation": [
+    "Confirm navigation and section labels are meaningful and current state matches the route.",
+    "Confirm collapsed content is not keyboard reachable and trigger state is announced."
+  ],
+  "related": [
+    "navigation-menu",
+    "sidebar",
+    "drawer",
+    "link"
+  ]
+}
+```

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

@@ -0,0 +1,104 @@
+# NavigationMenu
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: navigation-menu
+
+# NavigationMenu agent guide
+
+## Purpose
+
+Provide disclosure navigation with coordinated triggers, links, content, viewport geometry, focus, keyboard, pointer, and dismissal behavior.
+
+## Use when
+
+- Site or product navigation contains top-level links and disclosure panels of related destinations.
+
+## Choose something else when
+
+- The interface is an action menu, persistent route list, or tab panel switcher. Use Menu, NavList, or Tabs.
+
+## Required composition
+
+- Compose Root > List > Item containing Link or Trigger plus Content; use one Viewport for shared positioned content and Indicator when the styled layer needs trigger geometry.
+
+## Rules
+
+- **MUST:** Use NavigationMenu for destinations, not commands, selections, or arbitrary popover content.
+- **MUST:** Use the primitive's trigger, content, viewport, arrow, offset, focus, and dismissal contracts instead of manually positioning a competing overlay.
+- **MUST:** Let Viewport's active-trigger and collision geometry position a horizontal panel; customize collisionPadding only when the surrounding layout needs a different visible-edge inset.
+
+## Common mistakes
+
+- **Avoid:** Positioning content against the page or logo rather than its owning trigger/viewport, or using menuitem semantics. **Instead:** Keep the documented List/Item/Trigger/Content/Viewport composition and native link semantics.
+
+## Validation checklist
+
+- Test pointer hover, click, keyboard opening, arrow navigation, focus transfer, outside dismissal, Escape, RTL geometry, narrow panels, and first/last-trigger viewport collisions.
+- Confirm links navigate normally and action-menu roles are absent.
+
+## Related guidance
+
+- `nav-list`
+- `menubar`
+- `dropdown-menu`
+- `app-bar`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "navigation-menu",
+  "name": "NavigationMenu",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide disclosure navigation with coordinated triggers, links, content, viewport geometry, focus, keyboard, pointer, and dismissal behavior.",
+  "useWhen": [
+    "Site or product navigation contains top-level links and disclosure panels of related destinations."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The interface is an action menu, persistent route list, or tab panel switcher.",
+      "useInstead": "Menu, NavList, or Tabs"
+    }
+  ],
+  "composition": [
+    "Compose Root > List > Item containing Link or Trigger plus Content; use one Viewport for shared positioned content and Indicator when the styled layer needs trigger geometry."
+  ],
+  "rules": [
+    {
+      "id": "navigation-menu-destinations",
+      "level": "must",
+      "statement": "Use NavigationMenu for destinations, not commands, selections, or arbitrary popover content."
+    },
+    {
+      "id": "navigation-menu-geometry",
+      "level": "must",
+      "statement": "Use the primitive's trigger, content, viewport, arrow, offset, focus, and dismissal contracts instead of manually positioning a competing overlay."
+    },
+    {
+      "id": "navigation-menu-viewport-position",
+      "level": "must",
+      "statement": "Let Viewport's active-trigger and collision geometry position a horizontal panel; customize collisionPadding only when the surrounding layout needs a different visible-edge inset."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Positioning content against the page or logo rather than its owning trigger/viewport, or using menuitem semantics.",
+      "correction": "Keep the documented List/Item/Trigger/Content/Viewport composition and native link semantics."
+    }
+  ],
+  "validation": [
+    "Test pointer hover, click, keyboard opening, arrow navigation, focus transfer, outside dismissal, Escape, RTL geometry, narrow panels, and first/last-trigger viewport collisions.",
+    "Confirm links navigate normally and action-menu roles are absent."
+  ],
+  "related": [
+    "nav-list",
+    "menubar",
+    "dropdown-menu",
+    "app-bar"
+  ]
+}
+```