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

package/public/packages/atom/0.24.0/index.txt

@@ -0,0 +1,89 @@
+# @flowstack-ui/atom@0.24.0
+
+Archive SHA-256: `1fbbbe2b8109f6a056637ebe3e4ceafdebaddad3e64567eb5e43f5b958f35fbb`
+Coverage: 2789/2789 public surfaces; zero failures.
+
+## component
+
+- [Accordion](/packages/atom/0.24.0/components/accordion.txt)
+- [AlertDialog](/packages/atom/0.24.0/components/alert-dialog.txt)
+- [AppBar](/packages/atom/0.24.0/components/app-bar.txt)
+- [AspectRatio](/packages/atom/0.24.0/components/aspect-ratio.txt)
+- [Avatar](/packages/atom/0.24.0/components/avatar.txt)
+- [Badge](/packages/atom/0.24.0/components/badge.txt)
+- [BottomNavigation](/packages/atom/0.24.0/components/bottom-navigation.txt)
+- [Breadcrumb](/packages/atom/0.24.0/components/breadcrumb.txt)
+- [Button](/packages/atom/0.24.0/components/button.txt)
+- [Carousel](/packages/atom/0.24.0/components/carousel.txt)
+- [Checkbox](/packages/atom/0.24.0/components/checkbox.txt)
+- [CheckboxGroup](/packages/atom/0.24.0/components/checkbox-group.txt)
+- [Clipboard](/packages/atom/0.24.0/components/clipboard.txt)
+- [Collapsible](/packages/atom/0.24.0/components/collapsible.txt)
+- [Color Picker](/packages/atom/0.24.0/components/color-picker.txt)
+- [Combobox](/packages/atom/0.24.0/components/combobox.txt)
+- [ContextMenu](/packages/atom/0.24.0/components/context-menu.txt)
+- [DataGrid](/packages/atom/0.24.0/components/data-grid.txt)
+- [Dialog](/packages/atom/0.24.0/components/dialog.txt)
+- [Direction](/packages/atom/0.24.0/components/direction.txt)
+- [Divider](/packages/atom/0.24.0/components/divider.txt)
+- [DragDrop](/packages/atom/0.24.0/components/drag-drop.txt)
+- [Drawer](/packages/atom/0.24.0/components/drawer.txt)
+- [DropdownMenu](/packages/atom/0.24.0/components/dropdown-menu.txt)
+- [Feed](/packages/atom/0.24.0/components/feed.txt)
+- [Field](/packages/atom/0.24.0/components/field.txt)
+- [Fieldset](/packages/atom/0.24.0/components/fieldset.txt)
+- [FileUpload](/packages/atom/0.24.0/components/file-upload.txt)
+- [Form](/packages/atom/0.24.0/components/form.txt)
+- [HoverCard](/packages/atom/0.24.0/components/hover-card.txt)
+- [Image](/packages/atom/0.24.0/components/image.txt)
+- [Input](/packages/atom/0.24.0/components/input.txt)
+- [Label](/packages/atom/0.24.0/components/label.txt)
+- [Link](/packages/atom/0.24.0/components/link.txt)
+- [List](/packages/atom/0.24.0/components/list.txt)
+- [Listbox](/packages/atom/0.24.0/components/listbox.txt)
+- [Menu](/packages/atom/0.24.0/components/menu.txt)
+- [Menubar](/packages/atom/0.24.0/components/menubar.txt)
+- [Modal](/packages/atom/0.24.0/components/modal.txt)
+- [MultiSelect](/packages/atom/0.24.0/components/multi-select.txt)
+- [NavList](/packages/atom/0.24.0/components/nav-list.txt)
+- [NavigationMenu](/packages/atom/0.24.0/components/navigation-menu.txt)
+- [NumberInput](/packages/atom/0.24.0/components/number-input.txt)
+- [OTPField](/packages/atom/0.24.0/components/otp-field.txt)
+- [Pagination](/packages/atom/0.24.0/components/pagination.txt)
+- [PasswordToggleField](/packages/atom/0.24.0/components/password-toggle-field.txt)
+- [Popover](/packages/atom/0.24.0/components/popover.txt)
+- [Pressable](/packages/atom/0.24.0/components/pressable.txt)
+- [Progress](/packages/atom/0.24.0/components/progress.txt)
+- [RadioGroup](/packages/atom/0.24.0/components/radio-group.txt)
+- [Rating](/packages/atom/0.24.0/components/rating.txt)
+- [Reorder](/packages/atom/0.24.0/components/reorder.txt)
+- [ScrollArea](/packages/atom/0.24.0/components/scroll-area.txt)
+- [Select](/packages/atom/0.24.0/components/select.txt)
+- [Sidebar](/packages/atom/0.24.0/components/sidebar.txt)
+- [SkipLink](/packages/atom/0.24.0/components/skip-link.txt)
+- [Slider](/packages/atom/0.24.0/components/slider.txt)
+- [SwipeableItem](/packages/atom/0.24.0/components/swipeable-item.txt)
+- [Switch](/packages/atom/0.24.0/components/switch.txt)
+- [Table](/packages/atom/0.24.0/components/table.txt)
+- [Tabs](/packages/atom/0.24.0/components/tabs.txt)
+- [Textarea](/packages/atom/0.24.0/components/textarea.txt)
+- [Toast](/packages/atom/0.24.0/components/toast.txt)
+- [Toggle](/packages/atom/0.24.0/components/toggle.txt)
+- [ToggleGroup](/packages/atom/0.24.0/components/toggle-group.txt)
+- [Toolbar](/packages/atom/0.24.0/components/toolbar.txt)
+- [Tooltip](/packages/atom/0.24.0/components/tooltip.txt)
+- [Tree](/packages/atom/0.24.0/components/tree.txt)
+- [TreeGrid](/packages/atom/0.24.0/components/tree-grid.txt)
+- [VisuallyHidden](/packages/atom/0.24.0/components/visually-hidden.txt)
+
+## document
+
+- [guides/agent-knowledge](/packages/atom/0.24.0/docs/guides/agent-knowledge.txt)
+- [guides/getting-started](/packages/atom/0.24.0/docs/guides/getting-started.txt)
+- [guides/imports](/packages/atom/0.24.0/docs/guides/imports.txt)
+- [guides/public-api](/packages/atom/0.24.0/docs/guides/public-api.txt)
+
+## guide
+
+- [Atom behavior composition](/packages/atom/0.24.0/guides/behavior-composition.txt)
+- [Atom layer selection](/packages/atom/0.24.0/guides/layer-selection.txt)

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

@@ -0,0 +1,158 @@
+# Accordion
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: accordion
+
+# Accordion agent guide
+
+## Purpose
+
+Present a finished group of related disclosure sections while Atom owns expanded state, headings, linked panels, and keyboard navigation.
+
+## Use when
+
+- Several related sections belong to one scannable group and readers should reveal only the details they need.
+
+## Choose something else when
+
+- Only one independent in-flow region needs disclosure. Use Collapsible.
+- Peer controls switch one shared content view. Use Tabs.
+- Content must layer, dismiss outside, contain focus, or lock document scrolling. Use Dialog, Drawer, or another matching overlay component.
+
+## Required composition
+
+- Compose Root > Item > Header > Trigger with Indicator inside Trigger, then place Content > ContentInner as Header's sibling inside the same Item.
+- Put visible panel padding and ordinary Brick layout in ContentInner so Content remains Atom's measured motion boundary.
+- Choose Header levels from the host document and use Content landmark=false when many regions would make landmark navigation noisy.
+- Use the default decorative Indicator when the standard down-when-closed and up-when-open state cue fits; authored Indicator children may replace only the artwork.
+
+## Rules
+
+- **MUST:** Use Root, Item, Header, Trigger, Content, and ContentInner rather than rebuilding disclosure state, relationships, measurement, or animation lifecycle.
+- **MUST:** Let Accordion Trigger own the finished control recipe; do not compose Button or IconButton into Trigger because competing recipes would own one element.
+- **MUST:** Keep visible padding and panel layout in ContentInner rather than Content so Atom can measure and animate the panel accurately.
+- **MUST:** Choose Header level from the page outline and opt out of optional Content landmarks when the resulting region count would be noisy.
+- **MUST:** Load styles.css or core.css plus accordion.css.
+- **MUST:** Keep grouped trigger corners continuous with the enclosing Root and verify that the complete focus ring remains visible at the first and last group edges.
+- **MUST:** Keep the default Indicator pointing down while closed and up while open in both LTR and RTL; use custom decorative artwork only for a deliberate alternate state language.
+
+## Common mistakes
+
+- **Avoid:** Using Accordion for one disclosure, nesting a finished Button in Trigger, or placing padding directly on Content. **Instead:** Use Collapsible for one region, let Trigger own its visual recipe, and put panel spacing in ContentInner.
+- **Avoid:** Accepting the default heading level or region landmark count without checking the host page. **Instead:** Set Header to the correct document level and use landmark=false when many open panels would create excessive landmarks.
+- **Avoid:** Rounding every Trigger in one outlined group or clipping Root paint so the first and last Trigger focus rings are cut off. **Instead:** Treat Root as the group silhouette, keep interior Trigger edges square, round only exposed group corners, and preserve visible focus outside the group boundary.
+
+## Validation checklist
+
+- Check complete anatomy, unique values, heading order, Trigger names, linked panel relationships, landmark usefulness, and CSS delivery.
+- Test Enter, Space, Home, End, orientation-aware arrows, RTL, disabled and locked-open state, single and multiple modes, and controlled and uncontrolled state.
+- Test initial open, open and close motion, down/up Indicator state, dynamic panel measurement, reduced motion, complete first and last Trigger focus geometry, continuous grouped corners, long labels, narrow widths, zoom, and forced colors.
+
+## Related guidance
+
+- `collapsible`
+- `tabs`
+- `drawer`
+- `stack`
+- `text`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "accordion",
+  "name": "Accordion",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished group of related disclosure sections while Atom owns expanded state, headings, linked panels, and keyboard navigation.",
+  "useWhen": [
+    "Several related sections belong to one scannable group and readers should reveal only the details they need."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Only one independent in-flow region needs disclosure.",
+      "useInstead": "Collapsible"
+    },
+    {
+      "condition": "Peer controls switch one shared content view.",
+      "useInstead": "Tabs"
+    },
+    {
+      "condition": "Content must layer, dismiss outside, contain focus, or lock document scrolling.",
+      "useInstead": "Dialog, Drawer, or another matching overlay component"
+    }
+  ],
+  "composition": [
+    "Compose Root > Item > Header > Trigger with Indicator inside Trigger, then place Content > ContentInner as Header's sibling inside the same Item.",
+    "Put visible panel padding and ordinary Brick layout in ContentInner so Content remains Atom's measured motion boundary.",
+    "Choose Header levels from the host document and use Content landmark=false when many regions would make landmark navigation noisy.",
+    "Use the default decorative Indicator when the standard down-when-closed and up-when-open state cue fits; authored Indicator children may replace only the artwork."
+  ],
+  "rules": [
+    {
+      "id": "accordion-complete-anatomy",
+      "level": "must",
+      "statement": "Use Root, Item, Header, Trigger, Content, and ContentInner rather than rebuilding disclosure state, relationships, measurement, or animation lifecycle."
+    },
+    {
+      "id": "accordion-single-trigger-owner",
+      "level": "must",
+      "statement": "Let Accordion Trigger own the finished control recipe; do not compose Button or IconButton into Trigger because competing recipes would own one element."
+    },
+    {
+      "id": "accordion-content-inner",
+      "level": "must",
+      "statement": "Keep visible padding and panel layout in ContentInner rather than Content so Atom can measure and animate the panel accurately."
+    },
+    {
+      "id": "accordion-heading-landmarks",
+      "level": "must",
+      "statement": "Choose Header level from the page outline and opt out of optional Content landmarks when the resulting region count would be noisy."
+    },
+    {
+      "id": "accordion-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus accordion.css."
+    },
+    {
+      "id": "accordion-grouped-focus-geometry",
+      "level": "must",
+      "statement": "Keep grouped trigger corners continuous with the enclosing Root and verify that the complete focus ring remains visible at the first and last group edges."
+    },
+    {
+      "id": "accordion-indicator-direction",
+      "level": "must",
+      "statement": "Keep the default Indicator pointing down while closed and up while open in both LTR and RTL; use custom decorative artwork only for a deliberate alternate state language."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Accordion for one disclosure, nesting a finished Button in Trigger, or placing padding directly on Content.",
+      "correction": "Use Collapsible for one region, let Trigger own its visual recipe, and put panel spacing in ContentInner."
+    },
+    {
+      "mistake": "Accepting the default heading level or region landmark count without checking the host page.",
+      "correction": "Set Header to the correct document level and use landmark=false when many open panels would create excessive landmarks."
+    },
+    {
+      "mistake": "Rounding every Trigger in one outlined group or clipping Root paint so the first and last Trigger focus rings are cut off.",
+      "correction": "Treat Root as the group silhouette, keep interior Trigger edges square, round only exposed group corners, and preserve visible focus outside the group boundary."
+    }
+  ],
+  "validation": [
+    "Check complete anatomy, unique values, heading order, Trigger names, linked panel relationships, landmark usefulness, and CSS delivery.",
+    "Test Enter, Space, Home, End, orientation-aware arrows, RTL, disabled and locked-open state, single and multiple modes, and controlled and uncontrolled state.",
+    "Test initial open, open and close motion, down/up Indicator state, dynamic panel measurement, reduced motion, complete first and last Trigger focus geometry, continuous grouped corners, long labels, narrow widths, zoom, and forced colors."
+  ],
+  "related": [
+    "collapsible",
+    "tabs",
+    "drawer",
+    "stack",
+    "text"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/alert-dialog.txt

@@ -0,0 +1,175 @@
+# AlertDialog
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: alert-dialog
+
+# AlertDialog agent guide
+
+## Purpose
+
+Present a finished urgent or consequential decision that requires an explicit response, safe initial focus, and non-dismissible backdrop behavior.
+
+## Use when
+
+- A destructive, irreversible, security-sensitive, unsaved-change, or otherwise consequential action requires a safe cancellation choice and an explicit response before continuing.
+
+## Choose something else when
+
+- The surface presents an ordinary form, information, or multi-step task rather than one urgent decision. Use Dialog.
+- The content is an anchored utility panel or passive feedback that does not require a response. Use Popover or Menu, or Toast or Status.
+
+## Required composition
+
+- Compose AlertDialog.Root with AlertDialog.Trigger and AlertDialog.Portal; inside Portal keep AlertDialog.Overlay and AlertDialog.Content as siblings. Inside Content, arrange Header with the required Title and Description, use a short optional Body only when needed, and place Cancel before Action in Footer.
+- Compose Brick Button through Cancel and Action so each response keeps its visual and behavioral role. When a local Appearance scope owns the trigger, portal into that scope or apply the same Appearance to the portalled visual root.
+
+## Rules
+
+- **MUST:** Reserve AlertDialog for one urgent or consequential decision; use Dialog for ordinary tasks, forms, or complex workflows.
+- **MUST:** Keep the alertdialog semantics and provide both an accessible name with visible Title or native labeling and an accessible description with Description or native aria-describedby.
+- **MUST:** Place a visible enabled Cancel before Action and make Cancel the safe initial focus target for consequential actions unless an explicitly safer workflow target is supplied.
+- **MUST:** Do not add backdrop dismissal; require Cancel, Action, or an intentionally permitted Escape path to resolve the decision.
+- **MUST:** Render Overlay and Content as siblings inside Portal and rely on AlertDialog's inherited modal focus, isolation, scroll, and top-layer ownership.
+- **MUST:** Apply destructive or cautionary tone to the Action Button, not to the entire dialog surface, and keep Cancel visually safe and unambiguous.
+- **MUST:** When an Action starts asynchronous validation or work, prevent its automatic close until the application confirms success, preserves errors, and intentionally updates open state.
+- **MUST:** Keep permissions, authorization, persistence, pending state, error recovery, and the actual destructive operation in application code; AlertDialog owns presentation and interaction semantics only.
+- **SHOULD:** Keep the decision concise; use the bounded Body only for essential supporting context and move complex forms or third-party interactive portals to Dialog.
+- **MUST:** When Portal leaves a local Appearance scope, reproduce that scope on the portalled visual root or target a portal container inside it.
+- **MUST:** Load styles.css or core.css plus alert-dialog.css.
+
+## Common mistakes
+
+- **Avoid:** Using AlertDialog for an ordinary form, focusing the destructive Action first, omitting the description, or making the backdrop dismiss the choice. **Instead:** Use Dialog for ordinary tasks; for consequential decisions provide Title, Description, safe Cancel focus, explicit Action, and no backdrop dismissal.
+- **Avoid:** Closing immediately while an asynchronous destructive operation is still pending or styling the whole surface as destructive. **Instead:** Prevent automatic close until application work succeeds and communicate danger through the Action Button and concise decision copy.
+
+## Validation checklist
+
+- Verify alertdialog role, accessible name and description, visible Cancel before Action, safe Cancel initial focus for keyboard, pointer, touch, and programmatic opening, Tab containment, and that backdrop interaction cannot close the layer.
+- Verify Cancel and Action close reasons, prevented asynchronous Action behavior, pending and error recovery, controlled state, intentionally permitted Escape behavior, nested top-layer ownership, scroll lock, background isolation, exit presence, and focus restoration.
+- Verify long-label footer reflow, optional Body overflow, zoom, narrow and short viewports, reduced motion, forced colors, light and dark appearance on portalled Content, and required CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/alert-dialog`
+- `dialog`
+- `button`
+- `popover`
+- `toast`
+- `appearance`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "alert-dialog",
+  "name": "AlertDialog",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished urgent or consequential decision that requires an explicit response, safe initial focus, and non-dismissible backdrop behavior.",
+  "useWhen": [
+    "A destructive, irreversible, security-sensitive, unsaved-change, or otherwise consequential action requires a safe cancellation choice and an explicit response before continuing."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The surface presents an ordinary form, information, or multi-step task rather than one urgent decision.",
+      "useInstead": "Dialog"
+    },
+    {
+      "condition": "The content is an anchored utility panel or passive feedback that does not require a response.",
+      "useInstead": "Popover or Menu, or Toast or Status"
+    }
+  ],
+  "composition": [
+    "Compose AlertDialog.Root with AlertDialog.Trigger and AlertDialog.Portal; inside Portal keep AlertDialog.Overlay and AlertDialog.Content as siblings. Inside Content, arrange Header with the required Title and Description, use a short optional Body only when needed, and place Cancel before Action in Footer.",
+    "Compose Brick Button through Cancel and Action so each response keeps its visual and behavioral role. When a local Appearance scope owns the trigger, portal into that scope or apply the same Appearance to the portalled visual root."
+  ],
+  "rules": [
+    {
+      "id": "alert-dialog-consequential-only",
+      "level": "must",
+      "statement": "Reserve AlertDialog for one urgent or consequential decision; use Dialog for ordinary tasks, forms, or complex workflows."
+    },
+    {
+      "id": "alert-dialog-required-semantics",
+      "level": "must",
+      "statement": "Keep the alertdialog semantics and provide both an accessible name with visible Title or native labeling and an accessible description with Description or native aria-describedby."
+    },
+    {
+      "id": "alert-dialog-safe-cancel",
+      "level": "must",
+      "statement": "Place a visible enabled Cancel before Action and make Cancel the safe initial focus target for consequential actions unless an explicitly safer workflow target is supplied."
+    },
+    {
+      "id": "alert-dialog-no-backdrop-dismissal",
+      "level": "must",
+      "statement": "Do not add backdrop dismissal; require Cancel, Action, or an intentionally permitted Escape path to resolve the decision."
+    },
+    {
+      "id": "alert-dialog-overlay-content-siblings",
+      "level": "must",
+      "statement": "Render Overlay and Content as siblings inside Portal and rely on AlertDialog's inherited modal focus, isolation, scroll, and top-layer ownership."
+    },
+    {
+      "id": "alert-dialog-action-tone",
+      "level": "must",
+      "statement": "Apply destructive or cautionary tone to the Action Button, not to the entire dialog surface, and keep Cancel visually safe and unambiguous."
+    },
+    {
+      "id": "alert-dialog-controlled-action",
+      "level": "must",
+      "statement": "When an Action starts asynchronous validation or work, prevent its automatic close until the application confirms success, preserves errors, and intentionally updates open state."
+    },
+    {
+      "id": "alert-dialog-application-ownership",
+      "level": "must",
+      "statement": "Keep permissions, authorization, persistence, pending state, error recovery, and the actual destructive operation in application code; AlertDialog owns presentation and interaction semantics only."
+    },
+    {
+      "id": "alert-dialog-short-content",
+      "level": "should",
+      "statement": "Keep the decision concise; use the bounded Body only for essential supporting context and move complex forms or third-party interactive portals to Dialog."
+    },
+    {
+      "id": "alert-dialog-theme-scope",
+      "level": "must",
+      "statement": "When Portal leaves a local Appearance scope, reproduce that scope on the portalled visual root or target a portal container inside it."
+    },
+    {
+      "id": "alert-dialog-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus alert-dialog.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using AlertDialog for an ordinary form, focusing the destructive Action first, omitting the description, or making the backdrop dismiss the choice.",
+      "correction": "Use Dialog for ordinary tasks; for consequential decisions provide Title, Description, safe Cancel focus, explicit Action, and no backdrop dismissal."
+    },
+    {
+      "mistake": "Closing immediately while an asynchronous destructive operation is still pending or styling the whole surface as destructive.",
+      "correction": "Prevent automatic close until application work succeeds and communicate danger through the Action Button and concise decision copy."
+    }
+  ],
+  "validation": [
+    "Verify alertdialog role, accessible name and description, visible Cancel before Action, safe Cancel initial focus for keyboard, pointer, touch, and programmatic opening, Tab containment, and that backdrop interaction cannot close the layer.",
+    "Verify Cancel and Action close reasons, prevented asynchronous Action behavior, pending and error recovery, controlled state, intentionally permitted Escape behavior, nested top-layer ownership, scroll lock, background isolation, exit presence, and focus restoration.",
+    "Verify long-label footer reflow, optional Body overflow, zoom, narrow and short viewports, reduced motion, forced colors, light and dark appearance on portalled Content, and required CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "alert-dialog",
+      "versionPolicy": "installed-exact"
+    },
+    "dialog",
+    "button",
+    "popover",
+    "toast",
+    "appearance"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/app-bar.txt

@@ -0,0 +1,134 @@
+# AppBar
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: app-bar
+
+# AppBar agent guide
+
+## Purpose
+
+Provide a finished top surface and one-row start, geometrically centered, and end alignment structure built on Atom AppBar.
+
+## Use when
+
+- A page or application header needs branding, navigation, location, search, or persistent actions on one top surface.
+
+## Choose something else when
+
+- The need is a complete responsive shell, navigation system, or grouped-control keyboard model. Use AppBar composed with Show/Hide, NavigationMenu or NavList, Drawer, and Toolbar as appropriate.
+
+## Required composition
+
+- Root renders a semantic header by default. For a contained full-bleed bar, compose Root > Container > Toolbar inset=none > Start, Center, and End so Container alone owns the page gutter; omit Container only when Toolbar should use the full available width.
+
+## Rules
+
+- **MUST:** Keep AppBar.Root's default header when it owns page or application banner content; use asChild or render only when another semantic or neutral host is intentionally required, such as non-banner chrome inside a Drawer.
+- **MUST:** Place Container between Root and Toolbar when the AppBar surface should remain full bleed while its content uses a bounded measure, and set Toolbar inset to none so Container alone owns the gutter; do not cap Root itself or recreate Toolbar geometry.
+- **MUST:** Do not treat AppBar.Toolbar as an ARIA toolbar; compose Toolbar for grouped-control keyboard behavior.
+- **MUST:** Keep application-specific visibility and wrapping policy outside AppBar and implement it with Brick responsive/layout components.
+- **MUST:** When application layout references an App Bar density measurement, use the matching public comfortable or compact minimum block-size token instead of repeating Brick's value; allow the rendered bar and adjacent content to grow under zoom or enlarged content.
+- **MUST:** Load styles.css or core.css plus app-bar.css.
+
+## Common mistakes
+
+- **Avoid:** Hand-building a header row with div and flex CSS, assuming Root defaults to div, capping the full AppBar surface with application width CSS, double-insetting contained Toolbar content, or expecting AppBar to create menus and breakpoints. **Instead:** Use Root's default header for banner content, place Container around Toolbar with Toolbar inset set to none when Container owns the gutter, and compose the dedicated navigation, layout, and visibility owners inside it.
+
+## Validation checklist
+
+- Check the final Root element and landmark ownership, including non-banner composed hosts.
+- Check geometric centering with unequal side content, truncation, zoom, narrow widths, and RTL.
+- Confirm contained App Bars have one page-gutter owner rather than stacked Container and Toolbar insets.
+- Confirm landmark names, actions, navigation, and modular CSS are complete.
+
+## Related guidance
+
+- `container`
+- `toolbar`
+- `navigation-menu`
+- `nav-list`
+- `drawer`
+- `show`
+- `hide`
+- `stack`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "app-bar",
+  "name": "AppBar",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a finished top surface and one-row start, geometrically centered, and end alignment structure built on Atom AppBar.",
+  "useWhen": [
+    "A page or application header needs branding, navigation, location, search, or persistent actions on one top surface."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The need is a complete responsive shell, navigation system, or grouped-control keyboard model.",
+      "useInstead": "AppBar composed with Show/Hide, NavigationMenu or NavList, Drawer, and Toolbar as appropriate"
+    }
+  ],
+  "composition": [
+    "Root renders a semantic header by default. For a contained full-bleed bar, compose Root > Container > Toolbar inset=none > Start, Center, and End so Container alone owns the page gutter; omit Container only when Toolbar should use the full available width."
+  ],
+  "rules": [
+    {
+      "id": "appbar-root-semantics",
+      "level": "must",
+      "statement": "Keep AppBar.Root's default header when it owns page or application banner content; use asChild or render only when another semantic or neutral host is intentionally required, such as non-banner chrome inside a Drawer."
+    },
+    {
+      "id": "appbar-container-owner",
+      "level": "must",
+      "statement": "Place Container between Root and Toolbar when the AppBar surface should remain full bleed while its content uses a bounded measure, and set Toolbar inset to none so Container alone owns the gutter; do not cap Root itself or recreate Toolbar geometry."
+    },
+    {
+      "id": "appbar-structural-toolbar",
+      "level": "must",
+      "statement": "Do not treat AppBar.Toolbar as an ARIA toolbar; compose Toolbar for grouped-control keyboard behavior."
+    },
+    {
+      "id": "appbar-responsive-owner",
+      "level": "must",
+      "statement": "Keep application-specific visibility and wrapping policy outside AppBar and implement it with Brick responsive/layout components."
+    },
+    {
+      "id": "appbar-density-measurement",
+      "level": "must",
+      "statement": "When application layout references an App Bar density measurement, use the matching public comfortable or compact minimum block-size token instead of repeating Brick's value; allow the rendered bar and adjacent content to grow under zoom or enlarged content."
+    },
+    {
+      "id": "appbar-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus app-bar.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Hand-building a header row with div and flex CSS, assuming Root defaults to div, capping the full AppBar surface with application width CSS, double-insetting contained Toolbar content, or expecting AppBar to create menus and breakpoints.",
+      "correction": "Use Root's default header for banner content, place Container around Toolbar with Toolbar inset set to none when Container owns the gutter, and compose the dedicated navigation, layout, and visibility owners inside it."
+    }
+  ],
+  "validation": [
+    "Check the final Root element and landmark ownership, including non-banner composed hosts.",
+    "Check geometric centering with unequal side content, truncation, zoom, narrow widths, and RTL.",
+    "Confirm contained App Bars have one page-gutter owner rather than stacked Container and Toolbar insets.",
+    "Confirm landmark names, actions, navigation, and modular CSS are complete."
+  ],
+  "related": [
+    "container",
+    "toolbar",
+    "navigation-menu",
+    "nav-list",
+    "drawer",
+    "show",
+    "hide",
+    "stack"
+  ]
+}
+```