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

package/public/packages/brick/0.1.11/components/password-toggle-field.txt

@@ -0,0 +1,146 @@
+# PasswordToggleField
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: password-toggle-field
+
+# PasswordToggleField agent guide
+
+## Purpose
+
+Present finished native password entry with a named reveal action while Atom owns visibility, type switching, focus retention, Field validation, reset, and submission safety.
+
+## Use when
+
+- A reusable password benefits from an explicit keyboard-accessible reveal action and revealing it is acceptable for the product's privacy model.
+
+## Choose something else when
+
+- The value is ordinary text or a one-time code, or security, observation, or shared-device policy forbids revealing the secret. Use Input, OTPField, or Input with type=password without a reveal control.
+
+## Required composition
+
+- Compose a visible Field.Label, then PasswordToggleField.Root with exactly one Input and Toggle. Let Toggle render Brick's private default Icon or supply decorative product artwork without replacing its action name.
+- Choose the Input-family recipe, size, shape, and width on Root; set autocomplete deliberately and localize Root showLabel and hideLabel as the next available actions.
+
+## Rules
+
+- **MUST:** Include the reveal action only when it is acceptable for the product's security, privacy, observation, recording, and shared-device context.
+- **MUST:** Keep Input as the native value, naming, autocomplete, validity, and submission owner while Atom changes only its owned type between password and text.
+- **MUST:** Provide localized state-aware showLabel and hideLabel values that describe the next action; do not add aria-pressed because the changing action name communicates the available action.
+- **MUST:** Preserve Input focus on Toggle pointer down while keeping Toggle sequentially keyboard reachable by Tab, Enter, and Space.
+- **MUST:** Use visible with onVisibleChange or defaultVisible, preserve Field disabled/read-only/required/invalid behavior, reset uncontrolled visibility, and let Atom restore type=password before native submission.
+- **MUST:** Keep password strength, generation, confirmation, storage, authentication, clipboard, and security policy in the application or service.
+- **MUST:** Load styles.css or core.css plus password-toggle-field.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Adding reveal where policy forbids it, using an unlabeled eye or aria-pressed, moving pointer focus from Input, or submitting while the DOM input remains type=text. **Instead:** Apply the privacy decision first and preserve Atom's state-aware action, focus, reset, validation, and submit-time password restoration.
+- **Avoid:** Writing a second visibility state, replacing Field relationships, or moving password policy into the styled component. **Instead:** Use the complete Root, Input, Toggle, and optional Icon anatomy and keep product policy in the application.
+
+## Validation checklist
+
+- Verify visible Field naming, autocomplete, native props, controlled and uncontrolled visibility, password/text switching, localized Show/Hide actions, decorative Icon state, pointer focus retention, keyboard Tab/Enter/Space, disabled/read-only behavior, custom Toggle composition, and refs.
+- Verify Field ID, label, description, and error inheritance with native overrides; required/invalid inline and native validation; reset to defaultVisible; type=password restoration before submission; external form; and no unintended live-region or aria-pressed semantics.
+- Verify all recipes, sizes, allowed shapes, width modes, long localization, narrow width, zoom, RTL, light and dark appearance, forced colors, hover, focus, invalid, disabled, and read-only paint.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/password-toggle-field`
+- `field`
+- `input`
+- `otp-field`
+- `form`
+- `button`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "password-toggle-field",
+  "name": "PasswordToggleField",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present finished native password entry with a named reveal action while Atom owns visibility, type switching, focus retention, Field validation, reset, and submission safety.",
+  "useWhen": [
+    "A reusable password benefits from an explicit keyboard-accessible reveal action and revealing it is acceptable for the product's privacy model."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value is ordinary text or a one-time code, or security, observation, or shared-device policy forbids revealing the secret.",
+      "useInstead": "Input, OTPField, or Input with type=password without a reveal control"
+    }
+  ],
+  "composition": [
+    "Compose a visible Field.Label, then PasswordToggleField.Root with exactly one Input and Toggle. Let Toggle render Brick's private default Icon or supply decorative product artwork without replacing its action name.",
+    "Choose the Input-family recipe, size, shape, and width on Root; set autocomplete deliberately and localize Root showLabel and hideLabel as the next available actions."
+  ],
+  "rules": [
+    {
+      "id": "password-toggle-policy",
+      "level": "must",
+      "statement": "Include the reveal action only when it is acceptable for the product's security, privacy, observation, recording, and shared-device context."
+    },
+    {
+      "id": "password-toggle-input-owner",
+      "level": "must",
+      "statement": "Keep Input as the native value, naming, autocomplete, validity, and submission owner while Atom changes only its owned type between password and text."
+    },
+    {
+      "id": "password-toggle-action-name",
+      "level": "must",
+      "statement": "Provide localized state-aware showLabel and hideLabel values that describe the next action; do not add aria-pressed because the changing action name communicates the available action."
+    },
+    {
+      "id": "password-toggle-focus",
+      "level": "must",
+      "statement": "Preserve Input focus on Toggle pointer down while keeping Toggle sequentially keyboard reachable by Tab, Enter, and Space."
+    },
+    {
+      "id": "password-toggle-state-form",
+      "level": "must",
+      "statement": "Use visible with onVisibleChange or defaultVisible, preserve Field disabled/read-only/required/invalid behavior, reset uncontrolled visibility, and let Atom restore type=password before native submission."
+    },
+    {
+      "id": "password-toggle-application-policy",
+      "level": "must",
+      "statement": "Keep password strength, generation, confirmation, storage, authentication, clipboard, and security policy in the application or service."
+    },
+    {
+      "id": "password-toggle-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus password-toggle-field.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Adding reveal where policy forbids it, using an unlabeled eye or aria-pressed, moving pointer focus from Input, or submitting while the DOM input remains type=text.",
+      "correction": "Apply the privacy decision first and preserve Atom's state-aware action, focus, reset, validation, and submit-time password restoration."
+    },
+    {
+      "mistake": "Writing a second visibility state, replacing Field relationships, or moving password policy into the styled component.",
+      "correction": "Use the complete Root, Input, Toggle, and optional Icon anatomy and keep product policy in the application."
+    }
+  ],
+  "validation": [
+    "Verify visible Field naming, autocomplete, native props, controlled and uncontrolled visibility, password/text switching, localized Show/Hide actions, decorative Icon state, pointer focus retention, keyboard Tab/Enter/Space, disabled/read-only behavior, custom Toggle composition, and refs.",
+    "Verify Field ID, label, description, and error inheritance with native overrides; required/invalid inline and native validation; reset to defaultVisible; type=password restoration before submission; external form; and no unintended live-region or aria-pressed semantics.",
+    "Verify all recipes, sizes, allowed shapes, width modes, long localization, narrow width, zoom, RTL, light and dark appearance, forced colors, hover, focus, invalid, disabled, and read-only paint."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "password-toggle-field",
+      "versionPolicy": "installed-exact"
+    },
+    "field",
+    "input",
+    "otp-field",
+    "form",
+    "button"
+  ]
+}
+```

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

@@ -0,0 +1,181 @@
+# Popover
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: popover
+
+# Popover agent guide
+
+## Purpose
+
+Present a finished compact click-open interactive panel anchored to a trigger or explicit anchor while Atom owns placement, dismissal, focus, portal, and optional modal behavior.
+
+## Use when
+
+- A trigger needs a small contextual panel for details, filters, or compact editing that belongs near its point of invocation.
+
+## Choose something else when
+
+- The content is noninteractive help, a passive hover preview, a command or option collection, or a larger blocking task. Use Tooltip, HoverCard, Menu, Select or Combobox, or Dialog.
+- The task should enter from a screen edge or remain as persistent page content. Use Drawer or an in-page Brick composition.
+
+## Required composition
+
+- Compose Popover.Root with Popover.Trigger and Popover.Portal; add Popover.Anchor only when positioning must reference an element other than Trigger. Inside Popover.Content, arrange Header with Title and optional Description, Body, Footer, and Close as needed; keep Arrow as a direct Content child.
+- Use density=compact for concise filter and utility panels. When a local Appearance scope owns the trigger, portal into that scope or apply the same Appearance to Content because ordinary portal ancestry does not preserve the local theme boundary.
+
+## Rules
+
+- **MUST:** Use Brick Popover for compact click-open interactive work; choose Menu, Select, or Combobox when the panel's job is command or option selection, and Dialog for a larger blocking workflow.
+- **MUST:** Keep Trigger and portalled Content inside one Root, use Anchor only for a distinct positioning reference, and use the public structure parts instead of recreating panel spacing or hierarchy with private selectors.
+- **MUST:** Give Content an accessible name with one visible Title or an explicit native aria-label or aria-labelledby; add Description or native aria-describedby only when descriptive text is present.
+- **MUST:** Keep the default non-modal behavior for ordinary attached work; set modal only when the compact panel must trap focus, isolate the background, and lock document scrolling.
+- **MUST:** Provide a visible Close when modal is enabled or when outside interaction, Escape, and trigger toggling do not make the dismissal path obvious.
+- **MUST:** Use the owned initial and final focus targets and onInteractOutside preventDefault contract when customization is required; do not replace Atom's focus-out, Escape, completed-interaction, restoration, and nested-layer handling.
+- **MUST:** Use the comfortable default for ordinary contextual work and density=compact for concise filter and utility panels; do not recreate compact rhythm with private selectors.
+- **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:** Style from resolved data-side and available-size variables, keep Arrow as a direct Content child, and preserve its shared border and surface paint instead of assuming requested placement or independently recoloring it.
+- **SHOULD:** Keep the panel compact and verify collision shifts and flips, constrained scrolling, action reachability, zoom, touch input, narrow viewports, and LTR and RTL placement.
+- **MUST:** Load styles.css or core.css plus popover.css.
+
+## Common mistakes
+
+- **Avoid:** Hand-positioning a floating div, using Popover for a menu or tooltip, forcing it modal for every utility panel, or closing it with ad hoc document listeners. **Instead:** Choose by interaction job, use complete Popover anatomy, keep ordinary popovers non-modal, and use the preventable outside-interaction contract.
+- **Avoid:** Assuming portalled Content inherits a nearby Appearance scope or placing Arrow inside an authored viewport wrapper. **Instead:** Make the portal scope explicit and keep Arrow directly under Content so placement and finished surface paint remain intact.
+
+## Validation checklist
+
+- Verify trigger and Content naming, controlled and disabled state, keyboard, pointer, and touch opening, initial focus, Tab behavior, Close, Escape, outside interaction, focus-out dismissal, outside focus destination, and trigger restoration.
+- Verify explicit Anchor positioning, collision shifts and flips at every supported side, LTR and RTL, available-size variables, direct Arrow geometry, constrained scrolling, nested portalled controlled layers, zoom, and narrow viewports.
+- When modal is enabled, verify a visible close path, focus containment, background isolation, scroll lock, and exit presence; check light and dark Appearance on actual portalled Content and required CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/popover`
+- `dialog`
+- `drawer`
+- `dropdown-menu`
+- `select`
+- `combobox`
+- `hover-card`
+- `tooltip`
+- `appearance`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "popover",
+  "name": "Popover",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished compact click-open interactive panel anchored to a trigger or explicit anchor while Atom owns placement, dismissal, focus, portal, and optional modal behavior.",
+  "useWhen": [
+    "A trigger needs a small contextual panel for details, filters, or compact editing that belongs near its point of invocation."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content is noninteractive help, a passive hover preview, a command or option collection, or a larger blocking task.",
+      "useInstead": "Tooltip, HoverCard, Menu, Select or Combobox, or Dialog"
+    },
+    {
+      "condition": "The task should enter from a screen edge or remain as persistent page content.",
+      "useInstead": "Drawer or an in-page Brick composition"
+    }
+  ],
+  "composition": [
+    "Compose Popover.Root with Popover.Trigger and Popover.Portal; add Popover.Anchor only when positioning must reference an element other than Trigger. Inside Popover.Content, arrange Header with Title and optional Description, Body, Footer, and Close as needed; keep Arrow as a direct Content child.",
+    "Use density=compact for concise filter and utility panels. When a local Appearance scope owns the trigger, portal into that scope or apply the same Appearance to Content because ordinary portal ancestry does not preserve the local theme boundary."
+  ],
+  "rules": [
+    {
+      "id": "popover-click-context",
+      "level": "must",
+      "statement": "Use Brick Popover for compact click-open interactive work; choose Menu, Select, or Combobox when the panel's job is command or option selection, and Dialog for a larger blocking workflow."
+    },
+    {
+      "id": "popover-complete-anatomy",
+      "level": "must",
+      "statement": "Keep Trigger and portalled Content inside one Root, use Anchor only for a distinct positioning reference, and use the public structure parts instead of recreating panel spacing or hierarchy with private selectors."
+    },
+    {
+      "id": "popover-accessible-name",
+      "level": "must",
+      "statement": "Give Content an accessible name with one visible Title or an explicit native aria-label or aria-labelledby; add Description or native aria-describedby only when descriptive text is present."
+    },
+    {
+      "id": "popover-modal-choice",
+      "level": "must",
+      "statement": "Keep the default non-modal behavior for ordinary attached work; set modal only when the compact panel must trap focus, isolate the background, and lock document scrolling."
+    },
+    {
+      "id": "popover-visible-close",
+      "level": "must",
+      "statement": "Provide a visible Close when modal is enabled or when outside interaction, Escape, and trigger toggling do not make the dismissal path obvious."
+    },
+    {
+      "id": "popover-focus-dismissal",
+      "level": "must",
+      "statement": "Use the owned initial and final focus targets and onInteractOutside preventDefault contract when customization is required; do not replace Atom's focus-out, Escape, completed-interaction, restoration, and nested-layer handling."
+    },
+    {
+      "id": "popover-density",
+      "level": "must",
+      "statement": "Use the comfortable default for ordinary contextual work and density=compact for concise filter and utility panels; do not recreate compact rhythm with private selectors."
+    },
+    {
+      "id": "popover-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": "popover-positioning-arrow",
+      "level": "must",
+      "statement": "Style from resolved data-side and available-size variables, keep Arrow as a direct Content child, and preserve its shared border and surface paint instead of assuming requested placement or independently recoloring it."
+    },
+    {
+      "id": "popover-responsive",
+      "level": "should",
+      "statement": "Keep the panel compact and verify collision shifts and flips, constrained scrolling, action reachability, zoom, touch input, narrow viewports, and LTR and RTL placement."
+    },
+    {
+      "id": "popover-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus popover.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Hand-positioning a floating div, using Popover for a menu or tooltip, forcing it modal for every utility panel, or closing it with ad hoc document listeners.",
+      "correction": "Choose by interaction job, use complete Popover anatomy, keep ordinary popovers non-modal, and use the preventable outside-interaction contract."
+    },
+    {
+      "mistake": "Assuming portalled Content inherits a nearby Appearance scope or placing Arrow inside an authored viewport wrapper.",
+      "correction": "Make the portal scope explicit and keep Arrow directly under Content so placement and finished surface paint remain intact."
+    }
+  ],
+  "validation": [
+    "Verify trigger and Content naming, controlled and disabled state, keyboard, pointer, and touch opening, initial focus, Tab behavior, Close, Escape, outside interaction, focus-out dismissal, outside focus destination, and trigger restoration.",
+    "Verify explicit Anchor positioning, collision shifts and flips at every supported side, LTR and RTL, available-size variables, direct Arrow geometry, constrained scrolling, nested portalled controlled layers, zoom, and narrow viewports.",
+    "When modal is enabled, verify a visible close path, focus containment, background isolation, scroll lock, and exit presence; check light and dark Appearance on actual portalled Content and required CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "popover",
+      "versionPolicy": "installed-exact"
+    },
+    "dialog",
+    "drawer",
+    "dropdown-menu",
+    "select",
+    "combobox",
+    "hover-card",
+    "tooltip",
+    "appearance"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/progress-circle.txt

@@ -0,0 +1,142 @@
+# ProgressCircle
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: progress-circle
+
+# ProgressCircle agent guide
+
+## Purpose
+
+Present compact circular read-only task progress with Brick-owned SVG ring geometry while Atom Progress owns progressbar semantics, normalized range state, and determinate or indeterminate behavior.
+
+## Use when
+
+- Ongoing measurable or indeterminate work needs compact circular feedback in a card, toolbar, dialog, or other bounded region.
+
+## Choose something else when
+
+- Linear space communicates change more clearly, the value is a stable measurement or user input, stages matter, or the finished layout is loading. Use Progress, the native meter element, Slider, Steps, or Skeleton.
+
+## Required composition
+
+- Give ProgressCircle.Root a concise Label or native accessible name, pass a measurable value or null/omit it for indeterminate work, then compose one Circle with Brick-owned Track before Indicator. Add optional Value and Label outside Circle.
+- Choose size, thickness, cap, and tone on Root. Keep SVG geometry decorative, preserve clockwise motion independent of RTL, and keep application aria-busy state and announcements outside ProgressCircle.
+
+## Rules
+
+- **MUST:** Give Root an accessible task name through Label or native ARIA; Circle, Track, Indicator, and visible Value are decorative or silent and do not replace that name.
+- **MUST:** Use a numeric value only for measurable work, pass null or omit it for indeterminate work, and preserve Atom's truthful min/max normalization, clamping, state, and aria-valuenow behavior.
+- **MUST:** Treat Circle, Track, and Indicator as Brick-owned fixed SVG presentation over Atom Progress context; keep one Circle, order Track before Indicator, and do not override viewBox, radius, circumference, dash array, or dash offset.
+- **MUST:** Keep Root as the only progressbar and announcement path, keep SVG anatomy aria-hidden and unfocusable, and do not make circular progress keyboard adjustable or use it for static measurement.
+- **SHOULD:** Localize optional visible Value and provide aria-valuetext when the numeric range needs domain wording; do not assume the decorative Value changes Root's accessible value text.
+- **MUST:** Keep the ring square, contained within its surrounding region, clockwise in LTR and RTL, label wrapping intact, track visible, and reduced-motion indeterminate state understandable as a static arc.
+- **MUST:** Load styles.css or core.css plus progress-circle.css.
+
+## Common mistakes
+
+- **Avoid:** Using an unlabeled decorative spinner, adding progressbar semantics to SVG, passing zero for unknown work, or reversing the ring in RTL. **Instead:** Name Atom-backed Root, use indeterminate null state, keep Brick SVG silent, and retain clockwise geometry.
+- **Avoid:** Overriding component-owned SVG radius or dash geometry or using ProgressCircle for capacity or input. **Instead:** Use public size/thickness/cap/tone recipes and choose native meter or Slider for other semantic jobs.
+
+## Validation checklist
+
+- Verify Root naming, determinate loading/complete and indeterminate state, aria-valuenow presence/absence, clamping, invalid-range normalization, custom value text, localized visible Value, and Atom state propagation.
+- Verify one Root progressbar, one decorative Circle, Track before Indicator, fixed component-owned geometry, silent/unfocusable SVG, no keyboard interaction, native props, refs, and supported composition.
+- Verify five sizes, three thicknesses, both caps, all tones, square containment, long labels, zoom, clockwise LTR/RTL behavior, track contrast, light/dark appearance, forced colors, and reduced motion.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/progress`
+- `progress`
+- `slider`
+- `skeleton`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "progress-circle",
+  "name": "ProgressCircle",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present compact circular read-only task progress with Brick-owned SVG ring geometry while Atom Progress owns progressbar semantics, normalized range state, and determinate or indeterminate behavior.",
+  "useWhen": [
+    "Ongoing measurable or indeterminate work needs compact circular feedback in a card, toolbar, dialog, or other bounded region."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Linear space communicates change more clearly, the value is a stable measurement or user input, stages matter, or the finished layout is loading.",
+      "useInstead": "Progress, the native meter element, Slider, Steps, or Skeleton"
+    }
+  ],
+  "composition": [
+    "Give ProgressCircle.Root a concise Label or native accessible name, pass a measurable value or null/omit it for indeterminate work, then compose one Circle with Brick-owned Track before Indicator. Add optional Value and Label outside Circle.",
+    "Choose size, thickness, cap, and tone on Root. Keep SVG geometry decorative, preserve clockwise motion independent of RTL, and keep application aria-busy state and announcements outside ProgressCircle."
+  ],
+  "rules": [
+    {
+      "id": "progress-circle-name",
+      "level": "must",
+      "statement": "Give Root an accessible task name through Label or native ARIA; Circle, Track, Indicator, and visible Value are decorative or silent and do not replace that name."
+    },
+    {
+      "id": "progress-circle-state",
+      "level": "must",
+      "statement": "Use a numeric value only for measurable work, pass null or omit it for indeterminate work, and preserve Atom's truthful min/max normalization, clamping, state, and aria-valuenow behavior."
+    },
+    {
+      "id": "progress-circle-brick-anatomy",
+      "level": "must",
+      "statement": "Treat Circle, Track, and Indicator as Brick-owned fixed SVG presentation over Atom Progress context; keep one Circle, order Track before Indicator, and do not override viewBox, radius, circumference, dash array, or dash offset."
+    },
+    {
+      "id": "progress-circle-semantic-owner",
+      "level": "must",
+      "statement": "Keep Root as the only progressbar and announcement path, keep SVG anatomy aria-hidden and unfocusable, and do not make circular progress keyboard adjustable or use it for static measurement."
+    },
+    {
+      "id": "progress-circle-value",
+      "level": "should",
+      "statement": "Localize optional visible Value and provide aria-valuetext when the numeric range needs domain wording; do not assume the decorative Value changes Root's accessible value text."
+    },
+    {
+      "id": "progress-circle-responsive",
+      "level": "must",
+      "statement": "Keep the ring square, contained within its surrounding region, clockwise in LTR and RTL, label wrapping intact, track visible, and reduced-motion indeterminate state understandable as a static arc."
+    },
+    {
+      "id": "progress-circle-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus progress-circle.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using an unlabeled decorative spinner, adding progressbar semantics to SVG, passing zero for unknown work, or reversing the ring in RTL.",
+      "correction": "Name Atom-backed Root, use indeterminate null state, keep Brick SVG silent, and retain clockwise geometry."
+    },
+    {
+      "mistake": "Overriding component-owned SVG radius or dash geometry or using ProgressCircle for capacity or input.",
+      "correction": "Use public size/thickness/cap/tone recipes and choose native meter or Slider for other semantic jobs."
+    }
+  ],
+  "validation": [
+    "Verify Root naming, determinate loading/complete and indeterminate state, aria-valuenow presence/absence, clamping, invalid-range normalization, custom value text, localized visible Value, and Atom state propagation.",
+    "Verify one Root progressbar, one decorative Circle, Track before Indicator, fixed component-owned geometry, silent/unfocusable SVG, no keyboard interaction, native props, refs, and supported composition.",
+    "Verify five sizes, three thicknesses, both caps, all tones, square containment, long labels, zoom, clockwise LTR/RTL behavior, track contrast, light/dark appearance, forced colors, and reduced motion."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "progress",
+      "versionPolicy": "installed-exact"
+    },
+    "progress",
+    "slider",
+    "skeleton"
+  ]
+}
+```

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

@@ -0,0 +1,150 @@
+# Progress
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: progress
+
+# Progress agent guide
+
+## Purpose
+
+Present finished linear read-only task progress for known, unknown, or buffered work while Atom owns progressbar semantics, normalized range state, and the presentation-only Indicator.
+
+## Use when
+
+- Ongoing work such as upload, download, processing, or synchronization needs a linear indication of measurable completion or indeterminate activity.
+
+## Choose something else when
+
+- The value is a stable measurement, users manipulate it, stages rather than amount matter, the finished layout is loading, compact circular presentation fits better, or only a transient result is needed. Use the native meter element, Slider, Steps, Skeleton, ProgressCircle, or Toast.
+
+## Required composition
+
+- Give Progress.Root a concise Label or native accessible name, pass a measurable value or null/omit it for indeterminate work, set a truthful range, and compose optional Value then Track with optional Buffer before Indicator.
+- Choose horizontal or vertical orientation, size, shape, and semantic tone. Keep application region aria-busy state and announcements outside Progress, and provide aria-valuetext or getValueLabel when the numeric range needs domain wording.
+
+## Rules
+
+- **MUST:** Give Root an accessible name identifying the ongoing task through Progress.Label or native ARIA; visible Value does not name the task.
+- **MUST:** Use a current numeric value only for measurable work and pass null or omit value for unknown work so aria-valuenow is absent rather than pretending unknown progress is zero.
+- **MUST:** Supply truthful min and max, understand Atom clamping and invalid-range normalization, and keep optional bufferValue within the same task and range rather than treating it as a second progressbar.
+- **SHOULD:** Provide concise human-readable aria-valuetext or getValueLabel output when the numeric range alone does not communicate meaningful completion; localize visible Value formatting separately.
+- **MUST:** Keep Indicator and Buffer presentation-only, ordered Buffer before Indicator inside Track, and Root as the sole progressbar and announcement owner.
+- **MUST:** Do not make Progress interactive or keyboard adjustable and do not use it for static capacity; choose Slider for input and native meter for stable measurement.
+- **MUST:** Keep horizontal Progress shrinkable, vertical length explicit, label wrapping and value alignment intact, logical fill correct in RTL, and reduced-motion indeterminate state understandable as a static segment.
+- **MUST:** Load styles.css or core.css plus progress.css.
+
+## Common mistakes
+
+- **Avoid:** Passing zero for unknown progress, using Progress for capacity, omitting its task name, or adding progressbar semantics to Indicator. **Instead:** Use indeterminate null state, native meter for stable quantity, name Root, and keep visual parts silent.
+- **Avoid:** Announcing every percent change in another live region or treating tone as the sole status meaning. **Instead:** Keep one semantic progressbar, add independently justified announcements sparingly, and provide textual task or state context.
+
+## Validation checklist
+
+- Verify naming, determinate loading/complete and indeterminate states, aria-valuenow absence, clamping, invalid-range normalization, buffer percentage, data state, explicit aria-valuetext precedence, getValueLabel, and localized visible Value formatting.
+- Verify Root is the only progressbar; Indicator and Buffer are silent; no keyboard interaction exists; all parts remain under Root with Buffer before Indicator; native props, refs, and composition are preserved.
+- Verify both orientations, five sizes, all shapes and tones, narrow width, explicit vertical length, long labels, zoom, RTL logical fill, light/dark appearance, forced colors, reduced motion, and track/indicator contrast.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/progress`
+- `progress-circle`
+- `slider`
+- `toast`
+- `skeleton`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "progress",
+  "name": "Progress",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present finished linear read-only task progress for known, unknown, or buffered work while Atom owns progressbar semantics, normalized range state, and the presentation-only Indicator.",
+  "useWhen": [
+    "Ongoing work such as upload, download, processing, or synchronization needs a linear indication of measurable completion or indeterminate activity."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value is a stable measurement, users manipulate it, stages rather than amount matter, the finished layout is loading, compact circular presentation fits better, or only a transient result is needed.",
+      "useInstead": "the native meter element, Slider, Steps, Skeleton, ProgressCircle, or Toast"
+    }
+  ],
+  "composition": [
+    "Give Progress.Root a concise Label or native accessible name, pass a measurable value or null/omit it for indeterminate work, set a truthful range, and compose optional Value then Track with optional Buffer before Indicator.",
+    "Choose horizontal or vertical orientation, size, shape, and semantic tone. Keep application region aria-busy state and announcements outside Progress, and provide aria-valuetext or getValueLabel when the numeric range needs domain wording."
+  ],
+  "rules": [
+    {
+      "id": "progress-name",
+      "level": "must",
+      "statement": "Give Root an accessible name identifying the ongoing task through Progress.Label or native ARIA; visible Value does not name the task."
+    },
+    {
+      "id": "progress-determinate",
+      "level": "must",
+      "statement": "Use a current numeric value only for measurable work and pass null or omit value for unknown work so aria-valuenow is absent rather than pretending unknown progress is zero."
+    },
+    {
+      "id": "progress-range",
+      "level": "must",
+      "statement": "Supply truthful min and max, understand Atom clamping and invalid-range normalization, and keep optional bufferValue within the same task and range rather than treating it as a second progressbar."
+    },
+    {
+      "id": "progress-value-text",
+      "level": "should",
+      "statement": "Provide concise human-readable aria-valuetext or getValueLabel output when the numeric range alone does not communicate meaningful completion; localize visible Value formatting separately."
+    },
+    {
+      "id": "progress-indicator",
+      "level": "must",
+      "statement": "Keep Indicator and Buffer presentation-only, ordered Buffer before Indicator inside Track, and Root as the sole progressbar and announcement owner."
+    },
+    {
+      "id": "progress-readonly",
+      "level": "must",
+      "statement": "Do not make Progress interactive or keyboard adjustable and do not use it for static capacity; choose Slider for input and native meter for stable measurement."
+    },
+    {
+      "id": "progress-responsive",
+      "level": "must",
+      "statement": "Keep horizontal Progress shrinkable, vertical length explicit, label wrapping and value alignment intact, logical fill correct in RTL, and reduced-motion indeterminate state understandable as a static segment."
+    },
+    {
+      "id": "progress-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus progress.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Passing zero for unknown progress, using Progress for capacity, omitting its task name, or adding progressbar semantics to Indicator.",
+      "correction": "Use indeterminate null state, native meter for stable quantity, name Root, and keep visual parts silent."
+    },
+    {
+      "mistake": "Announcing every percent change in another live region or treating tone as the sole status meaning.",
+      "correction": "Keep one semantic progressbar, add independently justified announcements sparingly, and provide textual task or state context."
+    }
+  ],
+  "validation": [
+    "Verify naming, determinate loading/complete and indeterminate states, aria-valuenow absence, clamping, invalid-range normalization, buffer percentage, data state, explicit aria-valuetext precedence, getValueLabel, and localized visible Value formatting.",
+    "Verify Root is the only progressbar; Indicator and Buffer are silent; no keyboard interaction exists; all parts remain under Root with Buffer before Indicator; native props, refs, and composition are preserved.",
+    "Verify both orientations, five sizes, all shapes and tones, narrow width, explicit vertical length, long labels, zoom, RTL logical fill, light/dark appearance, forced colors, reduced motion, and track/indicator contrast."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "progress",
+      "versionPolicy": "installed-exact"
+    },
+    "progress-circle",
+    "slider",
+    "toast",
+    "skeleton"
+  ]
+}
+```