docs: update install and quick start pages

sites/docs-devsy-sh/pages/getting-started/install.mdx

@@ -7,11 +7,17 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import CodeBlock from '@theme/CodeBlock';
 
-Choose either [Devsy Desktop](#install-devsy) or the [Devsy CLI](#install-devsy-cli).
+Devsy comes in two forms that share the same workflow:
 
-## Install Devsy
+- **Devsy Desktop** — a guided app for creating and managing workspaces. Start here if you want a UI.
+- **Devsy CLI** — the same workflow from a terminal, for automation and scripting.
+
+Install either one below, then head to the [Quick Start](../quickstart/quickstart.mdx).
+
+## Install Devsy Desktop
+
+Download the build for your platform:
 
-Download Devsy Desktop:
 - [macOS Silicon/ARM](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_mac_arm64.dmg)
 - [macOS Intel/AMD](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_mac_x64.dmg)
 - [Windows](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_win_x64.exe)
@@ -20,42 +26,25 @@ Download Devsy Desktop:
 - [Linux RPM (Fedora/RHEL/openSUSE)](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_linux_x86_64.rpm)
 - [Linux Flatpak](https://github.com/devsy-org/devsy/releases/latest/download/Devsy.flatpak)
 
-:::info Previous Releases
-For earlier versions, visit the [GitHub releases page](https://github.com/devsy-org/devsy/releases)
-:::
-
-:::info Linux Packages
-The AppImage is tested on:
+For earlier versions, see the [GitHub releases page](https://github.com/devsy-org/devsy/releases).
 
-- Debian 12 and newer
-- Ubuntu 22.04 and newer
-- Fedora 36 and newer
-- openSUSE Leap 15.3 and newer
-- openSUSE Tumbleweed
-- Arch Linux
+:::info Linux dependencies
+The DEB and RPM packages declare their runtime dependencies; the AppImage and Flatpak bundle theirs. Most modern desktop distros run the AppImage as-is (tested on Debian 12+, Ubuntu 22.04+, Fedora 36+, openSUSE Leap 15.3+, Tumbleweed, and Arch).
 
-Most modern desktop distros include the required libraries. If the AppImage fails to launch, install FUSE and the standard GTK/Electron runtime libs:
+If the AppImage fails to launch, install FUSE and the GTK/Electron runtime libraries:
 
 - Debian/Ubuntu: `sudo apt-get install libfuse2 libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 xdg-utils libatspi2.0-0`
 - Fedora: `sudo dnf install fuse-libs gtk3 libnotify nss libXScrnSaver libXtst xdg-utils at-spi2-core`
 - openSUSE: `sudo zypper in libfuse2 gtk3 libnotify4 mozilla-nss libXss1 libXtst6 xdg-utils`
 :::
 
-:::info Windows Packages
-Make sure you have the following dependencies installed for the Desktop App to work:
-
-- [WebView 2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/?form=MA13LH)
-
-WebView 2 ships with recent versions of Windows. Install it only if you hit issues.
-:::
-
-:::info Linux Packaging
-Devsy publishes `.deb`, `.rpm`, `.AppImage`, and Flatpak builds. The DEB and RPM packages declare their runtime dependencies; the AppImage and Flatpak bundle theirs.
+:::info Windows dependency
+Devsy Desktop needs [WebView 2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/?form=MA13LH). It ships with recent versions of Windows — install it only if the app fails to open.
 :::
 
 ## Install Devsy CLI
 
-The Devsy CLI manages Devsy from a terminal. Choose an installation method below, or install it later from the Desktop App.
+Run the command for your platform. You can also install the CLI later from Devsy Desktop.
 
 <Tabs values={[
           {label: 'MacOS Silicon/ARM', value: 'macarm64'},
@@ -103,3 +92,13 @@ curl -L -o devsy "https://github.com/devsy-org/devsy/releases/latest/download/de
 
 </TabItem>
 </Tabs>
+
+Confirm the CLI is on your `PATH`:
+
+```bash
+devsy --version
+```
+
+## Next step
+
+Create your first workspace in the [Quick Start](../quickstart/quickstart.mdx).

sites/docs-devsy-sh/pages/quickstart/quickstart.mdx

@@ -5,95 +5,93 @@ sidebar_label: Quick Start
 
 import AddProvider from '../fragments/add-provider.mdx'
 
-This guide walks you from a fresh install to a running workspace using either the Devsy Desktop application or the Devsy CLI. Make sure you have installed [Devsy](../getting-started/install.mdx) on your system first.
+Go from a fresh install to a running workspace in three steps: add a provider, start a workspace, and open it in your editor. First, [install Devsy](../getting-started/install.mdx).
 
 ## Prerequisites
 
-Devsy connects your local editor to the workspace, so install the IDE you plan to use:
+Devsy connects a workspace to the editor you choose. Some paths run without any local install:
+
+- **VS Code Browser** (`--ide openvscode`) — opens in your browser, no local install.
+- **SSH / Vim / Neovim** (`--ide none`) — no local IDE; you connect over SSH.
+
+For a local editor, install the one you plan to use:
 
 - **VS Code** — [download VS Code](https://code.visualstudio.com/download).
-- **VS Code Browser** — no local install required; it opens in your browser.
-- **JetBrains (IntelliJ, GoLand, PyCharm, WebStorm, RustRover, RubyMine, CLion)** — install a [JetBrains IDE](https://www.jetbrains.com/) and [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/).
-- **SSH / Vim / Neovim** — no local IDE required; you connect to the workspace over SSH.
+- **JetBrains** (IntelliJ, GoLand, PyCharm, WebStorm, RustRover, RubyMine, CLion) — install a [JetBrains IDE](https://www.jetbrains.com/) and [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/).
 
-## Quick Start with Devsy Desktop
+## Devsy CLI
 
-### Add a Provider
+Fastest path to a running workspace. Make sure the [Devsy CLI](../getting-started/install.mdx#install-devsy-cli) is installed.
 
-<AddProvider />
+### 1. Add a provider
 
-### Start a Workspace
+A provider decides where workspaces run. Add local Docker:
 
-Navigate to 'Workspaces' > '+ Create' to launch the workspace wizard. Step through:
+```
+devsy provider add docker
+```
 
-1. **Provider** – pick an initialized provider.
-2. **Source** – enter your project URL or choose one of the quickstart templates.
-3. **IDE** – pick how you want to open the workspace:
-   - **VS Code** – opens VS Code locally, connected to the dev container.
-   - **VS Code Browser** – opens VS Code in your browser, connected to the dev container.
-   - **JetBrains** – opens your chosen JetBrains IDE through JetBrains Gateway.
-   - **None** – skip opening an IDE and connect over SSH (use this for Vim/Neovim or a plain SSH session).
-4. **Review** – confirm the configuration.
-5. **Launch** – start the workspace.
+For other backends, see [Add a Devsy Provider](../managing-providers/add-provider.mdx).
 
-The wizard streams logs as Devsy starts the workspace. Once it's ready, your chosen IDE opens connected to the dev container.
+### 2. Start a workspace
 
-:::info JetBrains Gateway
-If you selected a JetBrains IDE, JetBrains Gateway opens automatically with a prefilled form for the workspace. Press **Check Connection and Continue** without changing any configuration to start the IDE inside the workspace.
-:::
+Point Devsy at a repository and choose how to open it with `--ide`:
 
-### Connect over SSH
+```
+# VS Code in the browser
+devsy workspace up github.com/microsoft/vscode-remote-try-node --ide openvscode
 
-If you selected **None**, connect to the workspace over SSH once it's running:
+# VS Code, locally
+devsy workspace up github.com/microsoft/vscode-remote-try-node --ide vscode
+
+# No IDE — connect over SSH
+devsy workspace up github.com/microsoft/vscode-remote-try-node --ide none
+```
+
+Devsy builds the dev container and opens your IDE connected to it. If you chose `--ide none`, connect over SSH:
 
 ```
 ssh WORKSPACE_NAME.devsy
 ```
 
-#### Vim / Neovim
+## Devsy Desktop
 
-After connecting, you have two options to start coding in Vim/Neovim:
+Prefer a UI? Make sure [Devsy Desktop](../getting-started/install.mdx) is installed.
 
-- **Netrw/SCP** — Vim/Neovim can edit remote files using [Netrw](https://www.vim.org/scripts/script.php?script_id=1075). Connect from within Vim with `:e scp://[user@]machine[[:#]port]/path`, or start Vim with `vim scp://[user@]machine[[:#]port]/path`. The Devsy logs give you the user/machine combination, usually in the form `WORKSPACE_NAME.devsy`.
-- **Your Vim config in the workspace** — because the target environment is a container, you can SSH in and install your Vim/Neovim configuration like you would on any new machine. Run the `ssh WORKSPACE_NAME.devsy` command Devsy prints after starting the workspace.
-
-:::info Environment variables
-To use environment variables in your `devcontainer.json` — for example, for dynamic control over the container image version — see [Environment variables in devcontainer.json](../developing-in-workspaces/environment-variables-in-devcontainer-json.mdx).
-:::
+### 1. Add a provider
 
-## Quick Start with the Devsy CLI
+<AddProvider />
 
-Make sure you have installed the [Devsy CLI](../getting-started/install.mdx#install-devsy-cli) on your system.
+### 2. Start a workspace
 
-### Add a Provider
+Go to **Workspaces** > **+ Create** to open the wizard:
 
-Add a provider (local Docker, for example):
+1. **Provider** — pick an initialized provider.
+2. **Source** — enter your repository URL or choose a quickstart template.
+3. **IDE** — choose how to open the workspace:
+   - **VS Code** — opens locally, connected to the dev container.
+   - **VS Code Browser** — opens in your browser, connected to the dev container.
+   - **JetBrains** — opens through JetBrains Gateway.
+   - **None** — connect over SSH (Vim/Neovim or a plain session).
+4. **Review** — confirm the configuration.
+5. **Launch** — start the workspace.
 
-```
-devsy provider add docker
-```
+The wizard streams logs as the workspace starts. When it's ready, your IDE opens connected to the dev container.
 
-:::info Other providers
-For more providers, take a look at [Add a Devsy Provider](../managing-providers/add-provider.mdx).
+:::info JetBrains Gateway
+If you chose a JetBrains IDE, Gateway opens with a prefilled form. Press **Check Connection and Continue** to start the IDE inside the workspace.
 :::
 
-### Start a Workspace
+### Connect over SSH
 
-Start a workspace, choosing how to open it with `--ide`:
+If you chose **None**, connect once the workspace is running:
 
 ```
-# Start in VS Code browser
-devsy workspace up github.com/microsoft/vscode-remote-try-node --ide openvscode
-
-# Start in VS Code
-devsy workspace up github.com/microsoft/vscode-remote-try-node --ide vscode
-
-# Start without an IDE
-devsy workspace up github.com/microsoft/vscode-remote-try-node --ide none
+ssh WORKSPACE_NAME.devsy
 ```
 
-If you selected an IDE, it should open automatically. Otherwise, connect to the workspace manually:
+For Vim/Neovim, either edit remote files over [Netrw](https://www.vim.org/scripts/script.php?script_id=1075) (`vim scp://WORKSPACE_NAME.devsy/path`) or SSH in and install your config as you would on any new machine.
 
-```
-ssh WORKSPACE_NAME.devsy
-```
+:::info Environment variables
+To use environment variables in `devcontainer.json` — for example, to control the container image version — see [Environment variables in devcontainer.json](../developing-in-workspaces/environment-variables-in-devcontainer-json.mdx).
+:::

sites/docs-devsy-sh/pages/what-is-devsy.mdx

@@ -10,15 +10,15 @@ Devsy helps organizations scale their engineering operations with standardized,
   <figcaption>Devsy</figcaption>
 </figure>
 
-Devsy connects each developer's local IDE to the infrastructure where work actually runs. The same workspace can live on a laptop, a powerful cloud machine, or a shared remote host, and every workspace is created and managed the same way. That consistency is what lets a team standardize on one environment definition and move between backends without re-learning their tooling.
+Devsy connects each developer's local IDE to the infrastructure where the work runs. The same workspace can live on a laptop, a cloud machine, or a shared remote host, and every workspace is created and managed the same way. That consistency lets a team standardize on one environment definition and move between backends without re-learning their tooling.
 
 ## Why Devsy?
 
 Devsy implements the open [DevContainer standard](https://containers.dev/), so the environment definition your team commits remains portable across every backend Devsy supports.
 
 For engineering organizations, Devsy delivers:
 * **Standardized environments**: Define a workspace once in `devcontainer.json` and give every engineer the same toolchain, dependencies, and configuration. New hires are productive on day one instead of spending days on setup.
-* **Cost efficiency at scale**: Run workspaces on the infrastructure you already pay for, and let Devsy automatically shut down idle machines so you only spend on capacity that's in use.
+* **Cost efficiency at scale**: Run workspaces on the infrastructure you already pay for, and let Devsy shut down idle machines so you spend only on capacity in use.
 * **No vendor lock-in**: Choose the infrastructure that fits each team — local, cloud, Kubernetes, or remote SSH hosts. Switch a workspace's provider with a single command, with no rewrite of your environment definition.
 * **Flexible development**: Engineers get the same experience locally and remotely, from quick prototyping on a laptop to heavy builds on a cloud machine.
 * **Cross-IDE support**: VS Code and its variants and the full JetBrains suite are supported out of the box; any other editor can connect over SSH.