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

package/public/packages/brick/0.1.11/index.txt

@@ -0,0 +1,110 @@
+# @flowstack-ui/brick@0.1.11
+
+Archive SHA-256: `2ef92c69dad840583a6b47a854650734e1f18b902cf4a712174a0d95dcab4f1f`
+Coverage: 2594/2594 public surfaces; zero failures.
+
+## component
+
+- [Accordion](/packages/brick/0.1.11/components/accordion.txt)
+- [AlertDialog](/packages/brick/0.1.11/components/alert-dialog.txt)
+- [AppBar](/packages/brick/0.1.11/components/app-bar.txt)
+- [Appearance](/packages/brick/0.1.11/components/appearance.txt)
+- [AspectRatio](/packages/brick/0.1.11/components/aspect-ratio.txt)
+- [Avatar](/packages/brick/0.1.11/components/avatar.txt)
+- [Badge](/packages/brick/0.1.11/components/badge.txt)
+- [Bleed](/packages/brick/0.1.11/components/bleed.txt)
+- [BottomNavigation](/packages/brick/0.1.11/components/bottom-navigation.txt)
+- [Breadcrumb](/packages/brick/0.1.11/components/breadcrumb.txt)
+- [Button](/packages/brick/0.1.11/components/button.txt)
+- [Card](/packages/brick/0.1.11/components/card.txt)
+- [Carousel](/packages/brick/0.1.11/components/carousel.txt)
+- [Checkbox](/packages/brick/0.1.11/components/checkbox.txt)
+- [Checkbox Group](/packages/brick/0.1.11/components/checkbox-group.txt)
+- [Chip](/packages/brick/0.1.11/components/chip.txt)
+- [Code](/packages/brick/0.1.11/components/code.txt)
+- [Code Block](/packages/brick/0.1.11/components/code-block.txt)
+- [Collapsible](/packages/brick/0.1.11/components/collapsible.txt)
+- [Color Picker](/packages/brick/0.1.11/components/color-picker.txt)
+- [Color Swatch](/packages/brick/0.1.11/components/color-swatch.txt)
+- [Combobox](/packages/brick/0.1.11/components/combobox.txt)
+- [Container](/packages/brick/0.1.11/components/container.txt)
+- [ContextMenu](/packages/brick/0.1.11/components/context-menu.txt)
+- [Data Grid](/packages/brick/0.1.11/components/data-grid.txt)
+- [Data List](/packages/brick/0.1.11/components/data-list.txt)
+- [Dialog](/packages/brick/0.1.11/components/dialog.txt)
+- [Divider](/packages/brick/0.1.11/components/divider.txt)
+- [Drawer](/packages/brick/0.1.11/components/drawer.txt)
+- [DropdownMenu](/packages/brick/0.1.11/components/dropdown-menu.txt)
+- [Feed](/packages/brick/0.1.11/components/feed.txt)
+- [Field](/packages/brick/0.1.11/components/field.txt)
+- [Fieldset](/packages/brick/0.1.11/components/fieldset.txt)
+- [FileUpload](/packages/brick/0.1.11/components/file-upload.txt)
+- [Form](/packages/brick/0.1.11/components/form.txt)
+- [Frame](/packages/brick/0.1.11/components/frame.txt)
+- [Grid](/packages/brick/0.1.11/components/grid.txt)
+- [Group](/packages/brick/0.1.11/components/group.txt)
+- [Hide](/packages/brick/0.1.11/components/hide.txt)
+- [HoverCard](/packages/brick/0.1.11/components/hover-card.txt)
+- [Icon](/packages/brick/0.1.11/components/icon.txt)
+- [IconButton](/packages/brick/0.1.11/components/icon-button.txt)
+- [Image](/packages/brick/0.1.11/components/image.txt)
+- [Input](/packages/brick/0.1.11/components/input.txt)
+- [Link](/packages/brick/0.1.11/components/link.txt)
+- [Link Box](/packages/brick/0.1.11/components/link-box.txt)
+- [List](/packages/brick/0.1.11/components/list.txt)
+- [Menubar](/packages/brick/0.1.11/components/menubar.txt)
+- [MultiSelect](/packages/brick/0.1.11/components/multi-select.txt)
+- [NavList](/packages/brick/0.1.11/components/nav-list.txt)
+- [NavigationMenu](/packages/brick/0.1.11/components/navigation-menu.txt)
+- [NotificationBadge](/packages/brick/0.1.11/components/notification-badge.txt)
+- [NumberInput](/packages/brick/0.1.11/components/number-input.txt)
+- [OTPField](/packages/brick/0.1.11/components/otp-field.txt)
+- [Pagination](/packages/brick/0.1.11/components/pagination.txt)
+- [PasswordToggleField](/packages/brick/0.1.11/components/password-toggle-field.txt)
+- [Popover](/packages/brick/0.1.11/components/popover.txt)
+- [Progress](/packages/brick/0.1.11/components/progress.txt)
+- [ProgressCircle](/packages/brick/0.1.11/components/progress-circle.txt)
+- [RadioGroup](/packages/brick/0.1.11/components/radio-group.txt)
+- [Rating](/packages/brick/0.1.11/components/rating.txt)
+- [Reorderable List](/packages/brick/0.1.11/components/reorderable-list.txt)
+- [ScrollArea](/packages/brick/0.1.11/components/scroll-area.txt)
+- [Section](/packages/brick/0.1.11/components/section.txt)
+- [SegmentGroup](/packages/brick/0.1.11/components/segment-group.txt)
+- [Select](/packages/brick/0.1.11/components/select.txt)
+- [Show](/packages/brick/0.1.11/components/show.txt)
+- [Sidebar](/packages/brick/0.1.11/components/sidebar.txt)
+- [Skeleton](/packages/brick/0.1.11/components/skeleton.txt)
+- [SkipLink](/packages/brick/0.1.11/components/skip-link.txt)
+- [Slider](/packages/brick/0.1.11/components/slider.txt)
+- [Stack](/packages/brick/0.1.11/components/stack.txt)
+- [Status](/packages/brick/0.1.11/components/status.txt)
+- [Surface](/packages/brick/0.1.11/components/surface.txt)
+- [SwipeableItem](/packages/brick/0.1.11/components/swipeable-item.txt)
+- [Switch](/packages/brick/0.1.11/components/switch.txt)
+- [Table](/packages/brick/0.1.11/components/table.txt)
+- [Tabs](/packages/brick/0.1.11/components/tabs.txt)
+- [Text](/packages/brick/0.1.11/components/text.txt)
+- [Textarea](/packages/brick/0.1.11/components/textarea.txt)
+- [Toast](/packages/brick/0.1.11/components/toast.txt)
+- [Toggle](/packages/brick/0.1.11/components/toggle.txt)
+- [ToggleGroup](/packages/brick/0.1.11/components/toggle-group.txt)
+- [Toolbar](/packages/brick/0.1.11/components/toolbar.txt)
+- [Tooltip](/packages/brick/0.1.11/components/tooltip.txt)
+- [Tree](/packages/brick/0.1.11/components/tree.txt)
+- [TreeGrid](/packages/brick/0.1.11/components/tree-grid.txt)
+- [VisuallyHidden](/packages/brick/0.1.11/components/visually-hidden.txt)
+- [ZStack](/packages/brick/0.1.11/components/z-stack.txt)
+
+## document
+
+- [guides/agent-knowledge](/packages/brick/0.1.11/docs/guides/agent-knowledge.txt)
+- [guides/appearance-and-tokens](/packages/brick/0.1.11/docs/guides/appearance-and-tokens.txt)
+- [guides/browser-support](/packages/brick/0.1.11/docs/guides/browser-support.txt)
+- [guides/control-sizing](/packages/brick/0.1.11/docs/guides/control-sizing.txt)
+- [guides/installation](/packages/brick/0.1.11/docs/guides/installation.txt)
+- [guides/theme-contract](/packages/brick/0.1.11/docs/guides/theme-contract.txt)
+
+## guide
+
+- [Brick interface composition](/packages/brick/0.1.11/guides/interface-composition.txt)
+- [Brick layer selection](/packages/brick/0.1.11/guides/layer-selection.txt)

package/public/packages/colors/0.1.1/docs/agent-knowledge.txt

@@ -0,0 +1,63 @@
+# Public document: agent-knowledge
+
+Source: @flowstack-ui/colors@0.1.1
+
+# Colors Agent Knowledge
+
+Colors publishes deterministic, versioned guidance for agents that need to
+choose and use its color operations. The guidance describes operations, not UI
+components: Colors has no component, DOM, Theme, or application ownership.
+
+## Discovery
+
+Start with these package exports:
+
+- `@flowstack-ui/colors/agents/manifest.json` lists the package guide, all six
+  operation owners, and the coverage report.
+- `@flowstack-ui/colors/agents/coverage.json` proves that all 76 named public
+  API surfaces are classified and all six operation owners are routed.
+- `@flowstack-ui/colors/agents/colors-system.json` is the structured selection,
+  boundary, and validation guide.
+- `@flowstack-ui/colors/agents/colors-system.md` is deterministic Markdown
+  generated from that same JSON guide.
+
+The two direct `colors-system` subpaths remain stable compatibility routes.
+Wildcard `agents/*.json` and `agents/*.md` exports let consumers follow future
+manifest entries without adding a package export for every artifact.
+
+## Operation owners
+
+The manifest routes these six public operation families:
+
+1. `color-inspection` parses, validates, and normalizes color input.
+2. `color-conversion` converts color spaces and maps output gamut explicitly.
+3. `color-measurement` calculates contrast and perceptual color difference.
+4. `named-palette-reference` reads the shipped raw reference palettes.
+5. `palette-candidate` generates and reviews deterministic palette candidates.
+6. `color-provenance` records serializable engine and operation provenance.
+
+The package catalog at `agents/catalog.json` is the source classification used
+to build the published reports. It must exactly match `src/index.ts`: stale,
+missing, duplicate, or extra classifications fail the repository gate.
+
+## Boundaries
+
+Agent guidance must preserve the same public boundary as the runtime:
+
+- Colors produces deterministic color records, measurements, references, and
+  candidate data. It does not assign semantic Theme roles.
+- A generated candidate is not an approved palette. Human review remains
+  explicit, and Theme mapping and application/brand approval happen later.
+- Native CSS color handling is appropriate when no parsing, normalization,
+  conversion, measurement, provenance, or candidate artifact is required.
+- Component selection, rendering, focus, interaction, and accessibility remain
+  outside this package.
+
+## Verification
+
+Run `npm run agents:check` after editing source guidance or routing. Run
+`npm run agents:build` to regenerate Markdown and `dist/agents`, then run the
+complete `npm run check:repository` gate. The release gate packs the package,
+installs that exact archive in a clean consumer, resolves every manifest
+artifact, compares the installed 76-surface report with the installed type and
+runtime exports, and exercises all six operation families.

package/public/packages/colors/0.1.1/docs/architecture.txt

@@ -0,0 +1,74 @@
+# Public document: architecture
+
+Source: @flowstack-ui/colors@0.1.1
+
+# Colors Architecture
+
+Status: **Batch 7.4 candidate interchange qualified**
+
+Colors owns framework-independent color science and deterministic palette
+candidate generation. Theme owns semantic mapping, exact editable theme
+definitions, Brick contract validation, and final static artifacts.
+
+## Dependency direction
+
+```text
+Creative or human intent
+  -> @flowstack-ui/colors candidate
+  -> @flowstack-ui/theme definition
+  -> @flowstack-ui/brick semantic contract
+```
+
+The arrows describe artifact flow, not runtime dependencies. Colors does not
+import Theme or Brick. A deployed application does not require Colors merely
+because its CSS originated from a candidate.
+
+The qualified color engine is pinned exactly. Its version is part of every
+provenance record, so a consumer install cannot silently change math while
+claiming the same engine evidence.
+
+## Candidate rules
+
+- Inputs and outputs are serializable and deterministic.
+- Multiple named seeds are first-class.
+- A seed has an explicit interface, neutral, or decorative profile.
+- Exact preservation is the default; adaptation requires an explicit bounded
+  policy and complete diagnostics.
+- Light and dark are generated and validated independently.
+- Every accessibility claim names and measures the exact pair.
+- Existing named palettes and requested 12-step scales remain available as
+  raw/reference output without automatic Theme qualification.
+
+`flowstack.colors-candidate.v1` is the finalized serialized interchange
+boundary for the first release. Generation produces an `unreviewed` result;
+`reviewPaletteCandidate()` records an explicit human `accepted`, `edited`, or
+`rejected` decision without changing its measurements. An accepted family has
+passed only its declared Colors measurements, carries no semantic Brick
+mapping, and cannot be called a theme. See
+`palette-generation.md` [source reference: palette-generation.md].
+
+Batch 7.4 proved the boundary without coupling the packages: Theme reads the
+candidate JSON, imports selected families as project palettes, expands explicit
+semantic assignments against the installed Brick contract, and produces an
+ordinary editable Theme. One seven-family candidate passed all 152 compiled
+Brick contrast evaluations and the complete 80-route, four-profile rendered
+catalog. That evidence validates the interchange; it does not preapprove future
+candidates.
+
+## Color record
+
+`flowstack.color-record.v1` is the stable Batch 7.2 evidence envelope. It
+preserves the exact source, a structured supported-space color, an sRGB
+fallback with explicit gamut diagnostics, and deterministic provenance.
+
+Conversions do not silently map gamut. Gamut mapping is a separate named
+operation. Contrast maps to exact sRGB and rejects alpha without a backdrop.
+See `color-foundations.md` [source reference: color-foundations.md] for the API contract.
+
+## Reference palettes
+
+Thirty-one standalone FLOWSTACK named families are available through
+`getNamedPalette()`. They use FLOWSTACK seeds and the same deterministic
+decorative generator exposed to consumers, with no external palette package.
+Every result is marked `raw-reference`, preserving useful light/dark 12-step
+output without claiming that its values satisfy Theme or Brick.

package/public/packages/colors/0.1.1/docs/color-foundations.txt

@@ -0,0 +1,128 @@
+# Public document: color-foundations
+
+Source: @flowstack-ui/colors@0.1.1
+
+# Color Foundations
+
+Status: **Batch 7.2 implemented; achromatic qualification extended in Batch 7.3**
+
+## Inputs
+
+Every operation accepts either a CSS color string, a direct Design Tokens
+color value, or a wrapped Design Tokens token:
+
+```ts
+"oklch(70% 0.2 45)"
+
+{
+  colorSpace: "display-p3",
+  components: [1, 0.5, 0],
+  alpha: 1,
+  hex: "#ff7600",
+}
+
+{
+  $type: "color",
+  $value: {
+    colorSpace: "oklch",
+    components: [0.7, 0.2, 45],
+  },
+}
+```
+
+Supported structured spaces are sRGB, linear sRGB, Display P3, A98 RGB,
+ProPhoto RGB, Rec. 2020, XYZ D50 and D65, Lab, LCH, Oklab, and OKLCH. Common
+CSS formats such as named colors, hex, RGB, HSL, and HWB normalize into one of
+those spaces.
+
+When an achromatic color is converted to LCH or OKLCH, its physically
+meaningless missing hue is serialized canonically as `0`. This keeps black,
+white, and gray outputs finite and deterministic without changing the color.
+
+The Design Tokens `none` component is rejected because it requires a separate
+interpolation context. Non-finite components, invalid alpha, invalid optional
+hex fallback, unsupported spaces, and malformed CSS produce stable diagnostic
+codes.
+
+## Operations
+
+### Parse and validate
+
+`parseColor(input)` returns a plain `StructuredColor` or throws a
+`FlowstackColorError`. `validateColor(input)` accepts unknown input and returns
+the same structured color or serializable diagnostics without throwing for
+expected input errors.
+
+### Normalize
+
+`normalizeColor(input)` returns `flowstack.color-record.v1` with:
+
+- a cloned exact source representation;
+- the parsed color in its supported source space;
+- a bounded sRGB color and six- or eight-digit lowercase hex fallback;
+- whether gamut mapping occurred, its method, and deltaEOK change; and
+- deterministic package, engine, operation, version, and parameter provenance.
+
+The optional Design Tokens `hex` field is retained as source metadata. It is
+not treated as authoritative over the structured color components, so the
+record may produce a different qualified sRGB fallback.
+
+### Convert
+
+`convertColor(input, targetSpace)` converts coordinates without gamut mapping.
+Out-of-gamut components remain out of range so the caller cannot confuse
+conversion with adaptation. The result includes source, target, converted
+color, and provenance.
+
+### Map gamut
+
+`mapColorToGamut(input, targetGamut)` supports sRGB, Display P3, and Rec. 2020.
+It leaves in-gamut values unchanged and otherwise uses CSS Color 4 OKLCH local
+MINDE mapping with a deltaEOK just-noticeable threshold of `0.02`. The result
+states whether mapping occurred and how far the mapped color moved.
+
+Floating-point noise up to `1 × 10⁻¹²` at a gamut boundary is clamped before
+public components are returned. Larger out-of-range values remain visible.
+
+### Contrast
+
+`calculateContrast(foreground, background)` maps both colors to sRGB and
+returns the unrounded WCAG 2 relative-luminance ratio plus named 4.5:1 and 3:1
+pass gates. `contrastRatio()` returns only that exact ratio.
+
+Contrast currently requires two opaque colors. A translucent foreground or
+background fails with `alpha-requires-backdrop`; Colors will not invent a
+background and publish a misleading accessibility result.
+
+### Difference
+
+`calculateColorDifference(first, second, method)` supports deltaEOK by default
+and CIEDE2000 when explicitly requested. `colorDifference()` returns only the
+number. DeltaEOK reports the current `0.02` just-noticeable threshold;
+CIEDE2000 does not claim one package-wide threshold.
+
+Difference currently requires opaque colors because alpha is not a color-space
+coordinate and its visual effect depends on a backdrop.
+
+## Provenance and determinism
+
+Every report uses `flowstack.color-provenance.v1`. It records:
+
+- `@flowstack-ui/colors` and its version;
+- Culori and its qualified version;
+- the named operation and operation-contract version; and
+- sorted serializable parameters.
+
+No timestamp, environment path, random value, mutable class instance, or
+private workspace data enters a record. The same input and dependency version
+therefore produce byte-stable JSON.
+
+## What this does not prove
+
+These functions prove color math and declared pair relationships. They do not
+prove that a color has the right semantic meaning, that a palette is visually
+coherent, or that a complete Brick theme passes. Batch 7.3 candidate generation
+is documented in `palette-generation.md` [source reference: palette-generation.md]. Batch 7.4
+qualified the serialized Colors-to-Theme boundary and one complete generated
+fixture; every future candidate still needs its own semantic and rendered
+qualification.

package/public/packages/colors/0.1.1/docs/compatibility.txt

@@ -0,0 +1,75 @@
+# Public document: compatibility
+
+Source: @flowstack-ui/colors@0.1.1
+
+# Compatibility and upgrades
+
+Colors has three separate compatibility boundaries. Keeping them separate
+prevents a package upgrade from silently changing an accepted product theme.
+
+## Package API
+
+The npm package follows semantic versioning. Version `0.1.0` requires Node.js
+22 or newer and exposes ESM JavaScript and TypeScript declarations from the
+root package entry point.
+
+Before `1.0.0`, a minor version may contain a breaking API or candidate-shape
+change when the changelog and migration guidance identify it. Patch releases
+must remain compatible with the documented 0.1 API unless they close a safety
+or correctness defect that cannot be fixed compatibly.
+
+## Serialized schemas
+
+These identifiers version serialized meaning independently of npm:
+
+- `flowstack.colors-request.v1`;
+- `flowstack.colors-candidate.v1`;
+- `flowstack.color-record.v1`; and
+- `flowstack.color-provenance.v1`.
+
+Additive optional evidence may remain within version 1. Removing required
+fields, changing existing field meaning, or making a formerly valid document
+invalid requires a new schema identifier or an explicit migration.
+
+Theme consumes the candidate JSON shape, not Colors package code. A reviewed
+0.1 candidate therefore remains editable and compilable without rerunning its
+generator merely because Colors is upgraded.
+
+## Algorithm and exact values
+
+Candidate provenance records the Colors producer version, exact color-engine
+version, operation contract, and `flowstack-palette-v1` algorithm. Version
+0.1.0 pins the qualified engine to `4.0.2`; consumer installation cannot
+silently substitute another engine while claiming that provenance.
+
+Identical normalized input, package version, engine version, and algorithm
+parameters produce byte-identical output. A future intentional generation
+model receives a new algorithm identifier. A correctness fix may change exact
+candidate values only with a package version change, changelog entry, golden
+fixture update, Theme contract requalification, and rendered evidence when the
+change affects UI output.
+
+Do not automatically regenerate an accepted project theme during dependency
+installation. Review the candidate diff, record a new human decision, scaffold
+an ordinary Theme again, and repeat the relevant contract and product gates.
+
+Version `0.1.1` adds `textHover` and `textPressed` to generated interface
+appearances and adjusts the default generated text values. Existing reviewed
+candidate files remain valid inputs because serialized consumers must accept
+additive role evidence. Regenerating the same request intentionally produces
+different exact interface text values under producer version `0.1.1`, so
+review that candidate diff and repeat Theme qualification before adopting it.
+
+## Moving from qualification builds
+
+`0.1.0` is the first public release. Private `0.0.0` qualification checkouts
+should replace Git or workspace references with the exact registry version:
+
+```bash
+npm install --save-dev @flowstack-ui/colors@0.1.0
+```
+
+The finalized candidate uses `review`, plural `referenceBackgrounds`, and the
+neutral `textInverse` role. Regenerate experimental pre-0.1 candidate files,
+review them explicitly, and qualify their resulting Theme rather than editing
+old experimental envelopes in place.

package/public/packages/colors/0.1.1/docs/dependency-qualification.txt

@@ -0,0 +1,117 @@
+# Public document: dependency-qualification
+
+Source: @flowstack-ui/colors@0.1.1
+
+# Color-Science Dependency Qualification
+
+Status: **Culori adopted for implementation**
+
+Date: August 12, 2026
+
+## Decision
+
+Use Culori as the focused color-science implementation dependency. Batch 7.2
+now imports it from shipped color-foundation source, so it is a runtime package
+dependency while its separate declarations remain development-only.
+
+Color.js remains a high-quality reference implementation and comparison tool,
+not a package dependency.
+
+The package must not restore the archived handwritten sRGB, OKLab, OKLCH, and
+gamut implementation. FLOWSTACK owns its contracts and tests; the qualified
+library owns the underlying conversion machinery.
+
+## Candidates
+
+| Candidate | Version | License | Transitive runtime dependencies | Installed size in the proof |
+| --- | ---: | --- | ---: | ---: |
+| Culori | 4.0.2 | MIT | 0 | 1,584 KiB |
+| Color.js | 0.7.1 | MIT | 0 | 16,628 KiB |
+
+Culori does not bundle TypeScript declarations. `@types/culori` 4.0.1, also
+MIT with no dependencies, adds 796 KiB during development. Colors exposes its
+own public types and does not leak Culori types through its API. Its type
+declarations require the otherwise optional `mode` argument to `toGamut`, so
+the adapter supplies that argument explicitly and retains a compilation gate
+for declaration drift.
+
+## Method
+
+The temporary comparison used Node.js 22.23.1 and npm 10.9.8. It evaluated:
+
+- common CSS inputs: hex, modern RGB with alpha, HSL, OKLCH, Display P3, and
+  `transparent`;
+- an 11 × 11 × 11 sRGB grid round-tripped through OKLCH;
+- difficult high-chroma OKLCH colors and Display P3 primaries/mixtures;
+- a 3,672-color OKLCH sweep with lightness `0.10–0.95`, chroma `0.05–0.45`,
+  and hue every 15 degrees;
+- exact WCAG 2 relative-luminance contrast vectors used by Theme; and
+- 10,000 deterministic OKLCH-to-sRGB gamut mappings as a directional timing
+  check.
+
+Color.js's `css` method served as the independent JavaScript comparison for
+gamut mapping. CSS Color 4 identifies Color.js as an experimental
+implementation of binary-search local-MINDE mapping and specifies deltaEOK
+`0.02` as one just-noticeable difference in OKLCH.
+
+## Results
+
+- Both candidates parsed every required input format.
+- Culori's maximum sRGB → OKLCH → sRGB channel error was
+  `4.16 × 10⁻¹⁴`; Color.js measured `3.62 × 10⁻¹⁴`.
+- The focused difficult-color corpus produced 10 identical 8-bit hex results
+  out of 11. Its maximum difference was deltaEOK `0.0000913`.
+- Culori may return destination channels a few floating-point units outside
+  `[0, 1]` (for example `-2.8 × 10⁻¹⁴`) at an exact gamut boundary. Colors must
+  normalize this numerical epsilon before exposing exact sRGB components; its
+  qualified hex serializer already produces the expected bounded value.
+- Across the 3,672-color sweep, 3,586 outputs (97.7%) serialized to the same
+  8-bit hex. The maximum deltaEOK was `0.000284`, about 70 times smaller than
+  the `0.02` just-noticeable threshold. The maximum individual sRGB channel
+  difference was `0.00270`; the two cases with the largest numeric differences
+  still serialized to the same hex.
+- Culori exactly reproduced the tested WCAG values used by Theme, including
+  `21:1` for black/white, `4.478089453577214:1` for `#777777`/white, and
+  `3.9984767707539985:1` for red/white. Color.js showed small implementation
+  differences on saturated red and orange.
+- In the non-authoritative 10,000-map timing run, Culori completed in about
+  110 ms and Color.js in about 246 ms on the same machine and process model.
+  Performance was not the deciding gate, but it did not expose a Culori cost.
+
+## Why Culori
+
+Culori meets the required parsing, conversion, round-trip, gamut, contrast,
+determinism, and licensing boundary with materially less package weight. Its
+plain-object functional API also fits a serializable build-time library better
+than exposing mutable color class instances.
+
+The small gamut differences are far below the current just-noticeable
+threshold and are covered by permanent difficult-hue fixtures. Color.js would
+be the fallback if later evidence exposes a Culori defect or if FLOWSTACK needs
+an algorithm Culori cannot qualify.
+
+## Permanent gates
+
+The repository retains tests for:
+
+- required parser formats;
+- sRGB/OKLCH round-trip precision;
+- difficult hue and Display P3 gamut mapping;
+- deterministic repeated results;
+- exact WCAG contrast values; and
+- TypeScript declaration compatibility.
+
+Requalify this decision before accepting:
+
+- a Culori major version;
+- a material CSS Color 4 gamut-algorithm change;
+- a new output gamut or HDR color space;
+- a change in the Theme contrast authority; or
+- any fixture drift not explained by an explicitly adopted algorithm change.
+
+## Sources
+
+- [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/)
+- [WCAG 2.2](https://www.w3.org/TR/WCAG22/)
+- [Culori API](https://culorijs.org/api/)
+- [Color.js gamut mapping](https://colorjs.io/docs/gamut-mapping)

package/public/packages/colors/0.1.1/docs/installation.txt

@@ -0,0 +1,48 @@
+# Public document: installation
+
+Source: @flowstack-ui/colors@0.1.1
+
+# Installation
+
+Colors is build-time tooling for generating and reviewing palette candidates.
+Install it as a development dependency:
+
+```bash
+npm install --save-dev @flowstack-ui/colors
+```
+
+Version 0.1 requires Node.js 22 or newer and ships ESM JavaScript plus strict
+TypeScript declarations.
+
+```ts
+import {
+  COLOR_GENERATION_REQUEST_SCHEMA,
+  generatePaletteCandidate,
+  reviewPaletteCandidate,
+} from "@flowstack-ui/colors";
+
+const candidate = generatePaletteCandidate({
+  $schema: COLOR_GENERATION_REQUEST_SCHEMA,
+  seeds: [{ id: "brand", color: "#3157d5", profile: "interface" }],
+});
+
+const reviewed = reviewPaletteCandidate(candidate, {
+  status: "accepted",
+  notes: "Approved for Theme mapping.",
+});
+```
+
+Write the reviewed object as JSON when passing it to Theme. The candidate file
+is the integration boundary; neither package depends on the other.
+
+## Runtime boundary
+
+Colors does not import React, access the DOM, inject CSS, load fonts, or depend
+on Brick or Theme. Its only runtime dependency is the exactly qualified color
+engine used by its functions.
+
+Applications should generate candidates during development or a build step and
+ship Theme's compiled CSS. Do not import Colors from application client code
+unless the application deliberately intends to bundle a color editor or other
+future runtime tool. Installing Colors does not itself add code to a browser
+bundle.