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

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

@@ -0,0 +1,143 @@
+# Appearance
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: appearance
+
+# Appearance agent guide
+
+## Purpose
+
+Apply one explicit light, dark, or inherited semantic-token boundary without adding visual paint, layout, state, or a required client provider.
+
+## Use when
+
+- A local region must use a different supported appearance from its DOM ancestor.
+- An existing Brick host should receive an appearance boundary without another wrapper.
+- Portalled visual roots must explicitly reproduce the appearance scope they left.
+
+## Choose something else when
+
+- The whole application is selecting or persisting a user preference. Use Application or framework appearance bootstrap on the document root.
+- The region needs neutral background paint, inset, border, radius, or elevation. Use Surface as the one direct child of Appearance when both paint and an appearance boundary are needed.
+
+## Required composition
+
+- Pass exactly one existing DOM or Brick host to Appearance. That host may contain any number of descendants, must accept DOM props and a ref, and receives the boundary without a wrapper. For a portal, target a container inside the intended scope or apply Appearance to every portalled visual root.
+
+## Rules
+
+- **MUST:** Use Appearance only with a theme that supplies a complete appearance-dependent color and shadow assignment for the requested explicit appearance.
+- **MUST:** Do not recolor descendants component by component after establishing the scope.
+- **MUST:** Pass exactly one existing host. Do not pass a Fragment, string, or multiple direct children; author a semantic host explicitly when the region does not already have one.
+- **MUST:** Do not assume a portal inherits the trigger's local CSS scope; preserve it with a scoped container or explicit portalled root scopes.
+- **MUST:** Keep saved preference, toggle state, storage, and pre-paint scripts in the application or framework layer.
+- **MUST:** Load styles.css or styles/core.css plus appearance.css.
+
+## Common mistakes
+
+- **Avoid:** Wrapping every region in Surface only to switch between light and dark. **Instead:** Use Appearance; make Surface its direct child only when visual paint is also part of the job.
+- **Avoid:** Defining branded light values only on the outer theme root. **Instead:** Repeat the complete light semantic assignment at the theme's explicit light re-entry selector.
+- **Avoid:** Opening a Drawer or Menu from a dark section and expecting its body portal to remain dark. **Instead:** Use a scoped Portal container or apply the intended Appearance to its portalled visual roots.
+
+## Validation checklist
+
+- Inspect the DOM and confirm Appearance adds no wrapper while preserving child classes, styles, native props, handlers, component slot, and refs.
+- Test light to dark to light and dark to light to dark with representative controls and interaction states.
+- Test every used portalled family, native controls, contrast, forced colors, SSR, and hydration.
+
+## Related guidance
+
+- `surface`
+- `app-bar`
+- `drawer`
+- `tabs`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "appearance",
+  "name": "Appearance",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Apply one explicit light, dark, or inherited semantic-token boundary without adding visual paint, layout, state, or a required client provider.",
+  "useWhen": [
+    "A local region must use a different supported appearance from its DOM ancestor.",
+    "An existing Brick host should receive an appearance boundary without another wrapper.",
+    "Portalled visual roots must explicitly reproduce the appearance scope they left."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The whole application is selecting or persisting a user preference.",
+      "useInstead": "Application or framework appearance bootstrap on the document root"
+    },
+    {
+      "condition": "The region needs neutral background paint, inset, border, radius, or elevation.",
+      "useInstead": "Surface as the one direct child of Appearance when both paint and an appearance boundary are needed"
+    }
+  ],
+  "composition": [
+    "Pass exactly one existing DOM or Brick host to Appearance. That host may contain any number of descendants, must accept DOM props and a ref, and receives the boundary without a wrapper. For a portal, target a container inside the intended scope or apply Appearance to every portalled visual root."
+  ],
+  "rules": [
+    {
+      "id": "appearance-complete-theme",
+      "level": "must",
+      "statement": "Use Appearance only with a theme that supplies a complete appearance-dependent color and shadow assignment for the requested explicit appearance."
+    },
+    {
+      "id": "appearance-no-recoloring",
+      "level": "must",
+      "statement": "Do not recolor descendants component by component after establishing the scope."
+    },
+    {
+      "id": "appearance-single-host",
+      "level": "must",
+      "statement": "Pass exactly one existing host. Do not pass a Fragment, string, or multiple direct children; author a semantic host explicitly when the region does not already have one."
+    },
+    {
+      "id": "appearance-portal-explicit",
+      "level": "must",
+      "statement": "Do not assume a portal inherits the trigger's local CSS scope; preserve it with a scoped container or explicit portalled root scopes."
+    },
+    {
+      "id": "appearance-no-runtime-policy",
+      "level": "must",
+      "statement": "Keep saved preference, toggle state, storage, and pre-paint scripts in the application or framework layer."
+    },
+    {
+      "id": "appearance-css",
+      "level": "must",
+      "statement": "Load styles.css or styles/core.css plus appearance.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Wrapping every region in Surface only to switch between light and dark.",
+      "correction": "Use Appearance; make Surface its direct child only when visual paint is also part of the job."
+    },
+    {
+      "mistake": "Defining branded light values only on the outer theme root.",
+      "correction": "Repeat the complete light semantic assignment at the theme's explicit light re-entry selector."
+    },
+    {
+      "mistake": "Opening a Drawer or Menu from a dark section and expecting its body portal to remain dark.",
+      "correction": "Use a scoped Portal container or apply the intended Appearance to its portalled visual roots."
+    }
+  ],
+  "validation": [
+    "Inspect the DOM and confirm Appearance adds no wrapper while preserving child classes, styles, native props, handlers, component slot, and refs.",
+    "Test light to dark to light and dark to light to dark with representative controls and interaction states.",
+    "Test every used portalled family, native controls, contrast, forced colors, SSR, and hydration."
+  ],
+  "related": [
+    "surface",
+    "app-bar",
+    "drawer",
+    "tabs"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/aspect-ratio.txt

@@ -0,0 +1,136 @@
+# AspectRatio
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: aspect-ratio
+
+# AspectRatio agent guide
+
+## Purpose
+
+Reserve finished stable width-to-height geometry and optional neutral frame paint for media, embeds, or placeholders while Atom owns the authoritative ratio and children retain all semantics and interaction.
+
+## Use when
+
+- An image, video, iframe, preview, placeholder, or authored content region needs a predictable box before content loads or a consistent clipped frame.
+
+## Choose something else when
+
+- Intrinsic dimensions already provide the intended layout, image loading and fallback behavior is needed, the content is a general panel, or a loading placeholder owns the job. Use the semantic native media element, Image, Surface, or Skeleton.
+
+## Required composition
+
+- Wrap one semantic content region in AspectRatio.Root, pass a finite positive width-divided-by-height ratio when 16/9 is not correct, and choose plain, subtle, or outline plus radius and overflow. Size a child explicitly when it should fill the reserved box.
+- Keep image alt text, iframe title, media controls and captions, focus, loading, and interaction on the child. Choose overflow=visible or an inset child focus treatment whenever clipping would hide focus.
+
+## Rules
+
+- **MUST:** Treat Root as geometry and optional frame paint only; do not assign it media roles, accessible names, loading state, focus, or interaction owned by its child.
+- **MUST:** Express ratio as width divided by height and pass a finite positive number; understand that Atom normalizes zero, negative, NaN, and infinite values to 16/9.
+- **MUST:** Give contained images appropriate alt text, iframes descriptive titles, and interactive media its native controls, keyboard behavior, captions, and visible focus.
+- **MUST:** Do not override style.aspectRatio because Atom's ratio prop remains authoritative; use Brick variant, radius, overflow, and public frame variables for visual customization.
+- **MUST:** Keep Root contained at available inline size and author responsive ratio changes outside the scalar prop; verify clipped children, full radius, narrow widths, and focus at zoom rather than assuming Root stretches or crops them.
+- **MUST:** Load styles.css or core.css plus aspect-ratio.css and the stylesheet for every rendered child component.
+
+## Common mistakes
+
+- **Avoid:** Treating AspectRatio as Image or video, moving the child's name to Root, passing height divided by width, or relying on invalid ratio input. **Instead:** Keep Root structural, retain semantic native children, and pass a deliberate positive width/height ratio.
+- **Avoid:** Assuming Root sizes or object-fits the child or clipping a child's focus ring. **Instead:** Size and fit the child explicitly and use visible overflow or inset focus when interaction reaches the frame edge.
+
+## Validation checklist
+
+- Verify default, square, portrait, and wide ratios; invalid normalization; reserved layout before loading; all variants/radii/overflow modes; authoritative ratio with other consumer styles preserved; native props; refs; and composition.
+- Inspect final DOM for no Root role or ARIA and correct child image, iframe, video, keyboard, focus, captions, and loading semantics.
+- Verify narrow width, responsive external CSS, zoom, full-radius geometry, clipping, RTL neutrality, light/dark appearance, forced colors, and focus visibility for interactive children.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/aspect-ratio`
+- `image`
+- `surface`
+- `skeleton`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "aspect-ratio",
+  "name": "AspectRatio",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Reserve finished stable width-to-height geometry and optional neutral frame paint for media, embeds, or placeholders while Atom owns the authoritative ratio and children retain all semantics and interaction.",
+  "useWhen": [
+    "An image, video, iframe, preview, placeholder, or authored content region needs a predictable box before content loads or a consistent clipped frame."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Intrinsic dimensions already provide the intended layout, image loading and fallback behavior is needed, the content is a general panel, or a loading placeholder owns the job.",
+      "useInstead": "the semantic native media element, Image, Surface, or Skeleton"
+    }
+  ],
+  "composition": [
+    "Wrap one semantic content region in AspectRatio.Root, pass a finite positive width-divided-by-height ratio when 16/9 is not correct, and choose plain, subtle, or outline plus radius and overflow. Size a child explicitly when it should fill the reserved box.",
+    "Keep image alt text, iframe title, media controls and captions, focus, loading, and interaction on the child. Choose overflow=visible or an inset child focus treatment whenever clipping would hide focus."
+  ],
+  "rules": [
+    {
+      "id": "aspect-ratio-geometry-only",
+      "level": "must",
+      "statement": "Treat Root as geometry and optional frame paint only; do not assign it media roles, accessible names, loading state, focus, or interaction owned by its child."
+    },
+    {
+      "id": "aspect-ratio-value",
+      "level": "must",
+      "statement": "Express ratio as width divided by height and pass a finite positive number; understand that Atom normalizes zero, negative, NaN, and infinite values to 16/9."
+    },
+    {
+      "id": "aspect-ratio-semantics",
+      "level": "must",
+      "statement": "Give contained images appropriate alt text, iframes descriptive titles, and interactive media its native controls, keyboard behavior, captions, and visible focus."
+    },
+    {
+      "id": "aspect-ratio-authority",
+      "level": "must",
+      "statement": "Do not override style.aspectRatio because Atom's ratio prop remains authoritative; use Brick variant, radius, overflow, and public frame variables for visual customization."
+    },
+    {
+      "id": "aspect-ratio-responsive",
+      "level": "must",
+      "statement": "Keep Root contained at available inline size and author responsive ratio changes outside the scalar prop; verify clipped children, full radius, narrow widths, and focus at zoom rather than assuming Root stretches or crops them."
+    },
+    {
+      "id": "aspect-ratio-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus aspect-ratio.css and the stylesheet for every rendered child component."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Treating AspectRatio as Image or video, moving the child's name to Root, passing height divided by width, or relying on invalid ratio input.",
+      "correction": "Keep Root structural, retain semantic native children, and pass a deliberate positive width/height ratio."
+    },
+    {
+      "mistake": "Assuming Root sizes or object-fits the child or clipping a child's focus ring.",
+      "correction": "Size and fit the child explicitly and use visible overflow or inset focus when interaction reaches the frame edge."
+    }
+  ],
+  "validation": [
+    "Verify default, square, portrait, and wide ratios; invalid normalization; reserved layout before loading; all variants/radii/overflow modes; authoritative ratio with other consumer styles preserved; native props; refs; and composition.",
+    "Inspect final DOM for no Root role or ARIA and correct child image, iframe, video, keyboard, focus, captions, and loading semantics.",
+    "Verify narrow width, responsive external CSS, zoom, full-radius geometry, clipping, RTL neutrality, light/dark appearance, forced colors, and focus visibility for interactive children."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "aspect-ratio",
+      "versionPolicy": "installed-exact"
+    },
+    "image",
+    "surface",
+    "skeleton"
+  ]
+}
+```

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

@@ -0,0 +1,152 @@
+# Avatar
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: avatar
+
+# Avatar agent guide
+
+## Purpose
+
+Present one compact person or entity identity with a finished fixed-square image/fallback recipe and optional visual status ring.
+
+## Use when
+
+- A person, organization, workspace, or other named entity needs a compact fixed-square identity token with explicit fallback content.
+
+## Choose something else when
+
+- A larger editorial or profile portrait needs an authored aspect ratio, crop, focal position, or responsive measure. Use Image.
+- A count or dot must attach to an identity. Use NotificationBadge composed around Avatar.
+
+## Required composition
+
+- Provide explicit alt and fallback; keep Avatar passive and let an owning Button or Link provide interaction, focus, and the functional accessible name.
+- Keep visible identity or status text nearby when the image or status ring alone would be ambiguous or consequential.
+
+## Rules
+
+- **MUST:** Use Avatar for compact fixed-square identity presentation, not generic media or larger editorial portraits.
+- **MUST:** Decide alt from context: preserve meaningful identity when Avatar adds it, and use alt="" only when adjacent text or the owning control already supplies the same identity.
+- **MUST:** Pass the same source to the Atom-backed Root and Image path, preserve idle/loading/loaded/error state, and keep explicit fallback content durable through missing, changed, delayed, and failed images.
+- **MUST:** Supply explicit localized fallback content; do not generate initials or infer identity from a filename.
+- **MUST:** Keep Avatar passive; wrap it with the public Button or Link that owns any action or destination.
+- **MUST:** Provide separate accessible status text when a status ring communicates meaningful availability.
+- **MUST:** Choose the nearest named Avatar size, including 2xl through 5xl for larger square profile identities, instead of overriding --brick-avatar-size inline; use Image for authored non-square portrait media.
+- **MUST:** Load styles.css or core.css plus avatar.css.
+
+## Common mistakes
+
+- **Avoid:** Forcing a large 4:5 profile portrait into Avatar, using alt="" merely because a name appears somewhere nearby, generating fallback initials inside Brick, or treating the status ring as an announcement. **Instead:** Use Image for authored portrait media, make the alt decision from the specific context, provide explicit fallback content, and keep meaningful status in text.
+
+## Validation checklist
+
+- Check missing, idle, loading, loaded, changed-source, and error paths; delayed fallback timing; fixed square size; crop; informative and decorative naming; passive semantics; nearby identity/status text; light/dark/forced colors; zoom; and RTL.
+- Confirm a named Avatar size is used, CSS is loaded, and any owning Button, Link, or NotificationBadge preserves its own public contract.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/avatar`
+- `image`
+- `button`
+- `link`
+- `notification-badge`
+- `badge`
+- `status`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "avatar",
+  "name": "Avatar",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present one compact person or entity identity with a finished fixed-square image/fallback recipe and optional visual status ring.",
+  "useWhen": [
+    "A person, organization, workspace, or other named entity needs a compact fixed-square identity token with explicit fallback content."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A larger editorial or profile portrait needs an authored aspect ratio, crop, focal position, or responsive measure.",
+      "useInstead": "Image"
+    },
+    {
+      "condition": "A count or dot must attach to an identity.",
+      "useInstead": "NotificationBadge composed around Avatar"
+    }
+  ],
+  "composition": [
+    "Provide explicit alt and fallback; keep Avatar passive and let an owning Button or Link provide interaction, focus, and the functional accessible name.",
+    "Keep visible identity or status text nearby when the image or status ring alone would be ambiguous or consequential."
+  ],
+  "rules": [
+    {
+      "id": "avatar-compact-identity",
+      "level": "must",
+      "statement": "Use Avatar for compact fixed-square identity presentation, not generic media or larger editorial portraits."
+    },
+    {
+      "id": "avatar-alt-context",
+      "level": "must",
+      "statement": "Decide alt from context: preserve meaningful identity when Avatar adds it, and use alt=\"\" only when adjacent text or the owning control already supplies the same identity."
+    },
+    {
+      "id": "avatar-source-state",
+      "level": "must",
+      "statement": "Pass the same source to the Atom-backed Root and Image path, preserve idle/loading/loaded/error state, and keep explicit fallback content durable through missing, changed, delayed, and failed images."
+    },
+    {
+      "id": "avatar-explicit-fallback",
+      "level": "must",
+      "statement": "Supply explicit localized fallback content; do not generate initials or infer identity from a filename."
+    },
+    {
+      "id": "avatar-passive",
+      "level": "must",
+      "statement": "Keep Avatar passive; wrap it with the public Button or Link that owns any action or destination."
+    },
+    {
+      "id": "avatar-status-text",
+      "level": "must",
+      "statement": "Provide separate accessible status text when a status ring communicates meaningful availability."
+    },
+    {
+      "id": "avatar-named-size",
+      "level": "must",
+      "statement": "Choose the nearest named Avatar size, including 2xl through 5xl for larger square profile identities, instead of overriding --brick-avatar-size inline; use Image for authored non-square portrait media."
+    },
+    {
+      "id": "avatar-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus avatar.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Forcing a large 4:5 profile portrait into Avatar, using alt=\"\" merely because a name appears somewhere nearby, generating fallback initials inside Brick, or treating the status ring as an announcement.",
+      "correction": "Use Image for authored portrait media, make the alt decision from the specific context, provide explicit fallback content, and keep meaningful status in text."
+    }
+  ],
+  "validation": [
+    "Check missing, idle, loading, loaded, changed-source, and error paths; delayed fallback timing; fixed square size; crop; informative and decorative naming; passive semantics; nearby identity/status text; light/dark/forced colors; zoom; and RTL.",
+    "Confirm a named Avatar size is used, CSS is loaded, and any owning Button, Link, or NotificationBadge preserves its own public contract."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "avatar",
+      "versionPolicy": "installed-exact"
+    },
+    "image",
+    "button",
+    "link",
+    "notification-badge",
+    "badge",
+    "status"
+  ]
+}
+```

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

@@ -0,0 +1,139 @@
+# Badge
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: badge
+
+# Badge agent guide
+
+## Purpose
+
+Present a short passive category, status, metadata label, or compact circular passive marker with a complete Brick visual recipe.
+
+## Use when
+
+- A short non-interactive label needs a bounded visual treatment that remains understandable in its surrounding content.
+
+## Choose something else when
+
+- The element performs an action, changes state, announces a live update, or displays a count attached to another element. Use Button, an appropriate control, a live-status pattern, or NotificationBadge.
+
+## Required composition
+
+- Place the short label directly in Badge; when an icon or separately styled Text is necessary, keep those children passive and let Badge own their spacing and foreground. Use size=xl with shape=circle only for a deliberate passive empty-state icon well.
+
+## Rules
+
+- **MUST:** Keep Badge passive; do not add click, press, selection, or disclosure behavior to it.
+- **MUST:** Keep every count or status understandable from visible text or its owning control without relying on color, shape, or placement, and never assume Badge announces changes or joins a sibling control name automatically.
+- **MUST:** When composing Text inside Badge, use tone=inherit unless that Text intentionally communicates a separate semantic tone, so the Badge recipe continues to own foreground contrast.
+- **MUST:** Rely on Badge's gap for an icon and label instead of literal whitespace, wrapper margins, or positional offsets.
+- **MUST:** Keep the label short and atomic; Badge stays on one line, so use ordinary Text for explanatory or prose-length content.
+- **MUST:** Use shape=circle only for one compact passive icon or single character with nearby context; use IconButton for an action and Status for a dot-and-label state.
+- **MUST:** Load styles.css or core.css plus badge.css.
+
+## Common mistakes
+
+- **Avoid:** Nesting default-tone Text in a Badge, manually spacing an icon and label, using a padded rounded Badge for a circular verification marker, or using Badge as an eyebrow solely for uppercase styling. **Instead:** Use plain Badge text when possible, tone=inherit for nested Text, Badge's own gap for children, shape=circle for a passive icon marker, and Text variant=eyebrow for a short editorial heading introduction.
+
+## Validation checklist
+
+- Check label brevity, one-line atomic sizing, passive semantics, child spacing, foreground contrast for every variant and tone, zoom, forced colors, and RTL.
+- Confirm nested Text inherits the Badge foreground, circle geometry remains exactly square, and CSS is loaded.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/badge`
+- `text`
+- `icon`
+- `notification-badge`
+- `button`
+- `status`
+- `z-stack`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "badge",
+  "name": "Badge",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a short passive category, status, metadata label, or compact circular passive marker with a complete Brick visual recipe.",
+  "useWhen": [
+    "A short non-interactive label needs a bounded visual treatment that remains understandable in its surrounding content."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The element performs an action, changes state, announces a live update, or displays a count attached to another element.",
+      "useInstead": "Button, an appropriate control, a live-status pattern, or NotificationBadge"
+    }
+  ],
+  "composition": [
+    "Place the short label directly in Badge; when an icon or separately styled Text is necessary, keep those children passive and let Badge own their spacing and foreground. Use size=xl with shape=circle only for a deliberate passive empty-state icon well."
+  ],
+  "rules": [
+    {
+      "id": "badge-passive",
+      "level": "must",
+      "statement": "Keep Badge passive; do not add click, press, selection, or disclosure behavior to it."
+    },
+    {
+      "id": "badge-context-live",
+      "level": "must",
+      "statement": "Keep every count or status understandable from visible text or its owning control without relying on color, shape, or placement, and never assume Badge announces changes or joins a sibling control name automatically."
+    },
+    {
+      "id": "badge-inherited-text",
+      "level": "must",
+      "statement": "When composing Text inside Badge, use tone=inherit unless that Text intentionally communicates a separate semantic tone, so the Badge recipe continues to own foreground contrast."
+    },
+    {
+      "id": "badge-child-spacing",
+      "level": "must",
+      "statement": "Rely on Badge's gap for an icon and label instead of literal whitespace, wrapper margins, or positional offsets."
+    },
+    {
+      "id": "badge-short-label",
+      "level": "must",
+      "statement": "Keep the label short and atomic; Badge stays on one line, so use ordinary Text for explanatory or prose-length content."
+    },
+    {
+      "id": "badge-circle",
+      "level": "must",
+      "statement": "Use shape=circle only for one compact passive icon or single character with nearby context; use IconButton for an action and Status for a dot-and-label state."
+    },
+    {
+      "id": "badge-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus badge.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Nesting default-tone Text in a Badge, manually spacing an icon and label, using a padded rounded Badge for a circular verification marker, or using Badge as an eyebrow solely for uppercase styling.",
+      "correction": "Use plain Badge text when possible, tone=inherit for nested Text, Badge's own gap for children, shape=circle for a passive icon marker, and Text variant=eyebrow for a short editorial heading introduction."
+    }
+  ],
+  "validation": [
+    "Check label brevity, one-line atomic sizing, passive semantics, child spacing, foreground contrast for every variant and tone, zoom, forced colors, and RTL.",
+    "Confirm nested Text inherits the Badge foreground, circle geometry remains exactly square, and CSS is loaded."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "badge",
+      "versionPolicy": "installed-exact"
+    },
+    "text",
+    "icon",
+    "notification-badge",
+    "button",
+    "status",
+    "z-stack"
+  ]
+}
+```

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

@@ -0,0 +1,104 @@
+# Bleed
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: bleed
+
+# Bleed agent guide
+
+## Purpose
+
+Extend authored content across a parent inset with responsive logical spacing.
+
+## Use when
+
+- Edge media or artwork must cross its immediate container padding.
+
+## Choose something else when
+
+- The problem is size, paint, ordinary arrangement, or unrelated positioning. Use Frame, Surface, Stack, Grid, or application layout.
+
+## Required composition
+
+- Place Bleed inside the owner of the inset it crosses and keep meaningful media or content semantics on the authored child.
+
+## Rules
+
+- **MUST:** Use public non-negative spacing values; Bleed owns the negative conversion.
+- **SHOULD:** Prefer inline or block for an axis and directional props only for a genuine one-edge exception.
+- **MUST:** Verify narrow widths, RTL, zoom, and horizontal overflow.
+
+## Common mistakes
+
+- **Avoid:** Using Bleed to fix an incorrect Container measure. **Instead:** Correct the owning layout first.
+
+## Validation checklist
+
+- Confirm the intended edges align with the parent's outer boundary.
+- Confirm the page does not gain horizontal overflow.
+
+## Related guidance
+
+- `frame`
+- `stack`
+- `surface`
+- `image`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "bleed",
+  "name": "Bleed",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Extend authored content across a parent inset with responsive logical spacing.",
+  "useWhen": [
+    "Edge media or artwork must cross its immediate container padding."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The problem is size, paint, ordinary arrangement, or unrelated positioning.",
+      "useInstead": "Frame, Surface, Stack, Grid, or application layout"
+    }
+  ],
+  "composition": [
+    "Place Bleed inside the owner of the inset it crosses and keep meaningful media or content semantics on the authored child."
+  ],
+  "rules": [
+    {
+      "id": "bleed-positive-input",
+      "level": "must",
+      "statement": "Use public non-negative spacing values; Bleed owns the negative conversion."
+    },
+    {
+      "id": "bleed-axis-first",
+      "level": "should",
+      "statement": "Prefer inline or block for an axis and directional props only for a genuine one-edge exception."
+    },
+    {
+      "id": "bleed-verify",
+      "level": "must",
+      "statement": "Verify narrow widths, RTL, zoom, and horizontal overflow."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Bleed to fix an incorrect Container measure.",
+      "correction": "Correct the owning layout first."
+    }
+  ],
+  "validation": [
+    "Confirm the intended edges align with the parent's outer boundary.",
+    "Confirm the page does not gain horizontal overflow."
+  ],
+  "related": [
+    "frame",
+    "stack",
+    "surface",
+    "image"
+  ]
+}
+```