Add doctor/update commands, dry-run/print-config, and improve icon fallback

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,92 @@
+name: Bug report
+description: Report incorrect behavior, regressions, or build/install failures
+title: "[bug] "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting an issue. Please provide enough detail to reproduce the problem.
+  - type: dropdown
+    id: issue_area
+    attributes:
+      label: Area
+      description: Which area best fits this issue?
+      options:
+        - distro-compat
+        - integration
+        - icons
+        - architecture/runtime
+        - ci
+        - docs
+        - other
+    validations:
+      required: true
+  - type: input
+    id: deskify_version
+    attributes:
+      label: Deskify version
+      description: For example `v0.1.0-alpha.2` or commit SHA
+      placeholder: v0.1.0-alpha.2
+    validations:
+      required: true
+  - type: input
+    id: distro
+    attributes:
+      label: Linux distribution
+      description: Include distro + version
+      placeholder: Fedora 41 / Arch Linux / Ubuntu 24.04
+    validations:
+      required: true
+  - type: input
+    id: desktop_environment
+    attributes:
+      label: Desktop environment / session
+      description: Include DE/WM and Wayland/X11 if relevant
+      placeholder: GNOME (Wayland), KDE Plasma (X11), Hyprland
+  - type: textarea
+    id: command
+    attributes:
+      label: Command used
+      description: Exact command that triggered the issue
+      placeholder: |
+        deskify build --url "https://example.com" --name "Example"
+      render: bash
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior / error output
+      description: Paste the relevant error message or describe what happened
+    validations:
+      required: true
+  - type: textarea
+    id: repro_steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Install prerequisites...
+        2. Run `deskify ...`
+        3. Observe ...
+    validations:
+      required: true
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I checked the README/known limitations and prerequisites
+          required: true
+        - label: I included distro/environment details
+          required: true
+        - label: I included the exact command and error output
+          required: true
+

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Deskify README
+    url: https://github.com/spalencsar/deskify/blob/master/README.md
+    about: Check installation requirements, known limitations, usage examples, and release notes first.
+  - name: Contributing Guide
+    url: https://github.com/spalencsar/deskify/blob/master/CONTRIBUTING.md
+    about: Read local checks, smoke-test guidance, and contribution expectations before opening work-related issues/PRs.
+  - name: Maintainer Notes (Labels / Triage)
+    url: https://github.com/spalencsar/deskify/blob/master/docs/maintainer-notes.md
+    about: Reference label categories and alpha-phase triage conventions.

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,72 @@
+name: Feature request
+description: Suggest a user-facing improvement, integration idea, or architectural direction
+title: "[feature] "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion. Feature requests are most helpful when they describe the problem first, then the proposed solution.
+  - type: dropdown
+    id: request_area
+    attributes:
+      label: Area
+      description: Which area best fits this request?
+      options:
+        - integration
+        - icons
+        - architecture/runtime
+        - distro-compat
+        - docs
+        - ci
+        - other
+    validations:
+      required: true
+  - type: checkboxes
+    id: design_signal
+    attributes:
+      label: Design impact
+      description: Tick this if the request changes long-term project direction
+      options:
+        - label: This likely affects architecture or long-term product direction (`design decision`)
+          required: false
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What problem are you trying to solve?
+      placeholder: |
+        I want to ...
+        The current limitation is ...
+    validations:
+      required: true
+  - type: textarea
+    id: proposed_solution
+    attributes:
+      label: Proposed solution
+      description: Describe the behavior/API/CLI change you would like to see
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What are you doing today, or what other options did you consider?
+      placeholder: PWAs, Flatpak web apps, manual `.desktop` entries, etc.
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope / rollout thoughts (optional)
+      description: If relevant, suggest MVP scope or phased rollout
+      placeholder: Could start as..., later evolve into...
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I described the problem, not only the implementation idea
+          required: true
+        - label: I checked existing issues/discussions for duplicates
+          required: true
+

.github/workflows/release.yml

@@ -4,6 +4,7 @@ on:
   push:
     tags:
       - "v*"
+  workflow_dispatch:
 
 permissions:
   contents: write

CHANGELOG.md

@@ -7,6 +7,21 @@ and this project follows early MVP/alpha versioning with tags like `v0.1.0-alpha
 
 ## [Unreleased]
 
+### Added
+- `build --no-decorations` option to create frameless windows (`decorations: false`) for kiosk/dashboard-style setups
+- README screenshots for KDE/Arch showing launcher integration, running app window, and `deskify list` workflow
+
+### Fixed
+- Icon handling now normalizes downloaded and custom icons to RGBA PNG before Tauri build (prevents `icon ... is not RGBA` build failures)
+
+## [v0.1.0-alpha.2] - 2026-02-23
+
+### Fixed
+- Resolved a CI failure caused by Clippy (`items_after_test_module`) by moving the test module to the end of `src/main.rs`
+
+### Changed
+- No functional CLI behavior changes; this is a release/CI correctness follow-up to `v0.1.0-alpha.1`
+
 ## [v0.1.0-alpha.1] - 2026-02-23
 
 ### Added

CONTRIBUTING.md

@@ -46,6 +46,10 @@ cargo test
 cargo check
 ```
 
+## Maintainer Notes (Repo Meta / Triage)
+
+Maintainers can use `docs/maintainer-notes.md` for the current label strategy and issue triage conventions during the alpha phase.
+
 ## Manual Smoke Test (Recommended for Behavior Changes)
 
 If your change affects build/install/list/remove behavior, run a quick smoke test:

Makefile

@@ -0,0 +1,5 @@
+REPO ?= spalencsar/deskify
+
+.PHONY: labels
+labels:
+	./scripts/setup-github-labels.sh $(REPO)

README.md

@@ -1,8 +1,8 @@
 <h1 align="center">deskify</h1>
 
 <p align="center">
-  <b>A blazing fast, lightweight Nativefier alternative written in Rust & Tauri.</b><br>
-  Instantly turn any website or web app into a native, standalone Linux desktop application.
+  <b>Turn websites into first-class Linux desktop applications with Rust, Tauri, and the system WebView.</b><br>
+  Build native-feeling, standalone web app wrappers with CLI-first Linux integration.
 </p>
 
 <p align="center">
@@ -12,32 +12,127 @@
   <img src="https://img.shields.io/badge/Status-Alpha-yellow?style=flat-square" alt="Alpha status" />
 </p>
 
+<p align="center">
+  <img src="docs/assets/chat-kde.png" alt="Deskify app window running chat.com on KDE Plasma" width="49%" />
+  <img src="docs/assets/chat-launcher-kde.png" alt="Deskify app visible in KDE launcher" width="49%" />
+</p>
+
+<p align="center">
+  <img src="docs/assets/deskify-list-terminal.png" alt="deskify list terminal output" width="80%" />
+</p>
+
+<p align="center"><sub>Screenshots: KDE Plasma on Arch Linux (alpha MVP workflow).</sub></p>
+
 ---
 
-## ⚡ Why deskify?
+## Why Deskify Exists
 
-The original [Nativefier](https://github.com/nativefier/nativefier) project (Node.js/Electron) was an incredible tool, but it is now unmaintained and deprecated. Furthermore, packaging an entire Chromium V8 engine for *every single web app* you create consumes massive amounts of RAM and disk space.
+Web apps are now core tools, but Linux desktops still treat them like second-class citizens.
 
-**deskify** solves this by leveraging [Tauri](https://tauri.app/). Instead of bundling a heavy browser engine, it uses your native system webview (e.g., `webkit2gtk` on Linux). 
+- Electron-based wrappers solve distribution, but often at high RAM/disk cost.
+- PWAs help in some browsers, but desktop integration is inconsistent across environments.
+- The original [Nativefier](https://github.com/nativefier/nativefier) proved the need, but it is now unmaintained.
 
-## 🚧 Project Status (Alpha / Early MVP)
+`deskify` takes a Linux-first approach: it turns a website into a native-feeling desktop app using [Tauri](https://tauri.app/) and the system webview (for example `webkit2gtk`) instead of bundling a full browser engine per app.
+
+## Problem Fit (Why Deskify vs. Other Approaches)
+
+Deskify is optimized for Linux users who want native desktop integration and CLI-friendly automation for web apps, without shipping a bundled browser runtime per app.
+
+The comparison below is intentionally rough and practical (not benchmark marketing). It describes tradeoffs, not winners in every category.
+
+| Approach | Runtime model | Desktop integration | Automation / scripting | Isolation / sandbox | Setup complexity | Offline capability |
+| --- | --- | --- | --- | --- | --- | --- |
+| Electron / Nativefier | Bundled Chromium per app | Good | Low to medium | Per-app process, app-bundled runtime | Easy to medium | Depends on the site |
+| PWA | Browser runtime | Limited / browser-dependent | Low | Shared browser context | Very easy | Depends on browser + site |
+| Flatpak web app models | Sandbox-oriented runtime model | Good | Limited | Strong sandbox model | Medium | Depends on runtime + site |
+| **Deskify** | System WebView | Native (`.desktop`, icons, WMClass) | **High (CLI-first)** | Medium (shared system WebView security model) | Medium (Tauri prerequisites) | Depends on the site |
+
+### Deskify Focus (Today)
+
+Deskify focuses on:
+
+- system-native Linux desktop integration
+- minimal runtime overhead by relying on the system WebView
+- automation-friendly CLI workflows
+- straightforward local install/remove lifecycle management
+
+Deskify intentionally does not aim to:
+
+- replace full browser sandbox products
+- provide a cross-platform abstraction layer
+- ship bundled browser runtimes per generated app
+
+## How Deskify Works Today (Alpha / MVP)
 
 `deskify` is ready for public use and testing as an **early MVP**, but it is **not production-hardened yet**.
 
 - **Platform scope:** Linux only
-- **Build model:** `deskify` compiles a local Tauri wrapper app on your machine
-- **First build can take a while:** Rust crates + Tauri build steps may need to compile
-- **Test coverage:** currently limited (core behavior is implemented, but automated coverage is still growing)
+- **Current architecture:** one generated Tauri wrapper project per app
+- **Build model:** `deskify` compiles the wrapper locally on your machine
+- **Why this MVP design:** simpler debugging, isolated failures, low contributor complexity
+- **Tradeoff:** build time and distro-specific setup issues become user-facing
+- **Test coverage:** currently limited (core behavior is implemented, automated coverage is growing)
+
+### MVP Architecture (Today)
+
+```mermaid
+flowchart TD
+    A[deskify CLI] --> B[Generate temporary Tauri wrapper project]
+    B --> C[Fetch or copy icon]
+    C --> D[Write tauri.conf.json + source files]
+    D --> E[Run cargo tauri build locally]
+    E --> F[Install binary to local executable dir]
+    F --> G[Install icon + .desktop entry]
+    G --> H[Launch from Linux app menu]
+```
 
 ### Known Limitations
+
 - Requires Tauri/Linux system dependencies to be installed locally before `deskify build`
 - Generated app build success can vary by distro/system setup (WebKitGTK/Tauri prerequisites)
 - No official cross-platform support (Windows/macOS) yet
 - GitHub Releases / binary automation for `deskify` itself may lag behind source updates during early MVP
 
-### 🌟 Features
-- **Extremely Lightweight:** Generated binaries are tiny (~4-6 MB) and RAM consumption is minimal.
+## Where Deskify Is Going
+
+Deskify aims to make web applications **first-class Linux desktop applications**.
+
+Planned evolution (direction, not promise):
+
+- Shared runtime model for multiple apps
+- Per-app config and icon installs without full rebuilds
+- Stronger Linux desktop integration (deployment, automation, kiosk/admin workflows)
+- Better distro compatibility guidance and troubleshooting
+
+The current per-app build approach is intentional for the MVP. The goal is to keep it simple now while making the longer-term direction visible.
+
+### Planned Evolution (Concept)
+
+```mermaid
+flowchart TD
+    A[deskify CLI] --> B[deskify runtime binary]
+    A --> C[App config files]
+    A --> D[Icons + .desktop entries]
+    C --> E[apps/chatgpt.json]
+    C --> F[apps/netflix.json]
+    B --> G[Load app config at launch]
+    G --> H[Open site in system webview]
+    D --> I[Linux app menu integration]
+```
+
+## Why Not Just Use Flatpak Web Apps / PWAs / Electron?
+
+The table above covers the technical tradeoffs in more detail. In practice, `deskify` is most useful when you want:
+
+- a CLI-first workflow for repeatable installs and automation
+- Linux-native desktop integration (`.desktop`, icons, window class behavior)
+- a system-WebView-based runtime model instead of shipping a bundled browser per app
+
+### Key Features
+- **System-WebView Runtime Model:** Generated wrappers stay small because Deskify relies on the system WebView instead of bundling a browser runtime per app.
 - **Automatic Icon Fetching:** Scrapes high-quality 128x128 favicons automatically using the Google Favicon API.
+- **Layered Icon Fallbacks:** Tries site-provided icons first (`<link rel="icon">`, `/favicon.ico`), then falls back to the Google Favicon API, then a dummy icon.
 - **XDG-Compliant System Integration:** Safely creates `.desktop` entries in `~/.local/share/applications` and manages application icons in `~/.local/share/icons/hicolor/`.
 - **Wayland/X11 Ready:** Perfectly binds `StartupWMClass` to ensure your DE groups the app exactly to its custom icon (no generic gear icons in GNOME/KDE taskbars).
 - **Kiosk / Fullscreen Mode:** Pin applications perfectly as dashboards.
@@ -127,11 +222,37 @@ deskify build \
   --height 720
 ```
 
+Frameless example (without fullscreen):
+
+```bash
+deskify build \
+  --url "https://chat.com" \
+  --name "Chat" \
+  --no-decorations \
+  --width 1200 \
+  --height 800
+```
+
+Preview the generated Tauri config without building/installing:
+
+```bash
+deskify build --url "https://chat.com" --name "Chat" --print-config
+```
+
+Preview planned actions only (dry run):
+
+```bash
+deskify build --url "https://chat.com" --name "Chat" --dry-run
+```
+
 * `--icon <PATH>`: Provide a custom PNG icon instead of auto-downloading one.
 * `--fullscreen`: Starts the app in Kiosk mode.
+* `--no-decorations`: Disables native window decorations (frameless window; useful for dashboards/kiosk setups).
 * `--user-agent <UA>`: Useful to bypass webview restrictions on certain platforms.
 * `--dark-mode`: Forces the Tauri webview into a dark theme.
 * `--width <PX>` / `--height <PX>`: Sets the startup resolution.
+* `--print-config`: Prints the generated `tauri.conf.json` and exits.
+* `--dry-run`: Shows planned actions without building/installing.
 
 ### Managing Apps (`list` & `remove`)
 You can view all applications generated by `deskify`:
@@ -139,6 +260,7 @@ You can view all applications generated by `deskify`:
 deskify list
 ```
 *Output:*
+
 ```text
 Installed Deskify Apps:
 - ChatGPT (Internal ID: chatgpt)
@@ -152,6 +274,31 @@ deskify remove chatgpt
 
 `remove` expects this **internal ID** (sanitized lowercase letters, numbers, `-`), not the display name.
 
+### Updating Apps (`update`)
+
+Rebuild and reinstall an existing app ID without manually running `remove` + `build`:
+
+```bash
+deskify update chat --url "https://chat.com" --name "Chat" --no-decorations
+```
+
+Alpha note: `update` currently requires `--url` because Deskify does not persist app URLs/config metadata yet.
+
+You can also preview an update:
+
+```bash
+deskify update chat --url "https://chat.com" --dry-run
+deskify update chat --url "https://chat.com" --print-config
+```
+
+### Diagnostics (`doctor`)
+
+Check local prerequisites and common environment issues (Rust/Cargo, `cargo tauri`, `pkg-config`, directories):
+
+```bash
+deskify doctor
+```
+
 ---
 
 ## 🧪 Manual Smoke Test Checklist (Before a Public Release)
@@ -179,7 +326,7 @@ Expected: clean validation error and no unintended file deletion.
 - Start with **source-first** releases (repository + tags)
 - Add automated binary releases later via GitHub Actions
 
-For the first public launch, tagging `v0.1.0-alpha.1` is a sensible default.
+For the current public alpha, use `v0.1.0-alpha.2` (and continue with `v0.1.0-alpha.N` for follow-up releases).
 
 ---
 

docs/github-labels.json

@@ -0,0 +1,72 @@
+[
+  {
+    "name": "architecture/runtime",
+    "color": "5319E7",
+    "description": "Runtime model, shared runtime, config-based apps, install model evolution"
+  },
+  {
+    "name": "distro-compat",
+    "color": "D93F0B",
+    "description": "Distro-specific build/runtime issues and environment differences"
+  },
+  {
+    "name": "integration",
+    "color": "0E8A16",
+    "description": "Desktop integration topics (.desktop, icons, launchers, window class behavior)"
+  },
+  {
+    "name": "icons",
+    "color": "FBCA04",
+    "description": "Favicon fetching, icon parsing, icon quality, and fallback behavior"
+  },
+  {
+    "name": "good first issue",
+    "color": "7057FF",
+    "description": "Scoped tasks suitable for first-time contributors"
+  },
+  {
+    "name": "needs testing",
+    "color": "BFDADC",
+    "description": "Behavior change needs manual or wider validation across systems"
+  },
+  {
+    "name": "design decision",
+    "color": "1D76DB",
+    "description": "Affects long-term architecture or product direction"
+  },
+  {
+    "name": "docs",
+    "color": "0075CA",
+    "description": "README, CONTRIBUTING, examples, troubleshooting, and release notes"
+  },
+  {
+    "name": "bug",
+    "color": "D73A4A",
+    "description": "Incorrect behavior or regression"
+  },
+  {
+    "name": "enhancement",
+    "color": "A2EEEF",
+    "description": "Feature or improvement request"
+  },
+  {
+    "name": "ci",
+    "color": "C5DEF5",
+    "description": "GitHub Actions, release workflows, and build checks"
+  },
+  {
+    "name": "feature",
+    "color": "84B6EB",
+    "description": "User-facing functionality addition (release note category)"
+  },
+  {
+    "name": "fix",
+    "color": "E99695",
+    "description": "Behavior correction or bug fix (release note category)"
+  },
+  {
+    "name": "chore",
+    "color": "FEF2C0",
+    "description": "Maintenance tasks and non-user-facing housekeeping"
+  }
+]

docs/maintainer-notes.md

@@ -0,0 +1,46 @@
+# Maintainer Notes
+
+This document captures lightweight repo-management conventions for `deskify` during the alpha/MVP phase.
+
+## Issue Labels (Recommended)
+
+Use labels to make project direction visible and to reduce triage friction.
+
+- `architecture/runtime` - runtime model, shared runtime, config-based apps, install model evolution
+- `distro-compat` - distro-specific build/runtime issues (WebKitGTK, packaging prerequisites, environment differences)
+- `integration` - desktop integration topics (`.desktop`, icons, launchers, window class behavior)
+- `icons` - favicon fetching, icon parsing, icon quality/fallback behavior
+- `good first issue` - scoped tasks suitable for first-time contributors
+- `needs testing` - behavior change needs manual or wider validation across systems
+- `design decision` - issue/PR affects long-term architecture or product direction
+- `docs` - README, CONTRIBUTING, examples, troubleshooting, release notes
+- `bug` - incorrect behavior or regression
+- `enhancement` - feature or improvement request
+- `ci` - GitHub Actions, release workflows, build checks
+
+Label definitions for GitHub setup are stored in `docs/github-labels.json`.
+If you use GitHub CLI, `scripts/setup-github-labels.sh <owner/repo>` will create/update them.
+
+## Triage Heuristics (Alpha)
+
+- Prefer labeling directionally first (`architecture/runtime`, `distro-compat`, `integration`) before priority.
+- Use `design decision` early when a discussion can create long-term constraints.
+- Add `needs testing` to changes that touch build/install/remove flows or desktop integration behavior.
+- Distinguish user-environment issues from code bugs (`distro-compat` + details) to avoid misclassifying support reports.
+
+## Release Notes Categories (Suggested Mapping)
+
+- `feature`, `enhancement` -> user-facing functionality additions
+- `fix`, `bug` -> behavior corrections and regressions
+- `docs` -> documentation changes
+- `chore`, `ci` -> maintenance and pipeline work
+
+## Maintainer Framing (README / Issues)
+
+During alpha, consistently frame Deskify as:
+
+- a Linux-first web app integration tool
+- an early MVP with intentional per-app build architecture
+- a project with a visible evolution path toward runtime/config-based installs
+
+This helps avoid "Nativefier clone" framing as the default community label.

scripts/setup-github-labels.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v gh >/dev/null 2>&1; then
+  echo "Error: GitHub CLI ('gh') is not installed." >&2
+  exit 1
+fi
+
+repo="${1:-}"
+labels_file="${2:-docs/github-labels.json}"
+
+if [[ -z "${repo}" ]]; then
+  echo "Usage: $0 <owner/repo> [labels-json-path]" >&2
+  echo "Example: $0 spalencsar/deskify" >&2
+  exit 1
+fi
+
+if [[ ! -f "${labels_file}" ]]; then
+  echo "Error: labels file not found: ${labels_file}" >&2
+  exit 1
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "Error: 'jq' is required to read ${labels_file}." >&2
+  exit 1
+fi
+
+echo "Syncing labels to ${repo} using ${labels_file} ..."
+
+jq -c '.[]' "${labels_file}" | while IFS= read -r label; do
+  name="$(jq -r '.name' <<<"${label}")"
+  color="$(jq -r '.color' <<<"${label}")"
+  description="$(jq -r '.description' <<<"${label}")"
+
+  if gh label edit "${name}" --repo "${repo}" --color "${color}" --description "${description}" >/dev/null 2>&1; then
+    echo "Updated: ${name}"
+  else
+    gh label create "${name}" --repo "${repo}" --color "${color}" --description "${description}" >/dev/null
+    echo "Created: ${name}"
+  fi
+done
+
+echo "Done."

src/main.rs

@@ -1,6 +1,7 @@
 use anyhow::{Context, Result, anyhow};
 use clap::{Parser, Subcommand};
 use directories::BaseDirs;
+use image::{DynamicImage, ImageFormat};
 use regex::Regex;
 use serde_json::{Map, Value, json};
 use std::fs;
@@ -10,6 +11,19 @@ use std::process::Command;
 use tempfile::tempdir;
 use url::Url;
 
+#[derive(Debug, Clone)]
+struct BuildArgs {
+    url: String,
+    name: String,
+    icon: Option<String>,
+    fullscreen: bool,
+    no_decorations: bool,
+    user_agent: Option<String>,
+    width: Option<f64>,
+    height: Option<f64>,
+    dark_mode: bool,
+}
+
 /// Deskify - Turn any URL into a native Linux desktop application using Tauri.
 #[derive(Parser, Debug)]
 #[command(author, version, about, long_about = None)]
@@ -38,6 +52,10 @@ enum Commands {
         #[arg(short, long)]
         fullscreen: bool,
 
+        /// Disable native window decorations (frameless window)
+        #[arg(long)]
+        no_decorations: bool,
+
         /// Set a custom User-Agent string for the webview
         #[arg(short = 'A', long)]
         user_agent: Option<String>,
@@ -53,14 +71,73 @@ enum Commands {
         /// Force the webview into Dark Mode
         #[arg(short, long)]
         dark_mode: bool,
+
+        /// Print the generated Tauri config JSON and exit
+        #[arg(long)]
+        print_config: bool,
+
+        /// Show planned build/install actions without building or installing
+        #[arg(long)]
+        dry_run: bool,
     },
     /// List all installed apps created by deskify
     List,
+    /// Check local prerequisites and environment diagnostics
+    Doctor,
     /// Remove a specific app by its internal ID
     Remove {
         /// The safe name/ID of the app (e.g., "youtube")
         id: String,
     },
+    /// Rebuild and reinstall an existing app ID with new settings (alpha: URL is required)
+    Update {
+        /// The existing internal ID (e.g., "chatgpt")
+        id: String,
+
+        /// The URL to wrap (required in current alpha because URLs are not persisted yet)
+        #[arg(short, long)]
+        url: String,
+
+        /// Optional new display name (defaults to current desktop entry name or the ID)
+        #[arg(short, long)]
+        name: Option<String>,
+
+        /// Optional path to a custom icon (PNG format is recommended)
+        #[arg(short, long)]
+        icon: Option<String>,
+
+        /// Launch the application in fullscreen (Kiosk) mode
+        #[arg(short, long)]
+        fullscreen: bool,
+
+        /// Disable native window decorations (frameless window)
+        #[arg(long)]
+        no_decorations: bool,
+
+        /// Set a custom User-Agent string for the webview
+        #[arg(short = 'A', long)]
+        user_agent: Option<String>,
+
+        /// Set the initial window width
+        #[arg(short = 'W', long)]
+        width: Option<f64>,
+
+        /// Set the initial window height
+        #[arg(short = 'H', long)]
+        height: Option<f64>,
+
+        /// Force the webview into Dark Mode
+        #[arg(short, long)]
+        dark_mode: bool,
+
+        /// Show planned update actions without rebuilding/installing
+        #[arg(long)]
+        dry_run: bool,
+
+        /// Print the generated Tauri config JSON for the updated app and exit
+        #[arg(long)]
+        print_config: bool,
+    },
 }
 
 fn sanitize_app_id(name: &str) -> String {
@@ -86,12 +163,154 @@ fn validate_remove_id(id: &str) -> Result<()> {
     }
 }
 
+fn build_tauri_config_value(args: &BuildArgs, safe_identifier: &str, bundle_active: bool) -> Value {
+    let mut window_config = Map::<String, Value>::new();
+    window_config.insert("title".to_string(), json!(args.name));
+    window_config.insert("url".to_string(), json!(args.url));
+
+    if args.fullscreen {
+        window_config.insert("fullscreen".to_string(), json!(true));
+    }
+    if args.no_decorations {
+        window_config.insert("decorations".to_string(), json!(false));
+    }
+    if let Some(ua) = &args.user_agent {
+        window_config.insert("userAgent".to_string(), json!(ua));
+    }
+    if let Some(w) = args.width {
+        window_config.insert("width".to_string(), json!(w));
+    }
+    if let Some(h) = args.height {
+        window_config.insert("height".to_string(), json!(h));
+    }
+    if args.dark_mode {
+        window_config.insert("theme".to_string(), json!("Dark"));
+    }
+
+    json!({
+        "$schema": "https://schema.tauri.app/config/2",
+        "productName": args.name,
+        "version": "0.1.0",
+        "identifier": format!("com.deskify.{}", safe_identifier),
+        "build": {
+            "frontendDist": "dist"
+        },
+        "app": {
+            "windows": [Value::Object(window_config)],
+            "security": { "csp": null }
+        },
+        "bundle": {
+            "active": bundle_active,
+            "targets": "all",
+            "icon": ["icons/icon.png"]
+        }
+    })
+}
+
+fn print_generated_config(args: &BuildArgs) -> Result<()> {
+    let safe_identifier = sanitize_app_id(&args.name);
+    let config = build_tauri_config_value(args, &safe_identifier, false);
+    println!(
+        "{}",
+        serde_json::to_string_pretty(&config).context("Failed to serialize generated config")?
+    );
+    Ok(())
+}
+
+fn print_build_plan(action: &str, args: &BuildArgs, existing_id: Option<&str>) {
+    let safe_name = sanitize_app_id(&args.name);
+    println!("{} plan:", action);
+    if let Some(id) = existing_id {
+        println!("- Existing app ID: {}", id);
+    }
+    println!("- URL: {}", args.url);
+    println!("- Name: {}", args.name);
+    println!("- New internal ID: {}", safe_name);
+    println!("- Local build: cargo tauri build (temporary generated project)");
+    println!("- Install targets: local binary + XDG icon + .desktop entry");
+    if args.fullscreen {
+        println!("- Window: fullscreen enabled");
+    }
+    if args.no_decorations {
+        println!("- Window: native decorations disabled");
+    }
+}
+
 fn is_deskify_desktop_entry(content: &str) -> bool {
     content.contains("X-Deskify-Managed=true")
         || (content.contains("Categories=Network;WebBrowser;")
             && (content.contains(".local/bin/") || content.contains("deskify")))
 }
 
+fn write_rgba_png(img: DynamicImage, output_path: &Path) -> Result<()> {
+    // Tauri expects PNG icons in RGBA format; many favicons are palette/LA/ICO etc.
+    let rgba = img.to_rgba8();
+    let rgba_img = DynamicImage::ImageRgba8(rgba);
+    rgba_img
+        .save_with_format(output_path, ImageFormat::Png)
+        .with_context(|| format!("Failed to write RGBA PNG icon to {}", output_path.display()))?;
+    Ok(())
+}
+
+fn download_icon_from_url(icon_url: &str, output_path: &Path) -> Result<bool> {
+    let response = match ureq::get(icon_url).call() {
+        Ok(resp) => resp,
+        Err(_) => return Ok(false),
+    };
+    let mut bytes = Vec::new();
+    if response.into_reader().read_to_end(&mut bytes).is_err() || bytes.is_empty() {
+        return Ok(false);
+    }
+    let img = match image::load_from_memory(&bytes) {
+        Ok(img) => img,
+        Err(_) => return Ok(false),
+    };
+    write_rgba_png(img, output_path)?;
+    Ok(true)
+}
+
+fn extract_icon_candidates_from_html(base_url: &Url, html: &str) -> Vec<String> {
+    let link_re = Regex::new(r#"(?is)<link\s+[^>]*rel\s*=\s*["'][^"']*icon[^"']*["'][^>]*href\s*=\s*["']([^"']+)["'][^>]*>"#).unwrap();
+    let mut candidates = Vec::new();
+    for cap in link_re.captures_iter(html) {
+        if let Some(href) = cap.get(1)
+            && let Ok(joined) = base_url.join(href.as_str())
+        {
+            let candidate = joined.to_string();
+            if !candidates.contains(&candidate) {
+                candidates.push(candidate);
+            }
+        }
+    }
+    candidates
+}
+
+fn try_download_site_icon(website_url: &str, output_path: &Path) -> Result<bool> {
+    let base_url = match Url::parse(website_url) {
+        Ok(url) => url,
+        Err(_) => return Ok(false),
+    };
+
+    let mut html = String::new();
+    if let Ok(response) = ureq::get(website_url).call()
+        && response.into_reader().read_to_string(&mut html).is_ok()
+    {
+        for icon_url in extract_icon_candidates_from_html(&base_url, &html) {
+            if download_icon_from_url(&icon_url, output_path)? {
+                return Ok(true);
+            }
+        }
+    }
+
+    if let Ok(favicon_url) = base_url.join("/favicon.ico")
+        && download_icon_from_url(favicon_url.as_str(), output_path)?
+    {
+        return Ok(true);
+    }
+
+    Ok(false)
+}
+
 fn fetch_or_create_icon(
     website_url: &str,
     custom_icon: Option<&String>,
@@ -99,8 +318,9 @@ fn fetch_or_create_icon(
 ) -> Result<()> {
     if let Some(icon_path) = custom_icon {
         if Path::new(icon_path).exists() {
-            fs::copy(icon_path, output_path)
-                .with_context(|| format!("Failed to copy custom icon from {}", icon_path))?;
+            let img = image::open(icon_path)
+                .with_context(|| format!("Failed to read custom icon image from {}", icon_path))?;
+            write_rgba_png(img, output_path)?;
             return Ok(());
         } else {
             eprintln!(
@@ -110,19 +330,19 @@ fn fetch_or_create_icon(
         }
     }
 
+    if try_download_site_icon(website_url, output_path)? {
+        return Ok(());
+    }
+
     if let Ok(parsed_url) = Url::parse(website_url)
         && let Some(host) = parsed_url.host_str()
     {
-        println!("Downloading icon for {}...", host);
+        println!("Falling back to Google favicon API for {}...", host);
         let api_url = format!("https://www.google.com/s2/favicons?domain={}&sz=128", host);
-        if let Ok(response) = ureq::get(&api_url).call() {
-            let mut bytes = Vec::new();
-            if response.into_reader().read_to_end(&mut bytes).is_ok() && !bytes.is_empty() {
-                fs::write(output_path, bytes).context("Failed to write downloaded icon to disk")?;
+        if download_icon_from_url(&api_url, output_path)? {
             return Ok(());
         }
     }
-    }
 
     // Fallback to a transparent dummy icon
     let dummy_png: [u8; 67] = [
@@ -137,18 +357,7 @@ fn fetch_or_create_icon(
     Ok(())
 }
 
-#[allow(clippy::too_many_arguments)]
-fn generate_project(
-    url: &str,
-    name: &str,
-    icon: Option<&String>,
-    fullscreen: bool,
-    user_agent: Option<&String>,
-    width: Option<f64>,
-    height: Option<f64>,
-    dark_mode: bool,
-    project_dir: &Path,
-) -> Result<()> {
+fn generate_project(args: &BuildArgs, project_dir: &Path) -> Result<()> {
     let src_dir = project_dir.join("src");
     fs::create_dir_all(&src_dir).context("Failed to create src directory")?;
 
@@ -193,7 +402,7 @@ fn main() {
     fs::write(src_dir.join("main.rs"), main_rs).context("Failed to write src/main.rs")?;
 
     // 4. tauri.conf.json
-    let safe_identifier = sanitize_app_id(name);
+    let safe_identifier = sanitize_app_id(&args.name);
 
     let dist_dir = project_dir.join("dist");
     fs::create_dir_all(&dist_dir).context("Failed to create dist directory")?;
@@ -206,48 +415,9 @@ fn main() {
     let icons_dir = project_dir.join("icons");
     fs::create_dir_all(&icons_dir).context("Failed to create icons directory")?;
 
-    fetch_or_create_icon(url, icon, &icons_dir.join("icon.png"))?;
+    fetch_or_create_icon(&args.url, args.icon.as_ref(), &icons_dir.join("icon.png"))?;
 
-    let mut window_config = Map::<String, Value>::new();
-    window_config.insert("title".to_string(), json!(name));
-    window_config.insert("url".to_string(), json!(url));
-
-    if fullscreen {
-        window_config.insert("fullscreen".to_string(), json!(true));
-    }
-    if let Some(ua) = user_agent {
-        window_config.insert("userAgent".to_string(), json!(ua));
-    }
-    if let Some(w) = width {
-        window_config.insert("width".to_string(), json!(w));
-    }
-    if let Some(h) = height {
-        window_config.insert("height".to_string(), json!(h));
-    }
-    if dark_mode {
-        window_config.insert("theme".to_string(), json!("Dark"));
-    }
-
-    let tauri_conf = json!({
-        "$schema": "https://schema.tauri.app/config/2",
-        "productName": name,
-        "version": "0.1.0",
-        "identifier": format!("com.deskify.{}", safe_identifier),
-        "build": {
-            "frontendDist": "dist"
-        },
-        "app": {
-            "windows": [Value::Object(window_config)],
-            "security": {
-                "csp": null
-            }
-        },
-        "bundle": {
-            "active": false,
-            "targets": "all",
-            "icon": ["icons/icon.png"]
-        }
-    });
+    let tauri_conf = build_tauri_config_value(args, &safe_identifier, false);
     fs::write(
         project_dir.join("tauri.conf.json"),
         serde_json::to_string_pretty(&tauri_conf).context("Failed to serialize tauri.conf.json")?,
@@ -403,6 +573,107 @@ fn list_apps() -> Result<()> {
     Ok(())
 }
 
+fn read_installed_app_display_name(id: &str) -> Result<Option<String>> {
+    validate_remove_id(id)?;
+    let base_dirs = BaseDirs::new().ok_or_else(|| anyhow!("Could not find system BaseDirs"))?;
+    let desktop_path = base_dirs
+        .data_local_dir()
+        .join("applications")
+        .join(format!("{}.desktop", id));
+    if !desktop_path.exists() {
+        return Ok(None);
+    }
+    let content = fs::read_to_string(&desktop_path)
+        .with_context(|| format!("Failed to read desktop entry {}", desktop_path.display()))?;
+    if !is_deskify_desktop_entry(&content) {
+        return Ok(None);
+    }
+    let name = content
+        .lines()
+        .find(|line| line.starts_with("Name="))
+        .and_then(|line| line.strip_prefix("Name="))
+        .map(str::to_string);
+    Ok(name)
+}
+
+fn run_doctor() -> Result<()> {
+    let mut failed = false;
+
+    let checks = vec![
+        ("cargo", vec!["--version"], true),
+        ("rustc", vec!["--version"], true),
+        ("pkg-config", vec!["--version"], false),
+    ];
+
+    println!("Deskify doctor");
+    println!("-------------");
+
+    for (cmd, args, critical) in checks {
+        match Command::new(cmd).args(args).output() {
+            Ok(output) if output.status.success() => {
+                let version = String::from_utf8_lossy(&output.stdout).trim().to_string();
+                println!("[ok] {} {}", cmd, version);
+            }
+            _ => {
+                println!(
+                    "[{}] {} not found or failed",
+                    if critical { "fail" } else { "warn" },
+                    cmd
+                );
+                if critical {
+                    failed = true;
+                }
+            }
+        }
+    }
+
+    match Command::new("cargo").args(["tauri", "--version"]).output() {
+        Ok(output) if output.status.success() => {
+            println!("[ok] {}", String::from_utf8_lossy(&output.stdout).trim());
+        }
+        _ => {
+            println!(
+                "[fail] cargo tauri not available (install with: cargo install tauri-cli --version \"^2.0.0\")"
+            );
+            failed = true;
+        }
+    }
+
+    if let Ok(output) = Command::new("pkg-config")
+        .args(["--modversion", "webkit2gtk-4.1"])
+        .output()
+    {
+        if output.status.success() {
+            println!(
+                "[ok] webkit2gtk-4.1 {}",
+                String::from_utf8_lossy(&output.stdout).trim()
+            );
+        } else {
+            println!("[warn] webkit2gtk-4.1 not found via pkg-config");
+        }
+    }
+
+    let base_dirs = BaseDirs::new().ok_or_else(|| anyhow!("Could not find system BaseDirs"))?;
+    let executable_dir = base_dirs
+        .executable_dir()
+        .map(|p| p.to_path_buf())
+        .unwrap_or_else(|| base_dirs.home_dir().join(".local/bin"));
+    let applications_dir = base_dirs.data_local_dir().join("applications");
+    let icons_dir = base_dirs
+        .data_local_dir()
+        .join("icons/hicolor/128x128/apps");
+    println!("[info] executable dir: {}", executable_dir.display());
+    println!("[info] applications dir: {}", applications_dir.display());
+    println!("[info] icons dir: {}", icons_dir.display());
+
+    if failed {
+        Err(anyhow!("Doctor found critical issues"))
+    } else {
+        println!("Doctor completed: no critical issues detected.");
+        Ok(())
+    }
+}
+
 fn remove_app(safe_name: &str) -> Result<()> {
     validate_remove_id(safe_name)?;
 
@@ -449,36 +720,25 @@ fn remove_app(safe_name: &str) -> Result<()> {
     Ok(())
 }
 
-fn main() -> Result<()> {
-    let cli = Cli::parse();
+fn execute_build(args: &BuildArgs, dry_run: bool, print_config: bool) -> Result<()> {
+    if print_config {
+        print_generated_config(args)?;
+        return Ok(());
+    }
+    if dry_run {
+        print_build_plan("Build", args, None);
+        return Ok(());
+    }
 
-    match cli.command {
-        Commands::Build {
-            url,
-            name,
-            icon,
-            fullscreen,
-            user_agent,
-            width,
-            height,
-            dark_mode,
-        } => {
-            println!("Generating native app '{}' for URL: {}", name, url);
+    println!(
+        "Generating native app '{}' for URL: {}",
+        args.name, args.url
+    );
 
     let dir = tempdir().context("Failed to create temporary directory for building")?;
     println!("Scaffolding Tauri project in {:?}", dir.path());
 
-            generate_project(
-                &url,
-                &name,
-                icon.as_ref(),
-                fullscreen,
-                user_agent.as_ref(),
-                width,
-                height,
-                dark_mode,
-                dir.path(),
-            )?;
+    generate_project(args, dir.path())?;
 
     let bin_path = match build_project(dir.path()) {
         Ok(path) => path,
@@ -488,14 +748,102 @@ fn main() -> Result<()> {
         }
     };
 
-            install_app(&name, &bin_path, dir.path())?;
+    install_app(&args.name, &bin_path, dir.path())?;
+    Ok(())
+}
+
+fn execute_update(id: &str, args: &BuildArgs, dry_run: bool, print_config: bool) -> Result<()> {
+    validate_remove_id(id)?;
+
+    if print_config {
+        print_generated_config(args)?;
+        return Ok(());
+    }
+    if dry_run {
+        print_build_plan("Update", args, Some(id));
+        println!(
+            "- Update action: remove existing app '{}' and reinstall",
+            id
+        );
+        return Ok(());
+    }
+
+    println!("Updating app '{}' -> '{}' ({})", id, args.name, args.url);
+    remove_app(id)?;
+    execute_build(args, false, false)
+}
+
+fn main() -> Result<()> {
+    let cli = Cli::parse();
+
+    match cli.command {
+        Commands::Build {
+            url,
+            name,
+            icon,
+            fullscreen,
+            no_decorations,
+            user_agent,
+            width,
+            height,
+            dark_mode,
+            print_config,
+            dry_run,
+        } => {
+            let args = BuildArgs {
+                url,
+                name,
+                icon,
+                fullscreen,
+                no_decorations,
+                user_agent,
+                width,
+                height,
+                dark_mode,
+            };
+            execute_build(&args, dry_run, print_config)?;
         }
         Commands::List => {
             list_apps()?;
         }
+        Commands::Doctor => {
+            run_doctor()?;
+        }
         Commands::Remove { id } => {
             remove_app(&id)?;
         }
+        Commands::Update {
+            id,
+            url,
+            name,
+            icon,
+            fullscreen,
+            no_decorations,
+            user_agent,
+            width,
+            height,
+            dark_mode,
+            dry_run,
+            print_config,
+        } => {
+            let resolved_name = if let Some(name) = name {
+                name
+            } else {
+                read_installed_app_display_name(&id)?.unwrap_or_else(|| id.clone())
+            };
+            let args = BuildArgs {
+                url,
+                name: resolved_name,
+                icon,
+                fullscreen,
+                no_decorations,
+                user_agent,
+                width,
+                height,
+                dark_mode,
+            };
+            execute_update(&id, &args, dry_run, print_config)?;
+        }
     }
 
     Ok(())