diff --git a/Directory.Build.props b/Directory.Build.props
index b61e6e3..33646ab 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -3,7 +3,7 @@
   <!-- One version for every ShellUI package -->
   <PropertyGroup>
     <ShellUIVersion>0.4.0</ShellUIVersion>
-    <ShellUIVersionSuffix>alpha.3</ShellUIVersionSuffix>
+    <ShellUIVersionSuffix></ShellUIVersionSuffix>
   </PropertyGroup>
 
   <PropertyGroup>
diff --git a/README.md b/README.md
index 755dfbf..1dac508 100644
--- a/README.md
+++ b/README.md
@@ -24,12 +24,12 @@
 
 | Channel | Version | Notes |
 |---|---|---|
-| Latest stable (recommended) | `0.3.5` | Tailwind CSS `4.3.2` |
-| Prerelease | `0.4.0-alpha.3` | This branch; install with `--version 0.4.0-alpha.3` |
+| Latest stable (recommended) | `0.4.0` | Tailwind CSS `4.3.2` |
+| Previous stable | `0.3.6` | Patches come from `release/v0.3` |
 
-The CLI runs on .NET 8 or later and works in Blazor projects on .NET 8, 9 and 10. The `ShellUI.Components` NuGet package targets .NET 8, 9 and 10. (`0.4.0-alpha.3` and the 0.3 line need .NET 10 for both.)
+The CLI runs on .NET 8 or later and works in Blazor projects on .NET 8, 9 and 10. The `ShellUI.Components` NuGet package targets .NET 8, 9 and 10. (The 0.3 line and the 0.4 prereleases need .NET 10 for both.)
 
-`main` is the 0.4 line, so this README and `docs/` describe `0.4.0-alpha.3`, including features that are not in a stable release yet, such as `shellui init --dashboard` and the auth blocks. For the stable version, read the [v0.3.5 docs](https://github.com/shellui-dev/shellui/tree/v0.3.5). Prereleases need `--version` to install.
+This README and `docs/` describe `0.4.0`. For 0.3, read the [v0.3.6 docs](https://github.com/shellui-dev/shellui/tree/v0.3.6).
 
 ShellUI is pre-1.0, so APIs and generated output can still change between minor versions. Validate it in your target Blazor and hosting environments before relying on it.
 
@@ -37,7 +37,7 @@ ShellUI is pre-1.0, so APIs and generated output can still change between minor
 
 - The CLI commands are `init`, `add`, `list`, `remove`, `update`, `doctor` and `migrate`, plus `theme init`, `theme apply`, and `theme update`.
 - The component registry has **254 entries**: **98 direct install targets** and **156 hidden dependency entries**. `list` shows direct targets; `add` resolves hidden dependencies.
-- `0.4.0-alpha.1` adds `kbd`, `aspect-ratio`, `button-group`, `toggle-group`, `input-group`, `number-input`, `stat-card`, `timeline`, `tree-view`, `qr-code`, `image-viewer`, `chat`, `chat-message`, `chat-input`, and the `auth-01`, `auth-02` and `auth-03` blocks.
+- `0.4.0` adds `kbd`, `aspect-ratio`, `button-group`, `toggle-group`, `input-group`, `number-input`, `stat-card`, `timeline`, `tree-view`, `qr-code`, `image-viewer`, `chat`, `chat-message`, `chat-input`, `prompt-suggestions`, `reasoning`, `tool-call`, `field`, `json-viewer`, and the `auth-01`, `auth-02` and `auth-03` blocks. `resizable` is now a real resizable panel group.
 - `0.3.0` added `typed-select`, `command-palette`, `data-picker`, `multi-select`, `tag-input`, `donut-chart`, `radar-chart`, and `radial-chart`.
 - `ShellUI.Components` supports a release-generated precompiled CSS bundle and a generated safelist for existing Tailwind builds.
 - The CLI can install source with Tailwind's standalone executable or an npm-based build. The current Tailwind baseline is `4.3.2`.
diff --git a/VERSIONING_STRATEGY.md b/VERSIONING_STRATEGY.md
index 6ab7987..0827b99 100644
--- a/VERSIONING_STRATEGY.md
+++ b/VERSIONING_STRATEGY.md
@@ -6,7 +6,7 @@ ShellUI uses one centralized version for the source templates, CLI tool, and pac
 
 | Scope | Value |
 |---|---|
-| Version | `0.4.0-alpha.3` (prerelease; latest stable `0.3.5`) |
+| Version | `0.4.0` (stable; previous stable `0.3.6`) |
 | Target framework | .NET 8 and .NET 10 (`ShellUI.Components` also .NET 9) |
 | Tailwind version | `4.3.2` |
 
@@ -19,13 +19,13 @@ The root `Directory.Build.props` supplies the version:
 ```xml
 <PropertyGroup>
   <ShellUIVersion>0.4.0</ShellUIVersion>
-  <ShellUIVersionSuffix>alpha.3</ShellUIVersionSuffix>
+  <ShellUIVersionSuffix></ShellUIVersionSuffix>
 </PropertyGroup>
 ```
 
 `Directory.Build.props` composes the package and assembly metadata:
 
-- `Version` becomes `0.4.0-alpha.3` with the suffix above, and `0.4.0` without one.
+- `Version` is `0.4.0` with the empty suffix above; a suffix such as `alpha.3` makes it `0.4.0-alpha.3`.
 - `AssemblyVersion` and `FileVersion` use the numeric base `0.4.0`.
 - `InformationalVersion` includes the prerelease suffix.
 - Component metadata reads the centralized properties when running from the repository. `VersionHelper` uses assembly metadata as a fallback when its repository search does not find the solution file.
@@ -57,7 +57,7 @@ The CLI writes the computed version into `shellui.json` for each installed entry
   "InstalledComponents": [
     {
       "Name": "button",
-      "Version": "0.4.0-alpha.3",
+      "Version": "0.4.0",
       "InstalledAt": "2026-01-01T00:00:00Z",
       "IsCustomized": false
     }
diff --git a/docs/CLI_INSTALLATION.md b/docs/CLI_INSTALLATION.md
index b4bd853..ecf0492 100644
--- a/docs/CLI_INSTALLATION.md
+++ b/docs/CLI_INSTALLATION.md
@@ -4,12 +4,11 @@
 
 | Context | Version |
 |---|---|
-| Latest stable (recommended) | `0.3.5`, needs the .NET 10 runtime |
-| Prerelease | `0.4.0-alpha.3`, install with `--version 0.4.0-alpha.3` |
-| Previous stable | `0.2.1` |
+| Latest stable (recommended) | `0.4.0` |
+| Previous stable | `0.3.6`, needs the .NET 10 runtime |
 | Tailwind | `4.3.2` |
 
-The tool runs on .NET 8 or later (`0.4.0-alpha.3` and the 0.3 line need the .NET 10 runtime). The projects it sets up can target .NET 8, 9 or 10.
+The tool runs on .NET 8 or later (the 0.3 line and the 0.4 prereleases need the .NET 10 runtime). The projects it sets up can target .NET 8, 9 or 10.
 
 ## Global installation
 
diff --git a/docs/CLI_SYNTAX.md b/docs/CLI_SYNTAX.md
index ded3ded..040222f 100644
--- a/docs/CLI_SYNTAX.md
+++ b/docs/CLI_SYNTAX.md
@@ -1,6 +1,6 @@
 # ShellUI CLI Syntax
 
-This reference covers CLI `0.4.0-alpha.3` (prerelease): it runs on .NET 8 or later (`0.4.0-alpha.3` itself needs .NET 10), sets up Blazor projects on .NET 8, 9 and 10, uses Tailwind CSS `4.3.2`, and has 98 direct component targets. Some options, such as `--dashboard`, are not in the stable 0.3.4; see the [v0.3.4 reference](https://github.com/shellui-dev/shellui/blob/v0.3.4/docs/CLI_SYNTAX.md) for that version.
+This reference covers CLI `0.4.0`: it runs on .NET 8 or later, sets up Blazor projects on .NET 8, 9 and 10, uses Tailwind CSS `4.3.2`, and has 98 direct component targets. For 0.3, see the [v0.3.6 reference](https://github.com/shellui-dev/shellui/blob/v0.3.6/docs/CLI_SYNTAX.md).
 
 ## Command prefix
 
@@ -306,7 +306,7 @@ Representative fields look like this:
   "InstalledComponents": [
     {
       "Name": "button",
-      "Version": "0.4.0-alpha.3",
+      "Version": "0.4.0",
       "InstalledAt": "2026-01-01T00:00:00Z",
       "IsCustomized": false
     }
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 934ae10..ed93b18 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -6,13 +6,13 @@ Answers for the current ShellUI source and the currently published packages.
 
 ### Which version should I use?
 
-Use the latest stable release, `0.3.5`. It uses Tailwind CSS `4.3.2`. The `0.4.0-alpha.3` prerelease, with 93 direct component targets, needs `--version 0.4.0-alpha.3`:
+Use the latest stable release, `0.4.0`. It uses Tailwind CSS `4.3.2` and has 98 direct component targets:
 
 ```bash
 dotnet tool install -g ShellUI.CLI
 ```
 
-The CLI runs on .NET 8 or later and works in Blazor projects on .NET 8, 9 and 10. The `ShellUI.Components` NuGet package targets .NET 8, 9 and 10. (`0.4.0-alpha.3` and the 0.3 line need .NET 10 for both.)
+The CLI runs on .NET 8 or later and works in Blazor projects on .NET 8, 9 and 10. The `ShellUI.Components` NuGet package targets .NET 8, 9 and 10. (The 0.3 line and the 0.4 prereleases need .NET 10 for both.)
 
 ### Which command prefix should I use?
 
@@ -145,7 +145,7 @@ A representative Tailwind and component record is:
   "InstalledComponents": [
     {
       "Name": "button",
-      "Version": "0.4.0-alpha.3",
+      "Version": "0.4.0",
       "InstalledAt": "2026-01-01T00:00:00Z",
       "IsCustomized": false
     }
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 3aa00aa..a42963e 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -1,6 +1,6 @@
 # ShellUI Quick Start
 
-This quick start uses ShellUI `0.4.0-alpha.3`, a prerelease, with Tailwind CSS `4.3.2`. The CLI runs on .NET 8 or later and works in Blazor projects on .NET 8, 9 and 10.
+This quick start uses ShellUI `0.4.0` with Tailwind CSS `4.3.2`. The CLI runs on .NET 8 or later and works in Blazor projects on .NET 8, 9 and 10.
 
 ## Prerequisites
 
@@ -20,7 +20,7 @@ dotnet --version
 A global tool is invoked as `shellui`:
 
 ```bash
-dotnet tool install -g ShellUI.CLI --version 0.4.0-alpha.3
+dotnet tool install -g ShellUI.CLI
 shellui --version
 ```
 
diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md
index 3db8059..79183dd 100644
--- a/docs/RELEASE_NOTES.md
+++ b/docs/RELEASE_NOTES.md
@@ -1,5 +1,67 @@
 # ShellUI Release Notes
 
+# ShellUI v0.4.0
+
+> The 0.4 stable release. Compared with 0.3 it adds 19 components and three sign-in page blocks, compositional parts for eight more, `shellui add all`, `doctor` and `migrate`, .NET 8 and 9 support, and a CLI that keeps your changes on `update`. This section sums up the whole 0.4 line; the alpha sections below have the details. Report issues via [GitHub Issues](https://github.com/shellui-dev/shellui/issues).
+
+## ✨ New in 0.4
+
+- **Components.** `kbd`, `aspect-ratio`, `button-group`, `toggle-group`, `input-group`, `number-input`, `stat-card`, `timeline`, `tree-view`, `qr-code`, `image-viewer`, `chat`, `chat-message` and `chat-input` (0.4.0-alpha.1), and since alpha.3:
+  - **`prompt-suggestions`**: clickable suggestion chips for an empty chat.
+  - **`reasoning`**: a collapsible block that streams a model's thinking, open while `IsStreaming` and folded to "Thought for N seconds" after.
+  - **`tool-call`**: a tool's name with a pending, running, done or error badge; it opens to show the arguments, result or error.
+  - **`field`**: label, control, description and validation message as one unit, vertical or horizontal; `For` shows the `EditForm`'s messages.
+  - **`json-viewer`**: a highlighted, foldable JSON tree from a string or any object, with a copy button.
+  - **`resizable`** is now a real panel group: `ResizablePanelGroup`, `ResizablePanel` (`DefaultSize`, `MinSize`, `MaxSize`) and `ResizableHandle`, dragged with the pointer or moved with the arrow keys, Home and End. The browser moves the panels and reports the sizes once, so dragging doesn't wait on Blazor Server. The old `Resizable` stays in the package, deprecated.
+- **Blocks.** `init --dashboard 01|02` wires a dashboard layout into the app, and the new `auth-01`, `auth-02` and `auth-03` blocks give apps that use ASP.NET Core Identity their own sign-in pages.
+- **Compositional parts** for AlertDialog, Breadcrumb, Command, Form, Menubar, Pagination, Sheet and Drawer. Each mode is opt-in, so existing markup keeps working.
+- **`SonnerService.Clear()`** and **`Destructive`** context menu items.
+- **.NET 8 and 9.** The CLI runs on .NET 8 or later, and `ShellUI.Components` targets .NET 8, 9 and 10. The 0.3 line needed .NET 10.
+
+## 🛠️ CLI
+
+- **`shellui add all`** installs every component except the page blocks; `--except` leaves out a component and everything that depends on it.
+- **`shellui doctor`** checks the project's setup and says how to fix each problem; it exits 1 on errors, so it can run in CI.
+- **`shellui migrate`** rewrites your pages for template API changes after `update`: `Input.InputVariant.X`, the DatePicker and TimePicker `Selected*` parameters and `Pagination.OnPageChange`. It shows each changed line and asks first (`--dry-run`, `--yes`), and points out `Calendar` handlers that need a `DateTime?`.
+- **`update` keeps your changes** and installs dependencies a component gained since you added it. **`add` never downgrades** a NuGet package. **`remove`** follows your `ComponentsPath`.
+- **One Tailwind CLI per machine** in `~/.shellui/bin`, with resumable downloads, instead of a copy in every project.
+- **Razor class libraries:** `init` recognises a library shared by several apps.
+
+## 🐛 Fixes since 0.4.0-alpha.3
+
+- **`add` hung on .NET 8 and 9 apps.** The CLI waited for `dotnet add package`, npm and Tailwind to exit before reading their output, so once a process wrote more than a pipe buffer both sides waited forever. `shellui add all` stopped on restoring Blazor-ApexCharts. Output is now read while the process runs.
+- **The CLI didn't start on a machine with only .NET 9** (or a newer runtime). It now rolls forward to any .NET 8 or later runtime.
+- **`doctor` said `app.css` was stale right after a build.** Tailwind skips writing unchanged output, so the file kept an old timestamp. The build now touches it; `update` brings the change to projects set up by alpha.2 and alpha.3.
+- **`list --installed`** said "0 available" (and `--available` "0 installed"). The summary now counts every target.
+- **Safelist:** classes passed to `Shell.Cn("…")` and literals in ternaries never reached `shellui-classes.txt`, so 198 classes were missing for apps that build their own Tailwind CSS from the package.
+- Everything fixed in 0.3.5 and 0.3.6 is included.
+
+## ⚠️ Breaking changes from 0.3
+
+- **`Calendar.SelectedDateChanged`** is `EventCallback<DateTime?>`. Handlers that take a `DateTime` must take a `DateTime?` (`shellui migrate` lists them).
+- **CLI templates, after `shellui update`:** `Input.InputVariant` is now `InputVariant` (new `input-variants` template); Stepper parts read the stepper's `ActiveStep` instead of a `CurrentStep` parameter; `ScrollArea` drops its `scrollbar-*` classes; `shellui add resizable` installs the panel group. `shellui migrate` fixes the `InputVariant` uses.
+- Still working but deprecated: `Pagination.OnPageChange`, `DatePicker.SelectedDate`, `TimePicker.SelectedTime` and the old `Resizable`. `shellui migrate` moves you off the first three.
+
+## ⬆️ Upgrading
+
+- **CLI:** `dotnet tool update -g ShellUI.CLI`, then in each project commit, run `shellui update`, then `shellui migrate`, and build. `shellui doctor` checks the result.
+- **NuGet package:** update `ShellUI.Components` to `0.4.0`. If you handle `Calendar.SelectedDateChanged`, change the handler's parameter to `DateTime?`.
+- If you used `Class="…!"` to beat a component's own classes, you can drop the `!`.
+
+## 📦 Installation
+
+```bash
+dotnet tool install -g ShellUI.CLI
+# or upgrade an existing install
+dotnet tool update -g ShellUI.CLI
+```
+
+```bash
+dotnet add package ShellUI.Components
+```
+
+**Full Changelog**: https://github.com/shellui-dev/shellui/compare/v0.3.6...v0.4.0
+
 # ShellUI v0.4.0-alpha.3 🧪
 
 > The third 0.4 prerelease. A component's `Class` now overrides its own classes, dialogs and sheets keep keyboard focus inside, `add` never downgrades your NuGet packages, and the CLI templates have been brought in line with the NuGet package, fixing several template bugs on the way. It also adds Razor class library support. It is a prerelease, so installs need `--version`. Report issues via [GitHub Issues](https://github.com/shellui-dev/shellui/issues).
diff --git a/src/ShellUI.Core/Models/ComponentMetadata.cs b/src/ShellUI.Core/Models/ComponentMetadata.cs
index 9a53608..152b9fe 100644
--- a/src/ShellUI.Core/Models/ComponentMetadata.cs
+++ b/src/ShellUI.Core/Models/ComponentMetadata.cs
@@ -66,7 +66,7 @@ private static string GetCurrentVersion()
         if (assemblyVersion != null)
             return assemblyVersion.InformationalVersion.Split('+')[0];
 
-        return "0.4.0-alpha.3";
+        return "0.4.0";
     }
 }
 
diff --git a/src/ShellUI.Templates/VersionHelper.cs b/src/ShellUI.Templates/VersionHelper.cs
index e3ac567..b54acaf 100644
--- a/src/ShellUI.Templates/VersionHelper.cs
+++ b/src/ShellUI.Templates/VersionHelper.cs
@@ -51,7 +51,7 @@ public static string GetCurrentVersion()
             return _cachedVersion;
         }
 
-        return "0.4.0-alpha.3";
+        return "0.4.0";
     }
 
     private static string? FindSolutionRoot()