diff --git a/SPEC.md b/SPEC.md
new file mode 100644
index 0000000..f9f3916
--- /dev/null
+++ b/SPEC.md
@@ -0,0 +1,798 @@
+# Smoothie — Architecture Specification
+
+**Status:** As-built (v0.1.2)
+**Scope:** Desktop application for discovering, installing, isolating, and launching Blender builds.
+**Audience:** Maintainers and contributors.
+
+---
+
+## 1. Overview
+
+Smoothie is a Tauri 2 desktop application that manages multiple Blender installations from a single, portable library folder.
+
+The application:
+
+- Discovers official Blender builds from `download.blender.org`.
+- Downloads and extracts builds into a user-configurable library.
+- Isolates each install's Blender user resources so versions and templates do not share configuration.
+- Launches Blender with per-install environment variables and optional application templates.
+- Registers builds with the operating system and creates desktop shortcuts (Linux).
+- Generates per-install icons and splash banners.
+- Keeps update, tray, notification, and window-state behavior in the Tauri host.
+
+### Goals
+
+1. **Portability.** All versions, configuration, and templates live under one library directory that can be moved, backed up, or copied.
+2. **Isolation.** Each Blender build reads and writes its own `BLENDER_USER_RESOURCES` directory.
+3. **Low-friction management.** Install, launch, favorite, delete, and set default from one GUI.
+4. **Desktop-native behavior.** Tray support, OS shortcuts, file associations, signed auto-updates.
+5. **Thin native layer.** Rust is used only for capabilities the webview cannot perform reliably.
+
+### Non-goals
+
+- Building or compiling Blender from source.
+- Hosting or mirroring Blender binaries.
+- Multi-user or cloud-synced library management.
+- Plugin/add-on marketplace functionality.
+- Mobile support (the Tauri entry point exists, but the capabilities and UX target desktop).
+
+---
+
+## 2. System Context
+
+```mermaid
+flowchart TB
+    User[User] --> UI[Svelte 5 UI]
+    UI --> Services[JS service modules]
+    Services --> Stores[Svelte stores]
+    Services --> TauriJS[Tauri JS APIs]
+    Services --> Commands[Rust commands]
+    TauriJS --> Plugins[Tauri plugins]
+    Plugins --> Net[download.blender.org]
+    Plugins --> OS[OS: dialogs, notifications, shell, tray]
+    Commands --> FS[(Local filesystem)]
+    Plugins --> FS
+    Commands --> Blender[Blender process]
+    Plugins --> Updater[Update endpoint]
+    FS --> Library[Portable Blender library]
+```
+
+Smoothie has no application server. The only runtime network dependencies are:
+
+- `https://download.blender.org` for release discovery and downloads.
+- The configured updater endpoint for signed application updates.
+
+---
+
+## 3. Technology Stack
+
+| Layer | Technology | Notes |
+| --- | --- | --- |
+| Desktop shell | Tauri 2 (Rust, edition 2021) | One window, one main process |
+| Frontend | SvelteKit 2 + Svelte 5 runes | `adapter-static`, prerendered, SSR disabled |
+| Bundler | Vite 6 | Fixed dev port `1420` |
+| Package manager | Bun | `bun.lock` committed |
+| UI | Hand-written CSS + `@webtui/css` | Splitpanes, tabs, custom components |
+| Persistence | `@tauri-apps/plugin-store` | `settings.json`, `versions.json` |
+| Downloads | `@tauri-apps/plugin-upload` | Streaming download with progress |
+| HTTP | `@tauri-apps/plugin-http` | Scoped to Blender hosts |
+| Filesystem | `@tauri-apps/plugin-fs` + persisted scope | Library and shortcut operations |
+| OS integration | dialog, os, shell, notification, opener, window-state | Linux shortcut creation in JS |
+| Updates | `@tauri-apps/plugin-updater` | Signed artifacts |
+| Archives | Rust crates: `zip`, `tar`, `flate2`, `xz2`, `bzip2` | Custom Tauri commands |
+
+---
+
+## 4. High-Level Architecture
+
+Smoothie is organized into four layers:
+
+```mermaid
+flowchart TB
+    subgraph Presentation
+        Routes[routes/+page.svelte]
+        Components[lib/components]
+        Styles[app.css and component styles]
+    end
+
+    subgraph Application
+        Settings[settings.js]
+        Fetch[blenderfetch.js]
+        Download[download.js]
+        Library[library.js]
+        FileUtils[file_utils.js]
+        Tray[trayicon.js]
+        Notify[notification.js]
+    end
+
+    subgraph PlatformBoundary
+        TauriAPI[Tauri core API]
+        TauriPlugins[Tauri plugins]
+        RustCommands[Rust commands]
+    end
+
+    subgraph State
+        SvelteStores[Svelte writable stores]
+        LazyStores[plugin-store JSON files]
+        Disk[Library filesystem]
+    end
+
+    Presentation --> Application
+    Application --> PlatformBoundary
+    Application --> SvelteStores
+    Application --> LazyStores
+    PlatformBoundary --> Disk
+```
+
+### Architectural principles
+
+1. **Filesystem-first.** The library directory is the source of truth for installed versions. There is no installation database to drift out of sync.
+2. **Stateless UI over persistent services.** Components read Svelte stores; service modules perform I/O and refresh stores.
+3. **Thin Rust boundary.** Rust handles archive extraction and process spawning. All orchestration and file layout remain in JavaScript.
+4. **Explicit per-version isolation.** Launches inject `BLENDER_USER_RESOURCES` pointing at a version-specific config folder.
+5. **Idempotent maintenance.** Missing icons, banners, templates, and shortcuts are regenerated when versions are rescanned.
+6. **Graceful degradation.** Missing executables are skipped; failed shortcuts and banners log warnings rather than aborting startup.
+
+---
+
+## 5. Repository Layout
+
+```text
+smoothie/
+├── src/                          # SvelteKit frontend
+│   ├── app.css                   # Global styles and theme variables
+│   ├── app.html                  # Webview shell document
+│   ├── routes/
+│   │   ├── +layout.js            # prerender = true, ssr = false
+│   │   ├── +layout.svelte
+│   │   └── +page.svelte          # Main application shell and bootstrap
+│   └── lib/
+│       ├── assets/               # Base icon and embedded font
+│       ├── components/           # UI components
+│       ├── blenderfetch.js       # Release discovery and filename parsing
+│       ├── download.js           # Download/extract pipeline
+│       ├── file_utils.js         # Icons, banners, paths, copy/move helpers
+│       ├── library.js            # Installed versions, launch, templates, shortcuts
+│       ├── notification.js       # Transient notification store
+│       ├── settings.js           # Settings, defaults, platform detection
+│       ├── transition.js         # Crossfade transition
+│       └── trayicon.js           # Tray menu and close-to-tray behavior
+├── src-tauri/
+│   ├── src/
+│   │   ├── lib.rs                # Commands and plugin registration
+│   │   └── main.rs               # Entry point
+│   ├── capabilities/desktop.json # Permissions and scopes
+│   ├── icons/                    # App and platform icons
+│   ├── Cargo.toml
+│   ├── build.rs
+│   └── tauri.conf.json           # App, window, bundle, updater config
+├── static/                       # Static web assets
+├── .gitea/workflows/build.yml    # Release build workflow
+├── package.json
+├── svelte.config.js
+└── vite.config.js
+```
+
+---
+
+## 6. Frontend Architecture
+
+### 6.1 Application shell
+
+`src/routes/+page.svelte` owns:
+
+- The splash screen and initialization sequence.
+- The top-level tab state (`library`, `download`, `settings`).
+- Subscription wiring between Svelte stores and component props.
+- Global CSS variables and layout.
+
+Bootstrap order:
+
+```mermaid
+sequenceDiagram
+    participant UI as +page.svelte
+    participant App as Tauri app API
+    participant Settings as settings.js
+    participant Fetch as blenderfetch.js
+    participant Library as library.js
+    participant Tray as trayicon.js
+
+    UI->>App: getVersion()
+    UI->>Settings: getSettings()
+    Settings->>Settings: detect platform/arch
+    Settings->>Settings: create library structure
+    UI->>Fetch: getBlenderReleases()
+    Fetch->>Fetch: scrape and parse release pages
+    UI->>Library: getInstalledVersions()
+    Library->>Library: scan library, find executables
+    Library->>Library: generate icons/banners, shortcuts
+    UI->>Tray: setupTrayIcon()
+    UI->>UI: subscribe stores and show main UI
+```
+
+Initialization is intentionally serial and surfaced through splash status text. No routing is used beyond the single route; tabs are local component state.
+
+### 6.2 Components
+
+| Component | Responsibility |
+| --- | --- |
+| `Library.svelte` | Two-pane view: installed/favorite versions on the left, templates for the selected version on the right |
+| `Download.svelte` | Lists major releases and their available minor versions |
+| `Release.svelte` | Per-release row: version selector, progress, download/installed state |
+| `VersionCard.svelte` | Version tile: favorite, select, launch, delete, set default |
+| `TemplateCard.svelte` | Launch base Blender or a template; delete template |
+| `Dropzone.svelte` | Accepts dropped `.blend` files as templates for the selected version |
+| `Settings.svelte` | Displays settings and moves the library directory |
+| `Splash.svelte` | Startup status display |
+| `Dialog.svelte` | Promise-based confirmation dialog (`show({...})`) |
+| `Popup.svelte` | Transient success/error toast |
+| `Menu.svelte`, `MenuItem.svelte` | Context menu primitives |
+| `Progress.svelte` | Download/extraction progress display |
+| `Button.svelte` | Shared button styles and variants |
+
+### 6.3 State management
+
+State is split into two categories:
+
+**In-memory Svelte stores**
+
+| Store | Module | Shape |
+| --- | --- | --- |
+| `currentSettings` | `settings.js` | `Settings` |
+| `installedVersionsStore` | `library.js` | `blenderVersion[]` |
+| `selectedVersionStore` | `library.js` | `blenderVersion \| null` |
+| `blenderReleases` | `blenderfetch.js` | `BlenderRelease[]` |
+| `downloadTasksStore` | `download.js` | `DownloadTask[]` |
+| `notification` | `notification.js` | `{ message, timeout } \| null` |
+
+**Persisted stores (`plugin-store`)**
+
+| File | Keys | Purpose |
+| --- | --- | --- |
+| `settings.json` | Setting names | User preferences |
+| `versions.json` | Version string → boolean | Favorite flags |
+
+The UI does not cache installed versions independently of `installedVersionsStore`; components rescan through `getInstalledVersions()` after mutations.
+
+### 6.4 Service modules
+
+#### `settings.js`
+
+- Defines the `Settings` type and defaults.
+- Detects host platform and architecture via `plugin-os`.
+- Persists settings through `LazyStore`.
+- Creates the library structure when the library directory changes.
+- Exposes `BASE_LIBRARY_DIR = "smoothie-library"`.
+
+#### `blenderfetch.js`
+
+- Fetches `https://download.blender.org/release/`.
+- Parses the index with `DOMParser`.
+- Selects version folders matching `Blender<version>/` and greater than `2.78`.
+- Fetches each version folder in parallel and parses filenames of the form:
+
+  ```text
+  blender-<version>-<platform>-<arch>.<extension>
+  ```
+
+- Filters to the selected platform and architecture.
+- Sorts releases with a numeric dot-segment comparator.
+- Emits `BlenderRelease[]` and `FileLink[]`.
+
+This module is deliberately source-specific. It is the only component that understands Blender's download directory naming convention.
+
+#### `download.js`
+
+Implements the install pipeline:
+
+```mermaid
+sequenceDiagram
+    participant UI as Release.svelte
+    participant DL as download.js
+    participant Store as plugin-upload
+    participant Rust as extract_archive
+    participant Lib as library.js
+
+    UI->>DL: downloadBlenderVersion(link)
+    DL->>DL: read settings and compute target dir
+    DL->>Store: download(url, target/archive)
+    loop progress
+        Store-->>DL: loaded / total
+        DL->>DL: updateDownloadProgress(version)
+    end
+    DL->>Rust: extract_archive(archive, target)
+    Rust->>Rust: spawn_blocking extraction
+    Rust->>Rust: strip single top-level directory
+    DL->>DL: remove archive unless keepDownloadedArchives
+    DL->>Lib: getInstalledVersions()
+    DL-->>UI: { success, message, path }
+```
+
+Key behaviors:
+
+- Target directory: `<libraryDir>/smoothie-library/blender/<version>`.
+- Progress is keyed by version string, not by task ID.
+- On download failure, an empty target directory is removed.
+- On extraction failure, the archive is retained and the error is returned.
+- Extraction is delegated to a single Rust command; the JS layer only decides retention and refresh.
+
+#### `library.js`
+
+The domain core. Responsibilities:
+
+- Scan `<library>/blender/*` and build `blenderVersion` objects.
+- Resolve the executable for the current platform.
+- Load templates and ensure template directories exist.
+- Generate missing icons and banners.
+- Create/remove Linux `.desktop` entries.
+- Launch Blender with isolated environment variables.
+- Register a build as the system default (`blender --register`).
+- Maintain favorites.
+- Delete versions and clean up associated resources.
+- Refresh `selectedVersionStore` after scans.
+
+#### `file_utils.js`
+
+- Canvas-based icon generation with the embedded base icon and `Europa-Mono` font.
+- Canvas/figlet-based 600×90 banner generation.
+- Directory creation, recursive copy, move, and existence checks.
+- Single-top-level-directory flattening.
+- `.blend` drag-and-drop import as templates.
+
+#### `trayicon.js`
+
+- Creates a tray icon with "Show/Hide" and "Quit".
+- Intercepts window close and hides to tray when `closeToTray` is enabled.
+
+#### `notification.js`
+
+- Tiny writable store consumed by `+page.svelte` and rendered through `Popup.svelte`.
+
+---
+
+## 7. Native (Rust) Layer
+
+`src-tauri/src/lib.rs` exposes seven commands and registers twelve plugins.
+
+### 7.1 Commands
+
+| Command | Signature | Behavior |
+| --- | --- | --- |
+| `extract_zip` | `(archive_path, target_dir)` | Extracts ZIP entries, creating parent directories |
+| `extract_tar` | `(archive_path, target_dir)` | Extracts uncompressed TAR |
+| `extract_tar_gz` | `(archive_path, target_dir)` | Extracts gzip-compressed TAR |
+| `extract_tar_xz` | `(archive_path, target_dir)` | Extracts xz-compressed TAR |
+| `extract_tar_bz2` | `(archive_path, target_dir)` | Extracts bzip2-compressed TAR |
+| `extract_archive` | `(archive_path, target_dir)` | Async dispatcher; detects format by filename; runs in `spawn_blocking` |
+| `launch_binary` | `(path, args, env?)` | Spawns a detached process with null stdio |
+
+Format detection in `extract_archive`:
+
+1. Multi-part suffixes: `.tar.xz` / `.txz`, `.tar.gz` / `.tgz`, `.tar.bz2` / `.tbz2` / `.tbz`.
+2. Single suffix: `.tar`, `.zip`.
+3. Unknown suffix: try ZIP, then uncompressed TAR.
+
+All archive extractors call `strip_single_top_level_directory`, which flattens an archive that produced exactly one directory. This is required because Blender archives contain a versioned wrapping folder.
+
+### 7.2 Plugins
+
+Registered in `lib.rs` and declared in the frontend dependency set:
+
+- `updater`, `upload`, `shell`, `fs`, `persisted-scope`, `store`, `os`, `notification`, `http`, `dialog`, `window-state`, `opener`.
+
+`window-state` is registered twice (once in the builder chain and once in `setup`); this is redundant but harmless and should be consolidated.
+
+### 7.3 Process model
+
+Blender is launched as a detached child process with:
+
+- `stdin`, `stdout`, `stderr` set to null.
+- Optional environment variables.
+- No process tracking or lifecycle supervision.
+
+Smoothie does not wait for Blender and does not receive exit status.
+
+---
+
+## 8. Data Model
+
+### 8.1 `Settings`
+
+```js
+{
+  libraryDir: string,              // user-visible library root
+  defaultPlatform: 'windows' | 'linux' | 'macos',
+  defaultArch: string,             // host architecture string
+  keepDownloadedArchives: boolean, // default false
+  autoCreateShortcuts: boolean,    // default true (Linux desktop entries)
+  theme: 'light' | 'dark',         // default 'light'
+  closeToTray: boolean             // default true
+}
+```
+
+Defaults are derived at runtime from `appDataDir()`, `plugin-os` platform, and `plugin-os` architecture. Missing persisted fields are patched from defaults on load.
+
+### 8.2 `BlenderRelease`
+
+```js
+{
+  original: string,      // original href, e.g. "Blender4.2/"
+  version: string,       // major series, e.g. "4.2"
+  fullPath: string,      // absolute folder URL
+  lastModified: null,    // reserved
+  links: FileLink[]
+}
+```
+
+### 8.3 `FileLink`
+
+```js
+{
+  version: string,       // full version, e.g. "4.2.1"
+  downloadUrl: string,
+  platform: 'linux' | 'windows' | 'macos',
+  architecture: 'x64' | 'arm64',
+  fileExtension: 'tar.xz' | 'zip' | ...,
+  status: 'pending' | 'downloading' | 'completed' | 'error',
+  percent: number
+}
+```
+
+### 8.4 `blenderVersion`
+
+```js
+{
+  version: string,
+  path: string,
+  executable: string,
+  platform: string,
+  favourite: boolean,
+  templates: string[]   // template folder names
+}
+```
+
+`installDate` is declared in the JSDoc but not populated.
+
+### 8.5 `DownloadTask`
+
+```js
+{
+  version: string,
+  loaded: number,
+  total: number,
+  percent: number
+}
+```
+
+---
+
+## 9. Storage Layout
+
+### 9.1 Library
+
+`BASE_LIBRARY_DIR = "smoothie-library"` is created under the configured `libraryDir`.
+
+```text
+<libraryDir>/
+└── smoothie-library/
+    ├── blender/
+    │   └── <version>/
+    │       ├── blender            # or blender.exe
+    │       ├── icon.png           # generated
+    │       ├── banner.png         # generated
+    │       ├── <major.minor>/
+    │       │   └── scripts/
+    │       │       └── startup/
+    │       │           └── bl_app_templates_system/
+    │       │               └── <Template>/
+    │       │                   ├── startup.blend
+    │       │                   └── banner.png
+    │       └── ...
+    └── config/
+        └── <version>/             # BLENDER_USER_RESOURCES
+```
+
+The `config/<version>` folder is what makes installations independent. Blender writes preferences, startup files, add-ons, and caches there instead of the user's global Blender configuration.
+
+### 9.2 OS artifacts
+
+| Platform | Artifact | Location |
+| --- | --- | --- |
+| Linux | Desktop entry | `$LOCALDATA/applications/blender-smoothie-<version>.desktop` |
+| Windows | No shortcut creation implemented | — |
+| macOS | No shortcut creation implemented | — |
+
+Desktop entries embed:
+
+- `BLENDER_USER_RESOURCES=<library>/config/<version>`
+- `BLENDER_CUSTOM_SPLASH_BANNER=<version>/banner.png`
+- `Icon=<version>/icon.png`
+- `MimeType=application/x-blender`
+
+### 9.3 Settings and favorites
+
+Both are managed by `plugin-store`:
+
+- `settings.json` — scalar key/value pairs.
+- `versions.json` — version string → favorite boolean.
+
+These files live in the Tauri-managed application data/config location, not in the portable library. Moving machines requires copying the library separately from these preferences.
+
+---
+
+## 10. Key Workflows
+
+### 10.1 Release discovery
+
+1. Fetch the release index.
+2. Parse anchors ending in `/` and matching `Blender<number><suffix>/`.
+3. Ignore versions at or below 2.78.
+4. Fetch every qualifying folder concurrently.
+5. Parse `blender-<version>-<platform>-<arch>.<ext>` filenames.
+6. Group by full version and select the entry matching the configured platform/architecture.
+7. Sort major series and minor versions descending.
+8. Publish results to `blenderReleases`.
+
+### 10.2 Install
+
+1. User selects a `FileLink` in the Download tab.
+2. `downloadBlenderVersion` resolves the target directory.
+3. `plugin-upload` streams the archive into that directory.
+4. Progress updates are written to `downloadTasksStore` keyed by version.
+5. `invoke('extract_archive')` runs extraction off the UI thread.
+6. The single top-level directory is flattened.
+7. The archive is deleted unless `keepDownloadedArchives` is true.
+8. `getInstalledVersions()` rescans the library and regenerates artifacts.
+9. The release row flips to "Installed".
+
+### 10.3 Launch
+
+1. User clicks the version tag, double-clicks a card, or launches a template.
+2. Smoothie verifies the executable with `stat`.
+3. It computes the isolated config path.
+4. It selects the banner: version banner or template banner.
+5. For a template, it passes `--app-template <name>`.
+6. It invokes `launch_binary` with:
+   - `BLENDER_USER_RESOURCES=<library>/config/<version>`
+   - `BLENDER_CUSTOM_SPLASH_BANNER=<banner.png>`
+
+### 10.4 Templates
+
+- Template directories live inside the installed Blender build, not the config directory.
+- A template is valid when it contains `startup.blend`.
+- Built-in directories (`Storyboarding`, `2D_Animation`, `Sculpting`, `VFX`, `Video_Editing`) are ignored.
+- Dropping a `.blend` copies it into a new template directory as `startup.blend`.
+- Template deletion removes the directory recursively.
+- Template banners are generated lazily.
+
+### 10.5 Favorites and selection
+
+- Favorites are toggled in memory and persisted immediately.
+- On scan, the previously selected version is refreshed by version string.
+- If nothing is selected:
+  - Prefer the first favorite.
+  - Otherwise select the first installed version.
+
+### 10.6 Delete
+
+1. Remove the version directory recursively.
+2. Remove the favorite entry.
+3. Remove the Linux desktop entry.
+4. Reset any download-progress entry.
+5. Update the in-memory installed list.
+
+### 10.7 Set default
+
+`registerVersion` invokes `launch_binary` with `--register`, letting Blender register `.blend` file associations. The result of the invocation is not awaited or reported.
+
+### 10.8 Move library
+
+Implemented in `Settings.svelte`:
+
+1. Validate the destination is not inside the current library and vice versa.
+2. Optionally confirm replacement of an existing destination.
+3. Remove Linux desktop entries for current versions.
+4. Attempt `rename`; fall back to recursive copy + delete for cross-device moves.
+5. Persist the new `libraryDir`.
+6. Rescan and recreate shortcuts.
+
+### 10.9 Tray and window lifecycle
+
+- Closing the window hides it when `closeToTray` is true.
+- Tray menu toggles visibility and can destroy the window.
+- Window size and position are persisted by `window-state`.
+- Default window is 1024×576, resizable, bounded to 512×288 minimum and 1920×1080 maximum.
+
+---
+
+## 11. Platform Integration
+
+### Linux (primary, most complete)
+
+- `.desktop` entries created and removed automatically.
+- Orphaned entries cleaned up during scans.
+- `BLENDER_USER_RESOURCES` and splash banner configured in the entry.
+- Archives typically `.tar.xz`.
+
+### Windows (partial)
+
+- Executable name: `blender.exe`.
+- Archives typically `.zip`.
+- No Start Menu or desktop shortcut creation.
+- File association delegated to `blender --register`.
+
+### macOS (partial)
+
+- Platform mapping is `darwin → macos`.
+- Download links use the `macos` filename segment.
+- Executable discovery currently expects `<version>/blender`, while a standard macOS bundle places it at `Blender.app/Contents/MacOS/Blender`.
+- No `.app` or Dock integration.
+
+### Architecture handling
+
+- Download selection maps `x86_64 → x64` and `arm64 → arm64`.
+- Settings detection returns the raw OS architecture value.
+- The two mappings are not fully aligned (for example, `aarch64` is not normalized to `arm64`), which can cause missing download matches on ARM Linux.
+
+---
+
+## 12. Security and Capabilities
+
+### Current posture
+
+- The webview loads only bundled local content.
+- HTTP is scoped to `https://*.blender.org`.
+- Filesystem access is scoped to app directories plus persisted paths granted through the directory picker.
+- The updater uses a Minisign public key and signed artifacts.
+
+Relevant capability entry points in `src-tauri/capabilities/desktop.json`:
+
+- Window show/hide/close/destroy.
+- Dialog open and confirm.
+- App-scoped read/write, recursive.
+- FS scope for `$LOCALDATA/applications`.
+- Shell spawn.
+- HTTP for `*.blender.org`.
+- Store, OS, notification, upload, updater.
+
+### Security considerations
+
+1. **CSP is disabled** (`app.security.csp = null`). Tightening it is advisable now that the frontend is fully bundled.
+2. **`launch_binary` accepts an arbitrary path and arguments** from the frontend. The trust boundary is the local webview, but an allowlist or explicit launch token would reduce blast radius if UI content were ever compromised.
+3. **No checksum verification** is performed on downloaded Blender archives. `.md5` and `.sha256` files are explicitly ignored during parsing.
+4. **Archive extraction** uses `mangled_name()` for ZIP entries, which normalizes traversal paths; TAR extraction relies on the `tar` crate's safety checks.
+5. **Persisted scope** keeps directory grants across restarts; this is intentional for library access but should be reviewed when the library moves.
+6. **Updater artifacts** must remain signed; the private key is provided only to CI.
+
+---
+
+## 13. Build, Packaging, and Release
+
+### Local development
+
+```bash
+bun install
+bun run tauri dev
+```
+
+- Vite serves on `localhost:1420`.
+- `src-tauri` is excluded from Vite file watching.
+- Tauri runs `bun run dev` before development and `bun run build` before production builds.
+
+### Frontend build
+
+- `adapter-static` prerenders the single route.
+- `ssr = false` because Tauri has no Node server.
+- Output is written to `build/` and bundled by Tauri.
+
+### Packaging
+
+- `bundle.targets = "all"`.
+- `createUpdaterArtifacts = true`.
+- Icons for Linux, Windows, macOS, Android, and iOS are present, though desktop is the supported target.
+
+### Release workflow
+
+`.gitea/workflows/build.yml`:
+
+- Triggers on pushes to `master`.
+- Builds on `ubuntu-22.04`.
+- Installs Bun, Rust stable, and Linux system dependencies.
+- Invokes a Tauri action that publishes a draft Gitea release tagged `app-v__VERSION__`.
+- Signs update artifacts via CI secrets.
+- Uploads artifacts to `https://git.floatingpoint.ch`.
+
+### Update configuration
+
+- Endpoint: `https://git.floatingpoint.ch/valerio/smoothie/releases/download/latest/update.json`.
+- Signed with a Minisign key embedded in `tauri.conf.json`.
+
+---
+
+## 14. Reliability, Concurrency, and Error Handling
+
+### Current behavior
+
+- Service functions generally return `{ success, message, path? }` rather than throwing to the UI.
+- Known recoverable failures are logged with `console.warn`.
+- Downloads are tracked by version string, so two concurrent installs of the same version would collide.
+- There is no global install queue or lock.
+- Partial extraction leaves files behind; only a completely empty target directory is cleaned after a download failure.
+- Store writes are immediate but not transactional across multiple keys.
+- Installed-version scanning treats the filesystem as authoritative and tolerates malformed version folders by skipping them.
+- A missing executable causes the version folder to be skipped, with removal commented out.
+
+### Recommended invariants for future work
+
+1. One active operation per version.
+2. Install state machine: `idle → downloading → verifying → extracting → finalizing → installed | failed`.
+3. Atomic finalize: extract to a temporary directory, then rename into place.
+4. Cleanup of partial state on failure.
+5. Explicit cancellation through an operation ID.
+
+---
+
+## 15. Known Limitations and Architectural Risks
+
+| Area | Issue | Impact |
+| --- | --- | --- |
+| Release discovery | HTML scraping with regexes tied to current site markup | Breaks if Blender changes its index or filenames |
+| Release discovery | Fetches every major-version folder on every launch; no cache | Startup latency and N+1 requests |
+| Downloads | No checksum or signature verification | Supply-chain risk |
+| Downloads | No cancellation despite a "Cancel" label | Confusing UX and orphaned work |
+| Extraction | Not atomic; failure can leave partial installs | Library can contain unusable versions |
+| Concurrency | No per-version lock or queue | Duplicate downloads and progress collisions |
+| macOS | Executable discovery does not handle `.app` bundles | macOS installations are likely unusable |
+| Architecture | `aarch64` is not normalized to `arm64` consistently | ARM Linux builds may not appear |
+| Launch | Detached processes are not tracked | No exit status, crash detection, or running indicator |
+| Registration | `--register` result is not awaited | UI may report success without confirmation |
+| Portability | Settings and favorites live outside the library | Full setup is not completely portable |
+| Security | CSP disabled; arbitrary binary launch command | Hardening opportunity |
+| Testing | No automated tests or test harness | Regressions rely on manual verification |
+| Versioning | `package.json` and `tauri.conf.json` are `0.1.2`; `Cargo.toml` is `0.1.0` | Inconsistent release metadata |
+| Version scan | `exists()` is not awaited in one guard | Incorrect truthiness for missing library paths |
+| Window state | Plugin is registered twice | Redundant initialization |
+
+---
+
+## 16. Extension Points
+
+The architecture anticipates the following extensions without structural change:
+
+- **Additional download sources / mirrors.** Add a source adapter that produces `BlenderRelease[]`.
+- **Checksum verification.** Add a verification step between download and extraction.
+- **Install queue.** Introduce an operation manager keyed by version, with cancellation and persisted job state.
+- **Platform-specific shortcut adapters.** Extend the current Linux-only `.desktop` logic with Windows `.lnk` and macOS `.app`/alias handling.
+- **Typed domain layer.** Migrate JSDoc types to TypeScript and define a typed IPC contract.
+- **Library manifest.** Add an optional manifest for migration, integrity checks, and machine-readable provenance while keeping the filesystem authoritative.
+- **Plugin management.** Extend the library model with per-version add-on directories and enable/disable state.
+- **Template metadata.** Store display names, descriptions, and thumbnails alongside `startup.blend`.
+
+---
+
+## 17. Architectural Invariants
+
+These should remain true unless the architecture is deliberately revised:
+
+1. No installed-version state is stored outside the library except user preferences and favorites.
+2. Each Blender launch receives a version-specific `BLENDER_USER_RESOURCES`.
+3. Every installed version is discoverable by scanning `<library>/smoothie-library/blender`.
+4. Rust remains a capability layer, not a business-logic layer.
+5. Release discovery and installation are separate stages, joined by `FileLink`.
+6. UI state flows from stores; components do not maintain duplicate authoritative copies.
+7. Network access remains limited to Blender hosts and the updater endpoint.
+8. The library remains relocatable and transferable as a directory tree.
+
+---
+
+## 18. Glossary
+
+| Term | Meaning |
+| --- | --- |
+| Library | `<libraryDir>/smoothie-library`, the portable root containing builds and configs |
+| Build / Version | An extracted Blender installation under `blender/<version>` |
+| Template | A folder containing `startup.blend`, launchable via `--app-template` |
+| Favorite | User-marked version persisted in `versions.json` |
+| Default version | The build registered with the OS via `blender --register` |
+| Config isolation | Per-version `BLENDER_USER_RESOURCES` directory |
+| Splash banner | Generated PNG passed through `BLENDER_CUSTOM_SPLASH_BANNER` |