banhaten 0.3.0 → 0.5.0

package/docs/design-system/direction-and-localization.md

@@ -1,23 +1,23 @@
-# Direction and Localization
-
-Banhaten is Arabic and English-first, but text direction and language are separate contracts. Components resolve direction from an explicit `dir`, `DirectionProvider`, the nearest valid `[dir]` ancestor, or the document root—in that order. Direction changes layout, icon mirroring, and keyboard geometry; it never selects translated UI or accessibility copy.
-
-Use a request-known direction provider for server rendering so the server markup, hydration snapshot, and first paint agree:
-
-```tsx
-import { DirectionProvider } from "@/hooks/use-direction"
-import {
-  arabicPaginationMessages,
-  Pagination,
-} from "@/components/ui/pagination"
-
-<DirectionProvider dir="rtl">
-  <Pagination messages={arabicPaginationMessages} />
-</DirectionProvider>
-```
-
-`DirectionProvider dir="rtl"` works equally well with English, Arabic, Hebrew, Persian, or Urdu. Choose a component's `messages` catalog from the product locale, or pass its direct label props. The exported Arabic catalogs are conveniences, not RTL defaults.
-
-Without an explicit prop or provider, server output uses a stable LTR snapshot. After hydration, one shared subscription per document synchronizes consumers with the nearest nested boundary or document root. This avoids hydration mismatches and per-component document observers. For an RTL first paint, provide the request-known direction during SSR.
-
-Use logical CSS properties (`start`, `end`, `margin-inline`, `padding-inline`) and `dir="auto"` for user-authored copy. Test mixed-language content, punctuation, numbers, icon mirroring, arrow-key behavior, focus order, portal content, and screen-reader names in every supported direction and locale combination.
+# Direction and Localization
+
+Banhaten is Arabic and English-first, but text direction and language are separate contracts. Components resolve direction from an explicit `dir`, `DirectionProvider`, the nearest valid `[dir]` ancestor, or the document root—in that order. Direction changes layout, icon mirroring, and keyboard geometry; it never selects translated UI or accessibility copy.
+
+Use a request-known direction provider for server rendering so the server markup, hydration snapshot, and first paint agree:
+
+```tsx
+import { DirectionProvider } from "@/hooks/use-direction"
+import {
+  arabicPaginationMessages,
+  Pagination,
+} from "@/components/ui/pagination"
+
+<DirectionProvider dir="rtl">
+  <Pagination messages={arabicPaginationMessages} />
+</DirectionProvider>
+```
+
+`DirectionProvider dir="rtl"` works equally well with English, Arabic, Hebrew, Persian, or Urdu. Choose a component's `messages` catalog from the product locale, or pass its direct label props. The exported Arabic catalogs are conveniences, not RTL defaults.
+
+Without an explicit prop or provider, server output uses a stable LTR snapshot. After hydration, one shared subscription per document synchronizes consumers with the nearest nested boundary or document root. This avoids hydration mismatches and per-component document observers. For an RTL first paint, provide the request-known direction during SSR.
+
+Use logical CSS properties (`start`, `end`, `margin-inline`, `padding-inline`) and `dir="auto"` for user-authored copy. Test mixed-language content, punctuation, numbers, icon mirroring, arrow-key behavior, focus order, portal content, and screen-reader names in every supported direction and locale combination.

package/docs/design-system/form-recipes.md

@@ -1,73 +1,73 @@
-# Form Recipes
-
-## Labeled field with validation
-
-Compose `Field`, `FieldLabel`, `FieldControl`, `FieldDescription`, and `FieldError`. Associate the input with its label, keep help text stable, and announce errors only when validation has run.
-
-```tsx
-<Field invalid={Boolean(error)}>
-  <FieldLabel htmlFor="email">Email</FieldLabel>
-  <FieldControl>
-    <Input id="email" state={error ? "error" : "default"} />
-  </FieldControl>
-  <FieldDescription>Use your work email.</FieldDescription>
-  {error ? <FieldError>{error}</FieldError> : null}
-</Field>
-```
-
-## Selection and dates
-
-Use `Select` for a bounded option set, `Autocomplete` for searchable options, and `DatePicker`/`DateRangePicker` for calendar input. Controlled values are preferred when validation, persistence, or URL state owns the result.
-
-Do not emulate a date field with `Input`, a typed `@`, or a generic trailing icon. The Date Picker owns the calendar affordance, keyboard behavior, formatted value, and the same semantic density contract as the surrounding controls.
-
-## Golden recipe: collection filter bar
-
-Use the complete [`CollectionFilterBarDemo`](../../registry/examples/collection-filter-bar-demo.tsx) recipe for collection and search screens. It establishes the approved composition:
-
-- `ToolbarSearch` is full width and uses `shortcutKeys={["Mod", "F"]}` so Command and Control resolve by platform.
-- `DatePicker` owns the From and To fields.
-- `Select` owns Type and Order; `ToolbarSelect` is only a trigger-shaped primitive and is not a complete menu.
-- Every control declares `density="default"`; responsive width classes do not replace component height, padding, radius, or typography.
-- The Reset action uses the same density and resets all composed controls.
-
-```tsx
-<form aria-label="Collection filters" data-recipe="collection-filter-bar">
-  <ToolbarSearch
-    aria-label="Search bookmarks"
-    density="default"
-    shortcutKeys={["Mod", "F"]}
-    width="full"
-  />
-  <div className="flex flex-wrap items-end gap-3">
-    <DatePicker density="default" triggerProps={{ "aria-label": "From" }} />
-    <DatePicker density="default" triggerProps={{ "aria-label": "To" }} />
-    <Select density="default" value="Everything">{/* items */}</Select>
-    <Select density="default" value="Recently bookmarked">{/* items */}</Select>
-    <ToolbarButton density="default" type="reset" variant="link">Reset</ToolbarButton>
-  </div>
-</form>
-```
-
-## Golden recipe: results toolbar
-
-Use the complete [`ResultsToolbarDemo`](../../registry/examples/results-toolbar-demo.tsx) recipe for result counts, layout selection, and batch actions. `SegmentedControl` is the approved content-width primitive for small mutually exclusive values such as cards per row.
-
-```tsx
-<Toolbar aria-label="Bookmark results" layout="split" wrap>
-  <ToolbarText density="default"><strong>5,371</strong>&nbsp;bookmarks</ToolbarText>
-  <ToolbarSection align="end" wrap>
-    <SegmentedControl aria-label="Cards per row" defaultValue="4" density="default">
-      <SegmentedControlLabel>Cards / row</SegmentedControlLabel>
-      {[3, 4, 5, 6].map((count) => (
-        <SegmentedControlItem key={count} value={String(count)}>{count}</SegmentedControlItem>
-      ))}
-    </SegmentedControl>
-    <ToolbarButton density="default" variant="outline">Select</ToolbarButton>
-  </ToolbarSection>
-</Toolbar>
-```
-
-## RTL forms
-
-Set direction at the form or application boundary. Labels and helper text use logical alignment; OTP, calendar, pagination, and selection keyboard movement resolve the inherited direction. Localize labels, placeholders, validation messages, date formatting, and number formatting in the product layer.
+# Form Recipes
+
+## Labeled field with validation
+
+Compose `Field`, `FieldLabel`, `FieldControl`, `FieldDescription`, and `FieldError`. Associate the input with its label, keep help text stable, and announce errors only when validation has run.
+
+```tsx
+<Field invalid={Boolean(error)}>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <FieldControl>
+    <Input id="email" state={error ? "error" : "default"} />
+  </FieldControl>
+  <FieldDescription>Use your work email.</FieldDescription>
+  {error ? <FieldError>{error}</FieldError> : null}
+</Field>
+```
+
+## Selection and dates
+
+Use `Select` for a bounded option set, `Autocomplete` for searchable options, and `DatePicker`/`DateRangePicker` for calendar input. Controlled values are preferred when validation, persistence, or URL state owns the result.
+
+Do not emulate a date field with `Input`, a typed `@`, or a generic trailing icon. The Date Picker owns the calendar affordance, keyboard behavior, formatted value, and the same semantic density contract as the surrounding controls.
+
+## Golden recipe: collection filter bar
+
+Use the complete [`CollectionFilterBarDemo`](../../registry/examples/collection-filter-bar-demo.tsx) recipe for collection and search screens. It establishes the approved composition:
+
+- `ToolbarSearch` is full width and uses `shortcutKeys={["Mod", "F"]}` so Command and Control resolve by platform.
+- `DatePicker` owns the From and To fields.
+- `Select` owns Type and Order; `ToolbarSelect` is only a trigger-shaped primitive and is not a complete menu.
+- Every control declares `density="default"`; responsive width classes do not replace component height, padding, radius, or typography.
+- The Reset action uses the same density and resets all composed controls.
+
+```tsx
+<form aria-label="Collection filters" data-recipe="collection-filter-bar">
+  <ToolbarSearch
+    aria-label="Search bookmarks"
+    density="default"
+    shortcutKeys={["Mod", "F"]}
+    width="full"
+  />
+  <div className="flex flex-wrap items-end gap-3">
+    <DatePicker density="default" triggerProps={{ "aria-label": "From" }} />
+    <DatePicker density="default" triggerProps={{ "aria-label": "To" }} />
+    <Select density="default" value="Everything">{/* items */}</Select>
+    <Select density="default" value="Recently bookmarked">{/* items */}</Select>
+    <ToolbarButton density="default" type="reset" variant="link">Reset</ToolbarButton>
+  </div>
+</form>
+```
+
+## Golden recipe: results toolbar
+
+Use the complete [`ResultsToolbarDemo`](../../registry/examples/results-toolbar-demo.tsx) recipe for result counts, layout selection, and batch actions. `SegmentedControl` is the approved content-width primitive for small mutually exclusive values such as cards per row.
+
+```tsx
+<Toolbar aria-label="Bookmark results" layout="split" wrap>
+  <ToolbarText density="default"><strong>5,371</strong>&nbsp;bookmarks</ToolbarText>
+  <ToolbarSection align="end" wrap>
+    <SegmentedControl aria-label="Cards per row" defaultValue="4" density="default">
+      <SegmentedControlLabel>Cards / row</SegmentedControlLabel>
+      {[3, 4, 5, 6].map((count) => (
+        <SegmentedControlItem key={count} value={String(count)}>{count}</SegmentedControlItem>
+      ))}
+    </SegmentedControl>
+    <ToolbarButton density="default" variant="outline">Select</ToolbarButton>
+  </ToolbarSection>
+</Toolbar>
+```
+
+## RTL forms
+
+Set direction at the form or application boundary. Labels and helper text use logical alignment; OTP, calendar, pagination, and selection keyboard movement resolve the inherited direction. Localize labels, placeholders, validation messages, date formatting, and number formatting in the product layer.

package/docs/design-system/gap-promotion-policy.md

@@ -1,21 +1,21 @@
-# Gap promotion policy
-
-Every visual-QA background records missing components, assets, composition patterns, and tokens as structured gap metadata. The promotion report groups recurring needs across backgrounds and flags any normalized need seen in three or more distinct scenarios.
-
-Run:
-
-```sh
-npm --prefix playground run report:gap-promotions
-```
-
-The generated [Gap Promotion Report](./gap-promotion-report.md) is checked during background tests. Common needs are classified automatically; add `promotionKey` to a gap when two differently worded gaps represent the same reusable need or when a heuristic would group unrelated needs.
-
-A candidate does not automatically become a component. Promotion requires:
-
-1. Evidence from at least three backgrounds.
-2. A smallest-stable API and explicit fit/avoid guidance.
-3. Semantic density, state, accessibility, and RTL contracts where applicable.
-4. Migration of at least one real background away from its local fallback.
-5. Behavior and visual tests before resolved gap metadata is removed.
-
-The first application of this policy produced `SegmentedControl`, migrated the CRM Intelligence background to the shared primitive, and removed its former local segmented-control gap.
+# Gap promotion policy
+
+Every visual-QA background records missing components, assets, composition patterns, and tokens as structured gap metadata. The promotion report groups recurring needs across backgrounds and flags any normalized need seen in three or more distinct scenarios.
+
+Run:
+
+```sh
+npm --prefix playground run report:gap-promotions
+```
+
+The generated [Gap Promotion Report](./gap-promotion-report.md) is checked during background tests. Common needs are classified automatically; add `promotionKey` to a gap when two differently worded gaps represent the same reusable need or when a heuristic would group unrelated needs.
+
+A candidate does not automatically become a component. Promotion requires:
+
+1. Evidence from at least three backgrounds.
+2. A smallest-stable API and explicit fit/avoid guidance.
+3. Semantic density, state, accessibility, and RTL contracts where applicable.
+4. Migration of at least one real background away from its local fallback.
+5. Behavior and visual tests before resolved gap metadata is removed.
+
+The first application of this policy produced `SegmentedControl`, migrated the CRM Intelligence background to the shared primitive, and removed its former local segmented-control gap.

package/docs/design-system/icons.md

@@ -1,69 +1,74 @@
-# Icons
-
-The interactive icon explorer is available in the app under the `Icons` section.
-
-## Recommendation Posture
-
-Start the decision with five serious candidates:
-
-- `Lucide`: best default for modern product UI, especially if we want light, consistent, stroke-based icons.
-- `Tabler Icons`: best coverage-first option. It has a huge set, outline/fill coverage, and a familiar 24px grid.
-- `Material Symbols`: best if we want Google-style recognizability and many built-in style axes.
-- `Radix Icons`: best for very dense component UI where 15px icons need to stay crisp.
-- `Phosphor`: best if we want expressive weight control, including thin, bold, fill, and duotone variants.
-
-Keep `Simple Icons` as a separate brand-logo source. It should not be the primary UI icon family.
-
-## Packs To Review
-
-| Pack | Prefix | License | Best for | Variants to compare |
-| --- | --- | --- | --- | --- |
-| Google Material Symbols | `material-symbols` | Apache-2.0 | Google-style UI, broad coverage | Regular, Rounded, Sharp, Outline, Outline Rounded, Outline Sharp |
-| Google Material Icons Classic | `ic` | Apache-2.0 | Existing Material Icons familiarity | Filled/Baseline, Outlined, Rounded, Sharp, Two tone |
-| Material Design Icons by Pictogrammers | `mdi` | Apache-2.0 | Maximum utility coverage | Single broad style |
-| Radix Icons | `radix-icons` | MIT | Dense controls, primitives, menus | Single 15px style |
-| Lucide | `lucide` | ISC | Clean SaaS/product UI | Single outline style |
-| Heroicons | `heroicons` | MIT | Tailwind-friendly apps | Outline 24, Solid 24, Solid 20, Solid 16 |
-| Tabler Icons | `tabler` | MIT | Broad app coverage | Outline, filled where available |
-| Phosphor | `ph` | MIT | Adjustable visual tone | Thin, Light, Regular, Bold, Fill, Duotone |
-| Remix Icon | `ri` | Apache-2.0 | Neutral line/fill system icons | Line, Fill |
-| Bootstrap Icons | `bi` | MIT | Bootstrap-adjacent apps | Mixed outline/fill names |
-| Fluent UI System Icons | `fluent` | MIT | Microsoft-like UI language | Regular, Filled |
-| Carbon Icons | `carbon` | Apache-2.0 | Enterprise/data tools | Fixed source sizes in packages |
-| Ant Design Icons | `ant-design` | MIT | Enterprise React products | Outlined, Filled, TwoTone |
-| Octicons | `octicon` | MIT | Developer tools, GitHub-like UI | 16px and 24px source sizes |
-| Feather Icons | `feather` | MIT | Minimal legacy outline style | Single outline style |
-| Iconoir | `iconoir` | MIT | Broad modern outline set | Single outline style |
-| Flowbite Icons | `flowbite` | MIT | Tailwind/Flowbite apps | Outline, Solid |
-| Ionicons | `ion` | MIT | Mobile/app UI | Outline, Filled, Sharp |
-| Simple Icons | `simple-icons` | CC0-1.0 | Brand logos only | Single-color brand marks |
-
-## Decision Criteria
-
-- Button icon clarity at 16px and 20px.
-- Menu, dropdown, and table icon legibility in dense rows.
-- Visual match with `default`, `rounded`, and `sharp` appearances.
-- Variant usefulness: filled states, two-tone states, sharp geometry, or rounded geometry.
-- Coverage for navigation, data, files, users, settings, alerts, billing, integrations, and brand logos.
-- Licensing and attribution obligations. Keep source license notices in the project when redistributing SVG/source files.
-
-## Sources
-
-- Google Material Icons repository: https://github.com/google/material-design-icons
-- Iconify collection API: https://iconify.design/docs/api/collection.html
-- Radix Icons: https://github.com/radix-ui/icons
-- Lucide: https://github.com/lucide-icons/lucide
-- Heroicons: https://heroicons.com
-- Tabler Icons: https://github.com/tabler/tabler-icons
-- Phosphor Icons: https://github.com/phosphor-icons/core
-- Remix Icon: https://www.remixicon.com
-- Bootstrap Icons: https://icons.getbootstrap.com
-- Fluent UI System Icons: https://github.com/microsoft/fluentui-system-icons
-- Carbon Icons: https://carbondesignsystem.com/elements/icons/code
-- Ant Design Icons: https://www.npmjs.com/package/@ant-design/icons
-- Octicons: https://primer.github.io/design/components/icon
-- Feather Icons: https://github.com/feathericons/feather
-- Iconoir: https://github.com/iconoir-icons/iconoir
-- Flowbite Icons: https://flowbite.com/icons
-- Ionicons: https://github.com/ionic-team/ionicons
-- Simple Icons: https://github.com/simple-icons/simple-icons
+# Icons
+
+The interactive icon explorer is available in the app under the `Icons` section.
+
+## Recommendation Posture
+
+Start the decision with five serious candidates:
+
+- `Lucide`: best default for modern product UI, especially if we want light, consistent, stroke-based icons.
+- `Tabler Icons`: best coverage-first option. It has a huge set, outline/fill coverage, and a familiar 24px grid.
+- `Material Symbols`: best if we want Google-style recognizability and many built-in style axes.
+- `Radix Icons`: best for very dense component UI where 15px icons need to stay crisp.
+- `Phosphor`: best if we want expressive weight control, including thin, bold, fill, and duotone variants.
+
+Keep `Simple Icons` as a separate brand-logo source. It should not be the primary UI icon family.
+
+## Packs To Review
+
+| Pack | Prefix | License | Best for | Variants to compare |
+| --- | --- | --- | --- | --- |
+| Google Material Symbols | `material-symbols` | Apache-2.0 | Google-style UI, broad coverage | Regular, Rounded, Sharp, Outline, Outline Rounded, Outline Sharp |
+| Google Material Icons Classic | `ic` | Apache-2.0 | Existing Material Icons familiarity | Filled/Baseline, Outlined, Rounded, Sharp, Two tone |
+| Material Design Icons by Pictogrammers | `mdi` | Apache-2.0 | Maximum utility coverage | Single broad style |
+| Radix Icons | `radix-icons` | MIT | Dense controls, primitives, menus | Single 15px style |
+| Lucide | `lucide` | ISC | Clean SaaS/product UI | Single outline style |
+| Heroicons | `heroicons` | MIT | Tailwind-friendly apps | Outline 24, Solid 24, Solid 20, Solid 16 |
+| Tabler Icons | `tabler` | MIT | Broad app coverage | Outline, filled where available |
+| Phosphor | `ph` | MIT | Adjustable visual tone | Thin, Light, Regular, Bold, Fill, Duotone |
+| Remix Icon | `ri` | Apache-2.0 | Neutral line/fill system icons | Line, Fill |
+| Bootstrap Icons | `bi` | MIT | Bootstrap-adjacent apps | Mixed outline/fill names |
+| Fluent UI System Icons | `fluent` | MIT | Microsoft-like UI language | Regular, Filled |
+| Carbon Icons | `carbon` | Apache-2.0 | Enterprise/data tools | Fixed source sizes in packages |
+| Ant Design Icons | `ant-design` | MIT | Enterprise React products | Outlined, Filled, TwoTone |
+| Octicons | `octicon` | MIT | Developer tools, GitHub-like UI | 16px and 24px source sizes |
+| Feather Icons | `feather` | MIT | Minimal legacy outline style | Single outline style |
+| Iconoir | `iconoir` | MIT | Broad modern outline set | Single outline style |
+| Flowbite Icons | `flowbite` | MIT | Tailwind/Flowbite apps | Outline, Solid |
+| Ionicons | `ion` | MIT | Mobile/app UI | Outline, Filled, Sharp |
+| Simple Icons | `simple-icons` | CC0-1.0 | Brand logos only | Single-color brand marks |
+
+## Decision Criteria
+
+- Default UI glyph clarity at 18px, with the glyph centered in a 20px layout slot.
+- Small-control icon clarity at 16px without promoting those intentionally compact glyphs to the default size.
+- Menu, dropdown, and table icon legibility in dense rows.
+- Visual match with `default`, `rounded`, and `sharp` appearances.
+- Variant usefulness: filled states, two-tone states, sharp geometry, or rounded geometry.
+- Coverage for navigation, data, files, users, settings, alerts, billing, integrations, and brand logos.
+- Licensing and attribution obligations. Keep source license notices in the project when redistributing SVG/source files.
+
+## Default Geometry Contract
+
+Default UI icons use `--bh-icon-size-default` (`18px`) inside `--bh-icon-slot-size-default` (`20px`). The resulting `--bh-icon-slot-inset-default` is `1px` on each side. Components must preserve that slot so switching from the former 20px glyph does not change alignment, gaps, or control dimensions. Intentional 12px, 16px, 24px, brand-logo, avatar, spinner, and control-indicator sizes remain component-specific.
+
+## Sources
+
+- Google Material Icons repository: https://github.com/google/material-design-icons
+- Iconify collection API: https://iconify.design/docs/api/collection.html
+- Radix Icons: https://github.com/radix-ui/icons
+- Lucide: https://github.com/lucide-icons/lucide
+- Heroicons: https://heroicons.com
+- Tabler Icons: https://github.com/tabler/tabler-icons
+- Phosphor Icons: https://github.com/phosphor-icons/core
+- Remix Icon: https://www.remixicon.com
+- Bootstrap Icons: https://icons.getbootstrap.com
+- Fluent UI System Icons: https://github.com/microsoft/fluentui-system-icons
+- Carbon Icons: https://carbondesignsystem.com/elements/icons/code
+- Ant Design Icons: https://www.npmjs.com/package/@ant-design/icons
+- Octicons: https://primer.github.io/design/components/icon
+- Feather Icons: https://github.com/feathericons/feather
+- Iconoir: https://github.com/iconoir-icons/iconoir
+- Flowbite Icons: https://flowbite.com/icons
+- Ionicons: https://github.com/ionic-team/ionicons
+- Simple Icons: https://github.com/simple-icons/simple-icons

package/docs/design-system/installation.md

@@ -1,68 +1,70 @@
-# Installation
-
-## Requirements
-
-Banhaten installs source into a React 18.2/19 project using Tailwind CSS 4. Use Node 18.18 or newer.
-
-```bash
-npx banhaten init
-npx banhaten add button input select
-```
-
-Run the package-manager command printed by the CLI. It detects npm, pnpm, Yarn, and Bun from `packageManager` or lockfiles.
-
-Dependency declarations are validated with npm-compatible semantic-version
-ranges. A consumer range is kept only when every version it allows satisfies the
-Banhaten requirement. If the Banhaten range is wholly contained by a broader
-consumer range, the CLI safely narrows the declaration in its existing package
-section, updates `package.json`, and prints an install command so the package
-manager can reconcile its lockfile. Partial overlaps, disjoint ranges, mutable
-tags, workspace protocols, aliases, Git URLs, and local file specs fail without
-writing. Banhaten deliberately does not treat a current lockfile resolution as a
-durable compatibility guarantee. When the manifest is already safe, the CLI also
-checks package versions inside the target project or declared workspace boundary.
-For npm lockfiles v2 and v3 it verifies the importer declarations and exact locked
-resolutions; stale, missing, incompatible, or opaque lock state keeps the install
-action visible. Machine-readable output exposes the same
-`{ required, command, cwd }` state, including the project or workspace directory
-where the command must run.
-
-## Vite
-
-Before writing, the CLI resolves a canonical install plan from
-`banhaten.config.json`, the TypeScript `@/*` path, and the Vite `@` alias. If
-TypeScript and Vite agree, that root is used even when another `src` directory
-exists. If only one side declares the alias, the CLI mirrors it to the other.
-Conflicting roots, multi-target TypeScript paths, destination-overlapping aliases,
-inherited TypeScript aliases without local `baseUrl`/`paths`, and Vite aliases
-that cannot be inspected statically fail without changing the project. When a
-supported Vite config exists, `init` also adds the Tailwind Vite plugin while
-preserving its existing structure.
-
-CLI commands use strict schemas. Unknown or duplicate flags, missing values, and
-unexpected positional arguments are rejected before project discovery. The
-install receipt pins the resolved destinations; changing roots later requires
-moving or removing the old generated files and receipt first.
-
-## Next.js and other frameworks
-
-Without Vite, the CLI installs Tailwind and writes the configured global stylesheet, aliases, `cn` utility, and direction hook. Import the generated global stylesheet from the framework root layout and ensure the `@/*` TypeScript alias resolves to the source directory.
-
-## Fonts and direction
-
-The generated stylesheet imports Inter weights 400–700 and IBM Plex Sans Arabic weights 400–700. Set document language and direction at the application boundary:
-
-```tsx
-<html lang="ar" dir="rtl" data-theme="blue" data-radius="default">
-```
-
-Wrap server-rendered component trees in `DirectionProvider` when request data already determines the direction; this keeps the first server and client snapshots identical. It is also the boundary for nested surfaces that differ from the document. Without it, components hydrate from a stable LTR snapshot and then synchronize from the document through one shared observer.
-
-## Updating safely
-
-```bash
-npx banhaten diff
-npx banhaten update
-```
-
-The receipt records generated hashes. Unmodified files update automatically. Locally modified files and token blocks stop without writing; pass `--force` only after reviewing the unified diff. Put product overrides outside the marked token block and product composition in wrapper components.
+# Installation
+
+## Requirements
+
+Banhaten installs source into a React 18.2/19 project using Tailwind CSS 4. Use Node 18.18 or newer.
+
+```bash
+npx banhaten init
+npx banhaten add button input select
+```
+
+Run the package-manager command printed by the CLI. It detects npm, pnpm, Yarn, and Bun from `packageManager` or lockfiles.
+
+Dependency declarations are validated with npm-compatible semantic-version
+ranges. A consumer range is kept only when every version it allows satisfies the
+Banhaten requirement. If the Banhaten range is wholly contained by a broader
+consumer range, the CLI safely narrows the declaration in its existing package
+section, updates `package.json`, and prints an install command so the package
+manager can reconcile its lockfile. Partial overlaps, disjoint ranges, mutable
+tags, workspace protocols, aliases, Git URLs, and local file specs fail without
+writing. Banhaten deliberately does not treat a current lockfile resolution as a
+durable compatibility guarantee. When the manifest is already safe, the CLI also
+checks package versions inside the target project or declared workspace boundary.
+For npm lockfiles v2 and v3 it verifies the importer declarations and exact locked
+resolutions; stale, missing, incompatible, or opaque lock state keeps the install
+action visible. Machine-readable output exposes the same
+`{ required, command, cwd }` state, including the project or workspace directory
+where the command must run.
+
+## Vite
+
+Before writing, the CLI resolves a canonical install plan from
+`banhaten.config.json`, the TypeScript `@/*` path, and the Vite `@` alias. If
+TypeScript and Vite agree, that root is used even when another `src` directory
+exists. If only one side declares the alias, the CLI mirrors it to the other.
+Conflicting roots, multi-target TypeScript paths, destination-overlapping aliases,
+inherited TypeScript aliases without local `baseUrl`/`paths`, and Vite aliases
+that cannot be inspected statically fail without changing the project. When a
+supported Vite config exists, `init` also adds the Tailwind Vite plugin while
+preserving its existing structure.
+
+CLI commands use strict schemas. Unknown or duplicate flags, missing values, and
+unexpected positional arguments are rejected before project discovery. The
+install receipt pins the resolved destinations; changing roots later requires
+moving or removing the old generated files and receipt first.
+
+## Next.js and other frameworks
+
+Without Vite, the CLI installs Tailwind and writes the configured global stylesheet, aliases, `cn` utility, and direction hook. Import the generated global stylesheet from the framework root layout and ensure the `@/*` TypeScript alias resolves to the source directory.
+
+## Fonts and direction
+
+The generated stylesheet imports Inter weights 400–700 and IBM Plex Sans Arabic weights 400–700. Set document language and direction at the application boundary:
+
+```tsx
+<html lang="ar" dir="rtl" data-theme="gray" data-radius="default">
+```
+
+Wrap server-rendered component trees in `DirectionProvider` when request data already determines the direction; this keeps the first server and client snapshots identical. It is also the boundary for nested surfaces that differ from the document. Without it, components hydrate from a stable LTR snapshot and then synchronize from the document through one shared observer.
+
+## Updating safely
+
+```bash
+npx banhaten diff
+npx banhaten update
+```
+
+The receipt records generated hashes. Unmodified files update automatically. Locally modified files and token blocks stop without writing; pass `--force` only after reviewing the unified diff. Put product overrides outside the marked token block and product composition in wrapper components.
+
+The CLI also checks the original contents of every write target and the files used for ownership checks and merges before and after staging. An intervening edit, creation, or deletion aborts the plan, even with `--force`. Re-run the command after concurrent edits have finished.