skevetter · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026
diff --git a/.../docs-devsy-sh/content/docs/developing-in-workspaces/connect-to-a-workspace.mdx b/.../docs-devsy-sh/content/docs/developing-in-workspaces/connect-to-a-workspace.mdx
@@ -3,125 +3,76 @@ title: Connect to a Workspace
 sidebar_label: Connect to a Workspace
 ---
 
-## Connect to a Workspace
+Once a workspace is created, it is reachable over SSH at `WORKSPACE_NAME.devsy`. If you chose an IDE, Devsy opens it after the workspace starts.
 
-Once a workspace is created, it is reachable through the SSH host `WORKSPACE_NAME.devsy`. If you chose an IDE, Devsy opens it after the workspace starts.
+Pick the IDE with `--ide` when you start a workspace, or set a default for all workspaces:
 
-<Callout>
-Change the default IDE globally with `devsy ide use vscode`, or per workspace with `devsy workspace up my-workspace --ide vscode`.
-</Callout>
+```sh
+devsy workspace up my-workspace --ide vscode
+devsy ide use vscode
+```
 
-### VS Code Browser
+Run `devsy ide list` to see every supported IDE.
 
-Devsy can open VS Code in a browser tab. It installs [openvscode-server](https://github.com/gitpod-io/openvscode-server) inside the workspace and tunnels a connection to it from localhost. Open the workspace in VS Code browser with:
-```
-devsy workspace up my-workspace --ide openvscode
-```
+### VS Code in the browser
 
-To pick a different openvscode version:
-```
-devsy workspace up my-workspace --ide openvscode --ide-option VERSION=v1.76.2
+Devsy installs [openvscode-server](https://github.com/gitpod-io/openvscode-server) in the workspace and tunnels to it from localhost.
+
+```sh
+devsy workspace up my-workspace --ide openvscode
 ```
 
 ### VS Code
 
-Install the [remote ssh extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) and the [code CLI](https://code.visualstudio.com/docs/editor/command-line). Then start the workspace in VS Code with:
-```
+Install the [Remote - SSH extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) and the [code CLI](https://code.visualstudio.com/docs/editor/command-line), then:
+
+```sh
 devsy workspace up my-workspace --ide vscode
 ```
 
-<Callout title="SSH Fallback">
-If this doesn't work, use the regular SSH connection `WORKSPACE_NAME.devsy` to connect VS Code.
-</Callout>
+If that fails, connect VS Code to `WORKSPACE_NAME.devsy` over SSH.
 
-### JetBrains Suite (Goland, PyCharm, Intellij etc.)
+### JetBrains IDEs
 
-Install [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/) and have a valid JetBrains subscription for your local IDE. Supported JetBrains IDEs:
-* **CLion (clion)**
-* **Goland (goland)**
-* **PyCharm (pycharm)**
-* **Intellij (intellij)**
-* **PhpStorm (phpstorm)**
-* **WebStorm (webstorm)**
-* **Rider (rider)**
-* **RubyMine (rubymine)**
+Install [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/). You need a license for the IDE you use. Start the workspace with the IDE name, for example:
 
-Start your workspace with:
-```
+```sh
 devsy workspace up my-workspace --ide goland
 ```
 
-Devsy installs the GoLand server binary into the workspace and opens JetBrains Gateway. After installation, the Gateway SSH dialog appears pre-filled - click **Check Connection and Continue** to start the IDE inside the workspace.
-
-To pick a different IDE version:
-```
-devsy workspace up my-workspace --ide goland --ide-option VERSION=2022.3.3
-```
+Devsy installs the IDE server in the workspace and opens Gateway. Click **Check Connection and Continue** in the prefilled SSH dialog. If that fails, connect Gateway to `WORKSPACE_NAME.devsy` over SSH.
 
-<Callout title="SSH Fallback">
-If this doesn't work, use the SSH host `WORKSPACE_NAME.devsy` to connect your JetBrains IDE.
-</Callout>
-
-<Callout title="Fleet Support">
-Fleet only works by manually adding an SSH connection to `WORKSPACE_NAME.devsy`.
-</Callout>
+Fleet works only through a manually added SSH connection to `WORKSPACE_NAME.devsy`.
 
 ### SSH
 
-When a workspace is created, Devsy adds an entry for `WORKSPACE_NAME.devsy` to `~/.ssh/config`. Connect with:
-```
+Devsy adds a `WORKSPACE_NAME.devsy` entry to `~/.ssh/config` when it creates a workspace.
+
+```sh
 ssh WORKSPACE_NAME.devsy
 ```
 
-Any IDE that supports remote development over SSH can also use this host.
-
-### Devsy CLI
+Any IDE with remote SSH support can use this host. Without an `ssh` client, use the CLI:
 
-If you don't have `ssh` installed or can't connect through an IDE, use the Devsy CLI:
-```
+```sh
 devsy workspace ssh my-workspace
-```
-
-Run a command non-interactively:
-```
 devsy workspace ssh my-workspace --command "echo Hello World"
 ```
 
-## IDE Commands
-
-Configure how Devsy opens workspaces with these commands.
+## IDE options
 
-### Configure IDE Options
+Each IDE has options such as the version. List and change them with:
 
-Each IDE supports options like version and download path. List them with:
-```
+```sh
 devsy ide get openvscode
-```
-
-Change an option with:
-```
 devsy ide set openvscode -o VERSION=v1.76.2
 ```
 
-### Change Default IDE
-
-Set the default IDE Devsy uses to open workspaces:
-```
-devsy ide use vscode
-```
-
-### List supported IDEs
-
-List every IDE Devsy supports:
-```
-devsy ide list
-```
+You can also set an option for a single workspace with `--ide-option VERSION=...` on `devsy workspace up`.
 
 ## Desktop shortcuts
 
-Devsy Desktop ships a command palette and section shortcuts for fast navigation:
-
-- `Cmd/Ctrl + K` - open the command palette (search workspaces, providers, machines, and pages).
-- `Cmd/Ctrl + N` - start the New Workspace wizard.
-- `Cmd/Ctrl + 1` through `Cmd/Ctrl + 8` - jump to Dashboard, Workspaces, Providers, Machines, Contexts, Terminals, SSH Keys, and Settings.
-- `Esc` - close the active sheet, dialog, or palette (where supported).
+- `Cmd/Ctrl + K` opens the command palette.
+- `Cmd/Ctrl + N` starts the New Workspace wizard.
+- `Cmd/Ctrl + 1` to `8` jumps between the main sections.
+- `Esc` closes the open sheet, dialog, or palette.
diff --git a/.../docs-devsy-sh/content/docs/developing-in-workspaces/continuous-integration.mdx b/.../docs-devsy-sh/content/docs/developing-in-workspaces/continuous-integration.mdx
@@ -3,13 +3,9 @@ title: Continuous Integration
 sidebar_label: Continuous Integration
 ---
 
-## Continuous Integration
+`devsy ci` builds an ephemeral devcontainer, runs a command in it, and deletes the workspace afterwards. Use it to check that your `devcontainer.json` still builds and your tests pass inside it.
 
-`devsy ci` builds an ephemeral devcontainer, runs a command inside it, and tears
-the workspace down afterwards. It lets you verify that your `devcontainer.json`
-still builds.
-
-### How it works
+## How it works
 
 1. Resolves a workspace from the current directory (or a given source).
 2. Builds and starts the devcontainer (equivalent to `devsy workspace up`, without
@@ -21,7 +17,7 @@ still builds.
 A non-zero exit from the command propagates as the exit code of `devsy ci`, so a
 failing test or build fails the CI job.
 
-### Usage
+## Usage
 
 ```sh
 devsy ci [flags] [workspace-path|workspace-name] -- <cmd> [args...]
@@ -54,27 +50,16 @@ devsy ci --keep -- ./run-integration-tests.sh
 
 ### Common flags
 
-| Flag | Description |
-| --- | --- |
-| `--run-cmd` | Shell command run inside the container via `sh -c` (alternative to an explicit argv after `--`). |
-| `--remote-env KEY=VALUE` | Set an environment variable in the container at run time. Repeatable. |
-| `--keep` | Keep the workspace instead of tearing it down. |
-| `--devcontainer` | Select the devcontainer config source: `none`, `image:<ref>`, `id:<name>`, or a path to a `devcontainer.json`. |
-| `--no-cache` | Build without using the cache. |
-| `--cache-from` | Reuse a pre-built image as a build cache source. Repeatable. |
-| `--platform` | Run the container under a specific platform via emulation (e.g. `linux/amd64`). |
-| `--workspace-env KEY=VALUE` | Env variables available at build and lifecycle time (not just at run time). Repeatable. |
-| `--workspace-env-file` | File(s) of `KEY=VALUE` build/lifecycle env variables. |
-| `--init-env KEY=VALUE` | Env variables injected during workspace initialization. Repeatable. |
-| `--secrets-file` | JSON file (`{"KEY":"value"}`) of secrets injected into lifecycle commands. |
-| `--feature-secrets-file` | JSON file of secret values for features. |
-| `--secret` | Stored Devsy secret to inject, as `NAME[,type=env\|mount][,target=X]`. Repeatable. |
-| `--env` | Stored Devsy env var to inject, as `NAME[=TARGET]`. Repeatable. |
-| `--build-secret` | Stored Devsy secret exposed to the build via BuildKit. Repeatable. |
-| `--git-token` | Stored Devsy secret with an access token for cloning a private HTTP repository. |
-| `--git-token-username` | Username for `--git-token` (default inferred from the repo host). |
-
-### Pre-building and pushing images
+Run `devsy ci --help` for the full list. The most used:
+
+- `--keep` keeps the workspace instead of deleting it.
+- `--remote-env KEY=VALUE` sets an environment variable in the container at run time. Repeatable.
+- `--devcontainer` picks the config: `none`, `image:<ref>`, `id:<name>`, or a path to a `devcontainer.json`.
+- `--cache-from` and `--no-cache` control the image build cache.
+- `--platform` runs the container under another platform, such as `linux/amd64`.
+- `--secret`, `--env`, `--build-secret`, and `--git-token` inject stored Devsy secrets and variables. See [Secrets](./secrets.mdx).
+
+## Pre-building and pushing images
 
 `devsy ci` focuses on running a command. To pre-build and publish a devcontainer
 image for reuse as a build cache, use `devsy workspace build`:
@@ -86,7 +71,7 @@ devsy workspace build --repository ghcr.io/my-org/my-devcontainer --tag latest -
 Downstream CI jobs can then reference that image via `--cache-from` to speed up
 builds.
 
-### GitHub Actions
+## GitHub Actions
 
 Install the CLI, configure the docker provider, then run `devsy ci`: