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

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

@@ -0,0 +1,174 @@
+# Menubar
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: menubar
+
+# Menubar agent guide
+
+## Purpose
+
+Present a finished persistent application command strip with coordinated top-level menus while Atom owns menubar semantics, roving focus, adjacent-menu handoff, and shared Menu behavior.
+
+## Use when
+
+- A desktop-like application has several persistent command categories 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 route list, or a toolbar of immediately executable controls. Use DropdownMenu, NavigationMenu or NavList, or Toolbar.
+- The application needs responsive mobile replacement or overflow orchestration. Use An application-owned composition using DropdownMenu, Drawer, or another appropriate command surface.
+
+## Required composition
+
+- Give Menubar.Root an accessible name and compose one or more uniquely valued Menubar.Menu scopes, each containing Menubar.Trigger and portalled Menubar.Content. Build Content from the shared command, selection, grouping, separator, static row, and paired submenu anatomy.
+- Root owns sm, md, or lg density and horizontal or vertical orientation; Content and SubContent inherit that density. Reproduce any local Appearance scope on each portalled visual root.
+
+## Rules
+
+- **MUST:** Use Menubar only for persistent application command categories, not website navigation, page tabs, route-current state, or a responsive application shell.
+- **MUST:** Give the role=menubar Root an accessible name and keep every top-level Trigger as its role=menuitem child with one Atom-owned roving tab stop.
+- **MUST:** Give every top-level Menu a unique value and keep its Trigger and Content within that Menu scope so controlled value and adjacent-menu handoff remain deterministic.
+- **MUST:** Match orientation to the visible Root arrangement and preserve direction-aware Arrow movement, Home/End, first and last item opening, adjacent handoff, and nested submenu keys in LTR and RTL.
+- **MUST:** Preserve uniquely valued item roles, real focus, typeahead, disabled navigation, checkbox and radio state, closeOnSelect, paired submenus, whole-root Tab exit, Escape restoration, and parent-modal ownership.
+- **MUST:** Use Leading, ItemLabel, Description, Shortcut, ItemIndicator, and tone=danger for their documented jobs; shortcuts are visual hints and Menubar does not register global commands.
+- **MUST:** Do not automatically wrap, collapse, or change Menubar semantics at a breakpoint; applications own an explicit scrolling region or a separately selected mobile command surface.
+- **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:** Load styles.css or core.css plus menubar.css and every composed child component stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Using Menubar as styled website navigation, omitting Root's name, duplicating top-level values, or implementing each heading as an independent dropdown. **Instead:** Use Menubar only for application commands and preserve its named, uniquely valued, orientation-aware top-level ownership.
+- **Avoid:** Hiding or collapsing the command strip at a Brick breakpoint or treating Shortcut text as registered keyboard behavior. **Instead:** Let the application select a responsive alternative and keep shortcut execution in application code.
+
+## 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 and last opening, hover switching, controlled active value, disabled triggers, and adjacent-menu focus ownership.
+- Verify shared item focus and typeahead, checkbox mixed and radio state, submenus, selection close policy, whole-root Tab exit, top-layer Escape, focus return, portals, parent-modal ownership, and asChild or render composition.
+- Verify three densities, persistent Root and open-trigger paint, constrained popup scrolling, danger meaning, narrow overflow policy, zoom, long localization, reduced motion, forced colors, portalled appearance, and complete CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/menubar`
+- `@flowstack-ui/atom/agents/menu`
+- `dropdown-menu`
+- `context-menu`
+- `navigation-menu`
+- `nav-list`
+- `toolbar`
+- `drawer`
+- `appearance`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "menubar",
+  "name": "Menubar",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished persistent application command strip with coordinated top-level menus while Atom owns menubar semantics, roving focus, adjacent-menu handoff, and shared Menu behavior.",
+  "useWhen": [
+    "A desktop-like application has several persistent command categories 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 route list, or a toolbar of immediately executable controls.",
+      "useInstead": "DropdownMenu, NavigationMenu or NavList, or Toolbar"
+    },
+    {
+      "condition": "The application needs responsive mobile replacement or overflow orchestration.",
+      "useInstead": "An application-owned composition using DropdownMenu, Drawer, or another appropriate command surface"
+    }
+  ],
+  "composition": [
+    "Give Menubar.Root an accessible name and compose one or more uniquely valued Menubar.Menu scopes, each containing Menubar.Trigger and portalled Menubar.Content. Build Content from the shared command, selection, grouping, separator, static row, and paired submenu anatomy.",
+    "Root owns sm, md, or lg density and horizontal or vertical orientation; Content and SubContent inherit that density. Reproduce any local Appearance scope on each portalled visual root."
+  ],
+  "rules": [
+    {
+      "id": "menubar-application-commands",
+      "level": "must",
+      "statement": "Use Menubar only for persistent application command categories, not website navigation, page tabs, route-current state, or a responsive application shell."
+    },
+    {
+      "id": "menubar-root-name",
+      "level": "must",
+      "statement": "Give the role=menubar Root an accessible name and keep every top-level Trigger as its role=menuitem child with one Atom-owned roving tab stop."
+    },
+    {
+      "id": "menubar-menu-scope",
+      "level": "must",
+      "statement": "Give every top-level Menu a unique value and keep its Trigger and Content within that Menu scope so controlled value and adjacent-menu handoff remain deterministic."
+    },
+    {
+      "id": "menubar-orientation",
+      "level": "must",
+      "statement": "Match orientation to the visible Root arrangement and preserve direction-aware Arrow movement, Home/End, first and last item opening, adjacent handoff, and nested submenu keys in LTR and RTL."
+    },
+    {
+      "id": "menubar-shared-menu-contract",
+      "level": "must",
+      "statement": "Preserve uniquely valued item roles, real focus, typeahead, disabled navigation, checkbox and radio state, closeOnSelect, paired submenus, whole-root Tab exit, Escape restoration, and parent-modal ownership."
+    },
+    {
+      "id": "menubar-row-anatomy",
+      "level": "must",
+      "statement": "Use Leading, ItemLabel, Description, Shortcut, ItemIndicator, and tone=danger for their documented jobs; shortcuts are visual hints and Menubar does not register global commands."
+    },
+    {
+      "id": "menubar-responsive",
+      "level": "must",
+      "statement": "Do not automatically wrap, collapse, or change Menubar semantics at a breakpoint; applications own an explicit scrolling region or a separately selected mobile command surface."
+    },
+    {
+      "id": "menubar-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": "menubar-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus menubar.css and every composed child component stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Menubar as styled website navigation, omitting Root's name, duplicating top-level values, or implementing each heading as an independent dropdown.",
+      "correction": "Use Menubar only for application commands and preserve its named, uniquely valued, orientation-aware top-level ownership."
+    },
+    {
+      "mistake": "Hiding or collapsing the command strip at a Brick breakpoint or treating Shortcut text as registered keyboard behavior.",
+      "correction": "Let the application select a responsive alternative and keep shortcut execution in application code."
+    }
+  ],
+  "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 and last opening, hover switching, controlled active value, disabled triggers, and adjacent-menu focus ownership.",
+    "Verify shared item focus and typeahead, checkbox mixed and radio state, submenus, selection close policy, whole-root Tab exit, top-layer Escape, focus return, portals, parent-modal ownership, and asChild or render composition.",
+    "Verify three densities, persistent Root and open-trigger paint, constrained popup scrolling, danger meaning, narrow overflow policy, zoom, long localization, reduced motion, forced colors, portalled appearance, and complete CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "menubar",
+      "versionPolicy": "installed-exact"
+    },
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "menu",
+      "versionPolicy": "installed-exact"
+    },
+    "dropdown-menu",
+    "context-menu",
+    "navigation-menu",
+    "nav-list",
+    "toolbar",
+    "drawer",
+    "appearance"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/multi-select.txt

@@ -0,0 +1,153 @@
+# MultiSelect
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: multi-select
+
+# MultiSelect agent guide
+
+## Purpose
+
+Present several selected predefined values in a compact finished control while Atom owns array state, popup listbox focus, persistent toggling, positioning, validation, and native multiple-select submission.
+
+## Use when
+
+- A person chooses zero or more values from a predefined moderate collection that should remain collapsed until requested.
+
+## Choose something else when
+
+- A short choice set should stay visible, only one value is allowed, or editable filtering, arbitrary tags, creation, range selection, or virtualization is required. Use CheckboxGroup, Select, Combobox, or a documented Brick gap or higher-layer specialized control.
+
+## Required composition
+
+- Compose MultiSelect.Root with a named button Trigger containing Value and optional Icon, then exactly one Content or Listbox with stable uniquely valued Items and ItemText. Add Portal, Viewport, groups and labels, separators, scroll buttons, indicators, and a direct Arrow only as required.
+- Use sm, md, or lg consistently with adjacent button-like controls. Keep selected values, persistence, remote data, and application effects at the application boundary.
+
+## Rules
+
+- **MUST:** Use MultiSelect only for several predefined values; do not add editable filtering, arbitrary tags, commands, destinations, range selection, or virtualization.
+- **MUST:** Keep Trigger a separately named button rather than role=combobox and keep Content or Listbox as the focusable aria-multiselectable owner of required and read-only semantics.
+- **MUST:** Use deduplicated arrays for value and defaultValue, route controlled changes through onValueChange, and keep the popup open while Items toggle.
+- **MUST:** Give every Item a stable unique value and ItemText or label so summaries, option names, typeahead, and native options remain complete while the popup is closed.
+- **MUST:** Preserve popup focus, Arrow/Home/End, typeahead, Space/Enter toggling without close, Escape focus restoration, Tab dismissal, disabled skipping, native repeated-value submission, required validity, external form, and reset.
+- **MUST:** Keep Trigger, summaries, and collision-aware popup contained under long localization, narrow widths, zoom, and RTL; do not place removal buttons inside the v1 button Trigger.
+- **MUST:** Load styles.css or core.css plus multi-select.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Giving Trigger combobox semantics, using selected summary as its name, closing after each toggle, or deriving native options only from an open popup. **Instead:** Preserve the named button/listbox model, persistent toggling, static Item registration, and complete native option contract.
+- **Avoid:** Adding text entry, arbitrary tag creation, interactive descendants, or application persistence inside the component. **Instead:** Keep predefined noninteractive Items and choose an approved editable higher-layer pattern or record the missing Brick capability.
+
+## Validation checklist
+
+- Verify Trigger and listbox names, controlled and uncontrolled arrays and open state, deduplication, zero/one/many summaries and renderValue, popup focus, Arrow/Home/End, typeahead, Space/Enter without close, disabled Items, Escape, Tab, outside activation, and focus restoration.
+- Verify read-only on the listbox, Field relationships, hidden multiple-select options and repeated submission, required inline/native validation, external form, reset, groups, indicators, Viewport, scroll buttons, Portal, direction, collision placement, and nested modal behavior.
+- Verify all sizes, long summaries and option labels, narrow widths, zoom, RTL, touch targets, light and dark appearance, forced colors, and button-like control alignment.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/multi-select`
+- `@flowstack-ui/atom/agents/listbox`
+- `field`
+- `form`
+- `select`
+- `combobox`
+- `checkbox-group`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "multi-select",
+  "name": "MultiSelect",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present several selected predefined values in a compact finished control while Atom owns array state, popup listbox focus, persistent toggling, positioning, validation, and native multiple-select submission.",
+  "useWhen": [
+    "A person chooses zero or more values from a predefined moderate collection that should remain collapsed until requested."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A short choice set should stay visible, only one value is allowed, or editable filtering, arbitrary tags, creation, range selection, or virtualization is required.",
+      "useInstead": "CheckboxGroup, Select, Combobox, or a documented Brick gap or higher-layer specialized control"
+    }
+  ],
+  "composition": [
+    "Compose MultiSelect.Root with a named button Trigger containing Value and optional Icon, then exactly one Content or Listbox with stable uniquely valued Items and ItemText. Add Portal, Viewport, groups and labels, separators, scroll buttons, indicators, and a direct Arrow only as required.",
+    "Use sm, md, or lg consistently with adjacent button-like controls. Keep selected values, persistence, remote data, and application effects at the application boundary."
+  ],
+  "rules": [
+    {
+      "id": "multi-select-predefined-values",
+      "level": "must",
+      "statement": "Use MultiSelect only for several predefined values; do not add editable filtering, arbitrary tags, commands, destinations, range selection, or virtualization."
+    },
+    {
+      "id": "multi-select-semantics",
+      "level": "must",
+      "statement": "Keep Trigger a separately named button rather than role=combobox and keep Content or Listbox as the focusable aria-multiselectable owner of required and read-only semantics."
+    },
+    {
+      "id": "multi-select-array-state",
+      "level": "must",
+      "statement": "Use deduplicated arrays for value and defaultValue, route controlled changes through onValueChange, and keep the popup 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 remain complete while the popup is closed."
+    },
+    {
+      "id": "multi-select-keyboard-form",
+      "level": "must",
+      "statement": "Preserve popup focus, Arrow/Home/End, typeahead, Space/Enter toggling without close, Escape focus restoration, Tab dismissal, disabled skipping, native repeated-value submission, required validity, external form, and reset."
+    },
+    {
+      "id": "multi-select-responsive",
+      "level": "must",
+      "statement": "Keep Trigger, summaries, and collision-aware popup contained under long localization, narrow widths, zoom, and RTL; do not place removal buttons inside the v1 button Trigger."
+    },
+    {
+      "id": "multi-select-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus multi-select.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Giving Trigger combobox semantics, using selected summary as its name, closing after each toggle, or deriving native options only from an open popup.",
+      "correction": "Preserve the named button/listbox model, persistent toggling, static Item registration, and complete native option contract."
+    },
+    {
+      "mistake": "Adding text entry, arbitrary tag creation, interactive descendants, or application persistence inside the component.",
+      "correction": "Keep predefined noninteractive Items and choose an approved editable higher-layer pattern or record the missing Brick capability."
+    }
+  ],
+  "validation": [
+    "Verify Trigger and listbox names, controlled and uncontrolled arrays and open state, deduplication, zero/one/many summaries and renderValue, popup focus, Arrow/Home/End, typeahead, Space/Enter without close, disabled Items, Escape, Tab, outside activation, and focus restoration.",
+    "Verify read-only on the listbox, Field relationships, hidden multiple-select options and repeated submission, required inline/native validation, external form, reset, groups, indicators, Viewport, scroll buttons, Portal, direction, collision placement, and nested modal behavior.",
+    "Verify all sizes, long summaries and option labels, narrow widths, zoom, RTL, touch targets, light and dark appearance, forced colors, and button-like control alignment."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "multi-select",
+      "versionPolicy": "installed-exact"
+    },
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "listbox",
+      "versionPolicy": "installed-exact"
+    },
+    "field",
+    "form",
+    "select",
+    "combobox",
+    "checkbox-group"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/nav-list.txt

@@ -0,0 +1,130 @@
+# NavList
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: nav-list
+
+# NavList agent guide
+
+## Purpose
+
+Style persistent route navigation with current state, optional section labels, and collapsible grouped content.
+
+## Use when
+
+- A sidebar, drawer, rail, or page region contains a persistent list of destinations, optionally grouped.
+
+## Choose something else when
+
+- Navigation uses top-bar disclosure panels or local tab panels. Use NavigationMenu or Tabs.
+
+## Required composition
+
+- Compose Root > List > Item > Link; use SectionLabel for static groups and add SectionTrigger plus SectionContent only for real collapsible groups. Pass decorative artwork directly to Link or SectionTrigger startIcon so NavList owns its size and alignment. When repeated rows need Dividers, each Item owns its complete row or collapsible Section before the following boundary.
+
+## Rules
+
+- **MUST:** Set current destination state from the route and keep route items as links.
+- **MUST:** Use NavList's section and item anatomy rather than rebuilding rows, badges, icons, and collapse behavior with arbitrary divs.
+- **MUST:** Pass decorative artwork directly to Link or SectionTrigger startIcon; those parts own the wrapper, size, and first-label-line alignment. Do not compensate with consumer margins or transforms.
+- **MUST:** Keep decorative artwork in startIcon/endIcon; when a count or Badge is meaningful content, compose it with the label inside one Brick HStack within Link so the complete row remains one destination.
+- **MUST:** Place a Divider after the complete navigation item or collapsible section it separates; never place it between a SectionTrigger and the SectionContent that trigger controls, and keep repeated boundaries under one consistent layout owner.
+- **MUST:** Let SectionLabel use NavList's size-aware typography and logical leading-column alignment; use the logical row-padding tokens only when navigation rows need independent alignment with a surrounding shell, and do not shift indicators with margins or transforms.
+- **MUST:** Load styles.css or core.css plus nav-list.css.
+
+## Common mistakes
+
+- **Avoid:** Using buttons for routes, wrapping decorative artwork in a second Icon size owner, placing meaningful metadata in aria-hidden icon slots, adding a collapsible trigger that controls no content, placing a Divider between a trigger and the SectionContent that trigger controls, or moving disclosure indicators with positional CSS. **Instead:** Use Link for destinations, pass raw decorative artwork to startIcon, compose meaningful row content inside Link, keep a collapsible Section intact before its boundary, and let SectionLabel own group-title alignment.
+
+## Validation checklist
+
+- Check current, hover, focus, collapsed, expanded, disclosure motion, section-label alignment, complete-group divider placement, long labels, icons, counts, zoom, narrow widths, and RTL.
+- Confirm links and section relationships remain semantic and CSS is loaded.
+
+## Related guidance
+
+- `sidebar`
+- `drawer`
+- `navigation-menu`
+- `link`
+- `divider`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "nav-list",
+  "name": "NavList",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Style persistent route navigation with current state, optional section labels, and collapsible grouped content.",
+  "useWhen": [
+    "A sidebar, drawer, rail, or page region contains a persistent list of destinations, optionally grouped."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Navigation uses top-bar disclosure panels or local tab panels.",
+      "useInstead": "NavigationMenu or Tabs"
+    }
+  ],
+  "composition": [
+    "Compose Root > List > Item > Link; use SectionLabel for static groups and add SectionTrigger plus SectionContent only for real collapsible groups. Pass decorative artwork directly to Link or SectionTrigger startIcon so NavList owns its size and alignment. When repeated rows need Dividers, each Item owns its complete row or collapsible Section before the following boundary."
+  ],
+  "rules": [
+    {
+      "id": "nav-list-current",
+      "level": "must",
+      "statement": "Set current destination state from the route and keep route items as links."
+    },
+    {
+      "id": "nav-list-layout",
+      "level": "must",
+      "statement": "Use NavList's section and item anatomy rather than rebuilding rows, badges, icons, and collapse behavior with arbitrary divs."
+    },
+    {
+      "id": "nav-list-icons",
+      "level": "must",
+      "statement": "Pass decorative artwork directly to Link or SectionTrigger startIcon; those parts own the wrapper, size, and first-label-line alignment. Do not compensate with consumer margins or transforms."
+    },
+    {
+      "id": "nav-list-meaningful-content",
+      "level": "must",
+      "statement": "Keep decorative artwork in startIcon/endIcon; when a count or Badge is meaningful content, compose it with the label inside one Brick HStack within Link so the complete row remains one destination."
+    },
+    {
+      "id": "nav-list-group-boundary",
+      "level": "must",
+      "statement": "Place a Divider after the complete navigation item or collapsible section it separates; never place it between a SectionTrigger and the SectionContent that trigger controls, and keep repeated boundaries under one consistent layout owner."
+    },
+    {
+      "id": "nav-list-shell-alignment",
+      "level": "must",
+      "statement": "Let SectionLabel use NavList's size-aware typography and logical leading-column alignment; use the logical row-padding tokens only when navigation rows need independent alignment with a surrounding shell, and do not shift indicators with margins or transforms."
+    },
+    {
+      "id": "nav-list-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus nav-list.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using buttons for routes, wrapping decorative artwork in a second Icon size owner, placing meaningful metadata in aria-hidden icon slots, adding a collapsible trigger that controls no content, placing a Divider between a trigger and the SectionContent that trigger controls, or moving disclosure indicators with positional CSS.",
+      "correction": "Use Link for destinations, pass raw decorative artwork to startIcon, compose meaningful row content inside Link, keep a collapsible Section intact before its boundary, and let SectionLabel own group-title alignment."
+    }
+  ],
+  "validation": [
+    "Check current, hover, focus, collapsed, expanded, disclosure motion, section-label alignment, complete-group divider placement, long labels, icons, counts, zoom, narrow widths, and RTL.",
+    "Confirm links and section relationships remain semantic and CSS is loaded."
+  ],
+  "related": [
+    "sidebar",
+    "drawer",
+    "navigation-menu",
+    "link",
+    "divider"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/navigation-menu.txt

@@ -0,0 +1,150 @@
+# NavigationMenu
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: navigation-menu
+
+# NavigationMenu agent guide
+
+## Purpose
+
+Present polished disclosure navigation while Atom owns trigger geometry, viewport positioning, focus, keyboard, pointer, and dismissal behavior.
+
+## Use when
+
+- A top-level site or product navigation combines direct links with disclosure panels of related destinations.
+
+## Choose something else when
+
+- The content is an action menu, persistent route rail, mobile drawer, or tab switcher. Use DropdownMenu, NavList, Drawer, or Tabs.
+
+## Required composition
+
+- Compose Root > List > Item containing Link or Trigger plus Content, with Viewport and optional Indicator/Arrow according to the documented anatomy; lay out content with Brick components.
+
+## Rules
+
+- **MUST:** Keep Indicator and Viewport inside the Root-owned coordinate system and let Atom's measured trigger and viewport geometry position them; use documented NavigationMenu tokens and public parts for visual customization.
+- **MUST:** Let the horizontal Viewport use Atom's active-trigger-centered, collision-aware position; do not re-center it on the full Navigation Menu list or page header.
+- **MUST:** Do not invent overlay props such as side, align, sideOffset, or alignOffset; NavigationMenu does not expose the floating-overlay positioning API.
+- **MUST:** Keep contents focused on navigation destinations rather than commands or unrelated marketing panels.
+- **MUST:** Use Link variant=panel with one direct Surface child when one rich destination should own the complete clickable area; let Surface own inset, radius, border, elevation, and background, and keep all composed children non-interactive and concise.
+- **MUST:** Preserve the panel Link's focus fallback; with a direct Surface the ring follows that Surface, and without one the Link itself must remain visibly focused.
+- **MUST:** In React Server Components, import the component subpath as import * as NavigationMenu from @flowstack-ui/brick/navigation-menu; use the legacy root-package runtime object only inside a client-owned module.
+- **MUST:** Load styles.css or core.css plus navigation-menu.css and every child component stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Anchoring the panel or arrow to the logo/page, adding custom hover state that fights Atom, or applying Popover-style offset props that NavigationMenu does not own. **Instead:** Keep Viewport and Indicator under Root, let NavigationMenu own geometry and open state, then customize documented recipes, tokens, and public parts.
+- **Avoid:** Adding use client to an entire Next page only to dereference the legacy NavigationMenu runtime object. **Instead:** Use the RSC-safe module-namespace subpath so only the interactive Navigation Menu parts remain client-owned.
+- **Avoid:** Placing a small link inside a separately clickable-looking Surface, styling NavigationMenu.Link as a duplicate Surface, or nesting a Link or Button inside NavigationMenu.Link. **Instead:** Wrap one direct Surface child with the panel Link so the anchor owns interaction and Surface owns container paint and geometry.
+
+## Validation checklist
+
+- Test hover, click, focus, arrow keys, Escape, outside interaction, links, viewport transitions, active-trigger centering, boundary collision, arrow alignment, zoom, narrow widths, and RTL.
+- Confirm destination semantics, Root-relative geometry, panel focus fallback, documented customization hooks, and CSS delivery.
+- In a React Server Component consumer, confirm the module-namespace form passes a production prerender without promoting the page to use client.
+
+## Related guidance
+
+- `app-bar`
+- `nav-list`
+- `drawer`
+- `dropdown-menu`
+- `link`
+- `interface-composition`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "navigation-menu",
+  "name": "NavigationMenu",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present polished disclosure navigation while Atom owns trigger geometry, viewport positioning, focus, keyboard, pointer, and dismissal behavior.",
+  "useWhen": [
+    "A top-level site or product navigation combines direct links with disclosure panels of related destinations."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content is an action menu, persistent route rail, mobile drawer, or tab switcher.",
+      "useInstead": "DropdownMenu, NavList, Drawer, or Tabs"
+    }
+  ],
+  "composition": [
+    "Compose Root > List > Item containing Link or Trigger plus Content, with Viewport and optional Indicator/Arrow according to the documented anatomy; lay out content with Brick components."
+  ],
+  "rules": [
+    {
+      "id": "navigation-menu-positioning",
+      "level": "must",
+      "statement": "Keep Indicator and Viewport inside the Root-owned coordinate system and let Atom's measured trigger and viewport geometry position them; use documented NavigationMenu tokens and public parts for visual customization."
+    },
+    {
+      "id": "navigation-menu-horizontal-position",
+      "level": "must",
+      "statement": "Let the horizontal Viewport use Atom's active-trigger-centered, collision-aware position; do not re-center it on the full Navigation Menu list or page header."
+    },
+    {
+      "id": "navigation-menu-public-api",
+      "level": "must",
+      "statement": "Do not invent overlay props such as side, align, sideOffset, or alignOffset; NavigationMenu does not expose the floating-overlay positioning API."
+    },
+    {
+      "id": "navigation-menu-destinations",
+      "level": "must",
+      "statement": "Keep contents focused on navigation destinations rather than commands or unrelated marketing panels."
+    },
+    {
+      "id": "navigation-menu-panel-link",
+      "level": "must",
+      "statement": "Use Link variant=panel with one direct Surface child when one rich destination should own the complete clickable area; let Surface own inset, radius, border, elevation, and background, and keep all composed children non-interactive and concise."
+    },
+    {
+      "id": "navigation-menu-panel-focus",
+      "level": "must",
+      "statement": "Preserve the panel Link's focus fallback; with a direct Surface the ring follows that Surface, and without one the Link itself must remain visibly focused."
+    },
+    {
+      "id": "navigation-menu-rsc-import",
+      "level": "must",
+      "statement": "In React Server Components, import the component subpath as import * as NavigationMenu from @flowstack-ui/brick/navigation-menu; use the legacy root-package runtime object only inside a client-owned module."
+    },
+    {
+      "id": "navigation-menu-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus navigation-menu.css and every child component stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Anchoring the panel or arrow to the logo/page, adding custom hover state that fights Atom, or applying Popover-style offset props that NavigationMenu does not own.",
+      "correction": "Keep Viewport and Indicator under Root, let NavigationMenu own geometry and open state, then customize documented recipes, tokens, and public parts."
+    },
+    {
+      "mistake": "Adding use client to an entire Next page only to dereference the legacy NavigationMenu runtime object.",
+      "correction": "Use the RSC-safe module-namespace subpath so only the interactive Navigation Menu parts remain client-owned."
+    },
+    {
+      "mistake": "Placing a small link inside a separately clickable-looking Surface, styling NavigationMenu.Link as a duplicate Surface, or nesting a Link or Button inside NavigationMenu.Link.",
+      "correction": "Wrap one direct Surface child with the panel Link so the anchor owns interaction and Surface owns container paint and geometry."
+    }
+  ],
+  "validation": [
+    "Test hover, click, focus, arrow keys, Escape, outside interaction, links, viewport transitions, active-trigger centering, boundary collision, arrow alignment, zoom, narrow widths, and RTL.",
+    "Confirm destination semantics, Root-relative geometry, panel focus fallback, documented customization hooks, and CSS delivery.",
+    "In a React Server Component consumer, confirm the module-namespace form passes a production prerender without promoting the page to use client."
+  ],
+  "related": [
+    "app-bar",
+    "nav-list",
+    "drawer",
+    "dropdown-menu",
+    "link",
+    "interface-composition"
+  ]
+}
+```