Shewart · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026
diff --git a/README.md b/README.md
@@ -87,10 +87,12 @@ New CLI sidebar installs use the host-loaded `shellui.js`; the legacy `sidebar-j
 | Command | Purpose |
 |---|---|
 | `init` | Set up ShellUI, Tailwind, host wiring, and the generated project structure |
-| `add <components...>` | Install one or more direct targets and their hidden dependencies |
+| `add <components...>` | Install one or more direct targets (or `all`) and their hidden dependencies |
 | `list` | List direct targets, installed targets, or targets still available |
 | `remove <components...>` | Remove named installed components |
-| `update [components...]` | Reinstall named or all installed templates |
+| `update [components...]` | Reinstall named or all installed templates, skipping files you changed unless `--force` |
+| `doctor` | Check the project's setup and say how to fix each problem |
+| `migrate [components...]` | Rewrite your pages for template API changes |
 | `theme init <url-or-id>` | Initialize a project and apply a tweakcn theme |
 | `theme apply <url-or-id>` | Apply a theme to `wwwroot/input.css` or emit override CSS |
 | `theme update` | Re-fetch the source recorded in `shellui.theme.lock` |

diff --git a/VERSIONING_STRATEGY.md b/VERSIONING_STRATEGY.md
@@ -10,7 +10,7 @@ ShellUI uses one centralized version for the source templates, CLI tool, and pac
 | Target framework | .NET 8 and .NET 10 (`ShellUI.Components` also .NET 9) |
 | Tailwind version | `4.3.2` |
 
-`0.3.0-rc.1` was the last release targeting .NET 9.
+`0.3.0-rc.1` was the last release built only for .NET 9. `0.3.0-rc.2` through `0.3.6` and the 0.4 prereleases need .NET 10; `0.4.0` supports .NET 8, 9 and 10.
 
 ## Single Source of Truth
 
@@ -59,14 +59,15 @@ The CLI writes the computed version into `shellui.json` for each installed entry
       "Name": "button",
       "Version": "0.4.0",
       "InstalledAt": "2026-01-01T00:00:00Z",
-      "IsCustomized": false
+      "IsCustomized": false,
+      "Hash": "3b1f9c0e7a52d84f6e2c19ab07d4e5f8c6a3b2d1e0f9a8b7c6d5e4f3a2b1c0d9"
     }
   ],
   "ProjectType": 1
 }
 ```
 
-The timestamp is illustrative. A copied component is source owned by the consumer, so its recorded version identifies the registry release used at install or update time; it does not automatically track a later package publication.
+The timestamp and hash are illustrative. A copied component is source owned by the consumer, so its recorded version identifies the registry release used at install or update time; it does not automatically track a later package publication.
 
 Theme data has a separate lock file. `shellui.theme.lock` records the theme source URL, content hash, theme name, and application time. That lock controls `theme update` and is independent of the component version.
 
@@ -88,7 +89,7 @@ A local tool manifest can pin the same version for a team. An unversioned instal
 `ShellUI.Components` is the runtime RCL package. Select its published version explicitly when using NuGet:
 
 ```bash
-dotnet add package ShellUI.Components --version <published-version> --prerelease
+dotnet add package ShellUI.Components --version <published-version>
 ```
 
 Do not add `ShellUI.Core` or `ShellUI.Templates` to a consumer project. They are internal implementation projects.
@@ -153,12 +154,12 @@ The unified version applies to the source system and the two packable artifacts.
 
 ## Compatibility Boundaries
 
-- The current repository baseline is .NET 10. This strategy does not claim support for an older target framework that is not configured in the current projects.
+- The repository builds with the .NET 10 SDK. The CLI, Core and Templates target .NET 8 and .NET 10 (the CLI rolls forward to newer runtimes), and `ShellUI.Components` targets .NET 8, 9 and 10. This strategy does not claim support for a target framework that is not configured in the current projects.
 - Tailwind CSS `4.3.2` is the current generated-CSS baseline.
 - The CLI and the NuGet RCL are separate consumption paths, but a project that combines them should use versions from the same ShellUI release line.
 - CLI-installed files are copied into the consumer project and remain subject to the consumer's own edits. Updating them is an explicit CLI operation, not an automatic package update.
 - Theme lock files track theme sources, not package versions.
 
 ## Summary
 
-The version is centralized in `Directory.Build.props`, targeting .NET 10 and Tailwind CSS `4.3.2`. `ShellUI.CLI` and `ShellUI.Components` are the only packable artifacts. Prerelease versions must be selected explicitly.
+The version is centralized in `Directory.Build.props`, targeting .NET 8 and .NET 10 (`ShellUI.Components` also .NET 9) and Tailwind CSS `4.3.2`. `ShellUI.CLI` and `ShellUI.Components` are the only packable artifacts. Prerelease versions must be selected explicitly.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -77,15 +77,17 @@ The implemented command tree is:
 | Command | Responsibility |
 |---|---|
 | `shellui init` | Detect a Blazor project, configure Tailwind, install bootstrap assets, create `shellui.json`, patch the host, and create the MSBuild integration. |
-| `shellui add <components...>` | Install one or more direct targets and recursively install their registry dependencies. |
+| `shellui add <components...>` | Install one or more direct targets (or `all`) and recursively install their registry dependencies. |
 | `shellui list` | List direct targets, with installed/available filtering. |
 | `shellui remove <components...>` | Remove selected installed source files and update `shellui.json`. |
 | `shellui update [components...]` | Rewrite selected installed source files, or all installed components with `--all`; skips files changed since install unless `--force`, and installs new dependencies. |
+| `shellui doctor` | Check `shellui.json`, Tailwind, the host page, render mode, installed files and usings; print a fix for each problem and exit 1 on errors. |
+| `shellui migrate [components...]` | Rewrite the app's own `.razor` and `.cs` files for template API changes, showing a diff and asking first. |
 | `shellui theme init <url-or-id>` | Initialize a project and apply a fetched theme in one operation. |
 | `shellui theme apply <url-or-id>` | Apply a theme to `wwwroot/input.css` or emit a standalone override. |
 | `shellui theme update` | Re-fetch the theme recorded in `shellui.theme.lock`. |
 
-`init` accepts `--force`, `--style`, `--tailwind standalone|npm`, and `--yes`. `add` accepts space- or comma-separated component names and `--force`. The command surface above is the current implementation; commands not listed here are not part of the current CLI.
+`init` accepts `--force`, `--style`, `--tailwind standalone|npm`, `--yes`, `--dashboard 01|02|none`, and `--replace-layout`. `add` accepts space- or comma-separated component names, `--force`, `--replace-layout`, and `--except`. The command surface above is the current implementation; commands not listed here are not part of the current CLI.
 
 ## Registry Model and Counts
 
@@ -107,10 +109,10 @@ A dependency entry is still real source and is written to the consumer project w
 4. The installer walks `Dependencies` recursively before writing the requested target. Hidden entries are installed through this walk rather than being presented as normal public targets.
 5. The installer retrieves the template content, substitutes the consumer namespace, and writes it according to the metadata `FilePath` under `Components/UI`, `Components/Layout`, or a project `wwwroot` path.
 6. Required NuGet dependencies are collected during the walk and added once per package after source files are written. CSS assets are linked into the host when applicable.
-7. The installer records each installed name, computed version, installation time, and customization state in `shellui.json`.
+7. The installer records each installed name, computed version, installation time, customization state, and a hash of the written file in `shellui.json`.
 8. The generated MSBuild integration runs Tailwind during the consumer build, producing the configured CSS output.
 
-`remove` deletes the selected installed file and removes its record. The current remove path is optimized for regular component targets; layout blocks should be removed manually from `Components/Layout` until layout-aware removal is implemented. `update` rewrites selected source from the current registry and records the installed version. Theme commands use a separate managed CSS region and write `shellui.theme.lock`; theme updates re-fetch the recorded source rather than changing the component version.
+`remove` deletes the selected installed file and removes its record. For a layout block it deletes the file from `Components/Layout` and lists the `.razor` files that still reference the layout; it does not undo the layout wiring. `update` rewrites selected source from the current registry and records the installed version. Theme commands use a separate managed CSS region and write `shellui.theme.lock`; theme updates re-fetch the recorded source rather than changing the component version.
 
 ## Build and Test Flow
 

diff --git a/docs/CLI_INSTALLATION.md b/docs/CLI_INSTALLATION.md
@@ -43,7 +43,7 @@ The manifest is `.config/dotnet-tools.json` and uses the installed package versi
   "isRoot": true,
   "tools": {
     "shellui.cli": {
-      "version": "0.3.5",
+      "version": "0.4.0",
       "commands": ["shellui"]
     }
   }

diff --git a/docs/CLI_SYNTAX.md b/docs/CLI_SYNTAX.md
@@ -308,14 +308,15 @@ Representative fields look like this:
       "Name": "button",
       "Version": "0.4.0",
       "InstalledAt": "2026-01-01T00:00:00Z",
-      "IsCustomized": false
+      "IsCustomized": false,
+      "Hash": "3b1f9c0e7a52d84f6e2c19ab07d4e5f8c6a3b2d1e0f9a8b7c6d5e4f3a2b1c0d9"
     }
   ],
   "ProjectType": 1
 }
 ```
 
-`ProjectType` is serialized as the enum value; `1` is `BlazorServer`. `IsCustomized` is metadata, not a merge mechanism. `update` still overwrites the file.
+`ProjectType` is serialized as the enum value; `1` is `BlazorServer`. `Hash` is what `update` compares the file with to spot your changes (entries written before 0.4.0-alpha.2 have none), and `update` sets `IsCustomized` on a file it skips for that reason. Neither is a merge mechanism; `update --force` still overwrites the file.
 
 ## Common workflow
 

diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md
@@ -23,7 +23,7 @@ The direct-target count is the number users invoke with `shellui add`. It is not
 | CLI workflow | Yes | No CLI in this comparison | No CLI in this comparison | No CLI in this comparison | No CLI in this comparison | No CLI in this comparison |
 | Accessibility status | Semantic markup is used; no current WCAG conformance claim | Not audited here | Not audited here | Not audited here | Not audited here | Not audited here |
 | Bundle/performance status | No current reproducible benchmark published | No current benchmark published here | No current benchmark published here | No current benchmark published here | No current benchmark published here | No current benchmark published here |
-| Community status | Current project is an alpha snapshot; no comparable size claim | See the current project community | See the current project community | See the current project community | See the current project community | See the current project community |
+| Community status | Pre-1.0 project; no comparable size claim | See the current project community | See the current project community | See the current project community | See the current project community | See the current project community |
 
 The “not audited here” cells are intentional. They avoid presenting stale component counts, community metrics, or performance estimates as if they were current facts.
 

diff --git a/docs/COMPONENT_DEPENDENCIES.md b/docs/COMPONENT_DEPENDENCIES.md
@@ -87,7 +87,7 @@ Several entries are deliberately hidden from `shellui list` while remaining part
 - `button-variants` is hidden and is required by `button`.
 - `card-header`, `card-title`, `card-description`, `card-content`, and `card-footer` are hidden card sub-components, not independent public card targets.
 - `shell` is a hidden utility installed during `shellui init` and used by the sidebar graph.
-- `shellui-js` is a hidden JavaScript support asset. It is used by `copy-button`, `file-upload`, `input-otp`, `theme-toggle`, `command-palette`, and the hidden `sidebar-provider`; it is not a standalone public component.
+- `shellui-js` is a hidden JavaScript support asset. It is used by `copy-button`, `file-upload`, `input-otp`, `theme-toggle`, `command-palette`, `resizable`, and the hidden `sidebar-provider`; it is not a standalone public component.
 - `data-table-models`, `chart-variants`, `chart-styles`, `context-menu-models`, and similar entries are hidden support templates used by their registered parents.
 
 A hidden entry can have an empty `Dependencies` list while still being required by a parent. For example, the metadata for `shellui-js` describes the asset itself; it does not turn every component that uses the asset into a dependency of the asset.

diff --git a/docs/COMPONENT_ROADMAP.md b/docs/COMPONENT_ROADMAP.md
@@ -2,14 +2,14 @@
 
 **Goal:** Build the components and tooling needed for a Tailwind-first Blazor design system.
 
-.NET 10 · Tailwind CSS `4.3.2`
+.NET 8, 9 and 10 · Tailwind CSS `4.3.2`
 
 ## Current inventory
 
-`ComponentRegistry` is the source of truth for component availability, names, and dependencies. The current registry contains **243 entries**:
+`ComponentRegistry` is the source of truth for component availability, names, and dependencies. The current registry contains **254 entries**:
 
-- **93 direct CLI targets** shown by `shellui list`
-- **150 hidden entries** for sub-components, variants, models, services, and support assets
+- **98 direct CLI targets** shown by `shellui list`
+- **156 hidden entries** for sub-components, variants, models, services, and support assets
 - **Packable projects:** `ShellUI.CLI` and `ShellUI.Components`
 
 Hidden entries are not counted as direct targets. They can still be installed recursively when a parent target declares them.
@@ -81,6 +81,13 @@ The current registry provides explicit sub-components for these parent component
 - [x] **ContextMenu** — `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuOption`
 - [x] **NavigationMenu** — `NavList`, `NavItem`, `NavTrigger`, `NavContent`
 - [x] **Carousel** — `CarouselList`, `CarouselSlide`
+- [x] **AlertDialog** — `AlertDialogTrigger`, `AlertDialogContent`, `AlertDialogHeader`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogFooter`, `AlertDialogAction`, `AlertDialogCancel` (0.4)
+- [x] **Breadcrumb** — `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` (0.4)
+- [x] **Command** — `CommandInput`, `CommandList`, `CommandGroup`, `CommandOption`, `CommandEmpty`, `CommandSeparator` (0.4)
+- [x] **Form** — `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage` (0.4)
+- [x] **Menubar** — `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`, `MenubarSeparator` (0.4)
+- [x] **Pagination** — `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, `PaginationEllipsis` (0.4)
+- [x] **Resizable** — `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle` (0.4; the old `Resizable` is deprecated)
 
 The intended pattern is explicit child components, cascaded state and callbacks, value/label parameters, and Tailwind utility classes matching the shadcn-style API.
 

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -1,10 +1,10 @@
 # Contributing to ShellUI
 
-ShellUI targets .NET 8 and .NET 10 and Tailwind CSS `4.3.2`. This guide describes the contribution and verification workflow; releases are covered in [VERSIONING_STRATEGY.md](../VERSIONING_STRATEGY.md) and [RELEASING.md](RELEASING.md).
+ShellUI targets .NET 8 and .NET 10 (`ShellUI.Components` also .NET 9) and Tailwind CSS `4.3.2`. This guide describes the contribution and verification workflow; releases are covered in [VERSIONING_STRATEGY.md](../VERSIONING_STRATEGY.md) and [RELEASING.md](RELEASING.md).
 
 ## Contribution Policy
 
-ShellUI is an active alpha project. Focused bug fixes, documentation corrections, tests, and component or CLI improvements are welcome through GitHub issues and pull requests.
+ShellUI is an active pre-1.0 project. Focused bug fixes, documentation corrections, tests, and component or CLI improvements are welcome through GitHub issues and pull requests.
 
 Before starting a substantial new component, a new distribution path, or a change to the registry contract:
 
@@ -13,7 +13,7 @@ Before starting a substantial new component, a new distribution path, or a chang
 3. Agree on the smallest useful scope before implementing a large change.
 4. Keep the change compatible with the current architecture unless the proposal explicitly changes that architecture.
 
-Alpha software can change its APIs and generated source. An issue or pull request is not a promise that a feature will be accepted, scheduled, or released. There is no response-time or adoption target in this policy.
+Pre-1.0 software can change its APIs and generated source. An issue or pull request is not a promise that a feature will be accepted, scheduled, or released. There is no response-time or adoption target in this policy.
 
 Implemented features should be described as implemented. Ideas that have no implementation or release assignment belong in an issue or in the unscheduled section below, not in current-status documentation.
 
@@ -45,7 +45,7 @@ dotnet restore ShellUI.slnx
 dotnet build ShellUI.slnx --configuration Release
 ```
 
-The CLI supports the implemented commands `init`, `add`, `list`, `remove`, `update`, `theme init`, `theme apply`, and `theme update`. Use a local build when testing changes; do not substitute an older published CLI merely because it is easier to install.
+The CLI supports the implemented commands `init`, `add`, `list`, `remove`, `update`, `doctor`, `migrate`, `theme init`, `theme apply`, and `theme update`. Use a local build when testing changes; do not substitute an older published CLI merely because it is easier to install.
 
 The precompiled CSS and safelist are generated as part of the CI workflow. When changing component CSS, variant helpers, or safelist inputs, regenerate the safelist and then build the bundle:
 
@@ -93,7 +93,7 @@ For a component change:
 
 1. Update the live component and its generated template together.
 2. Update registry metadata, dependencies, `FilePath`, variants, and NuGet dependencies when the public contract changes.
-3. Preserve the distinction between direct targets and hidden dependency entries. The current registry has 243 entries, including 93 direct targets and 150 hidden entries.
+3. Preserve the distinction between direct targets and hidden dependency entries. The current registry has 254 entries, including 98 direct targets and 156 hidden entries.
 4. Use the Tailwind `4.3.2` variable and utility conventions already used by the project.
 5. Add or update tests that exercise the changed registry, template, or CLI behavior.
 6. Review keyboard and assistive-technology behavior without claiming a blanket accessibility conformance level that the repository does not test.