diff --git a/README.md b/README.md
index f361c440b8..f7b3865cdc 100644
--- a/README.md
+++ b/README.md
@@ -134,22 +134,28 @@ Reviewer agents are configured separately. The current reviewer harnesses are:
## Install
-The fastest path is the same flow used by the installation docs:
+Download the latest desktop build for your platform:
+
+| Platform | Download |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| macOS (Apple silicon) | [.zip](https://github.com/AgentWrapper/agent-orchestrator/releases/latest/download/agent-orchestrator-darwin-arm64.zip) |
+| macOS (Intel) | [.zip](https://github.com/AgentWrapper/agent-orchestrator/releases/latest/download/agent-orchestrator-darwin-x64.zip) |
+| Windows | [.exe](https://github.com/AgentWrapper/agent-orchestrator/releases/latest/download/agent-orchestrator-win32-x64.exe) |
+| Linux | [.AppImage](https://github.com/AgentWrapper/agent-orchestrator/releases/latest/download/agent-orchestrator-linux-x64.AppImage) |
+
+After installing, open Agent Orchestrator and point it at the repository you want AO to manage. The desktop app runs the daemon for you, so no CLI is required. See the [installation guide](https://ao-agents.com/docs/installation) for agent CLI setup and troubleshooting.
+
+
+Install via npm (legacy CLI, no longer recommended)
+
+The `@aoagents/ao` npm package is frozen and no longer receives updates. It ships the `ao` CLI for existing users; `ao start` fetches and opens the same desktop build linked above. Prefer the desktop download for a fresh setup.
```bash
npm install -g @aoagents/ao
ao start
```
-Run `ao start` from the repository you want AO to manage. See the [installation guide](https://ao-agents.com/docs/installation) for pnpm, yarn, source installs, agent CLI setup, and troubleshooting.
-
-You can also download the latest desktop build for your platform:
-
-| Platform | Download |
-| -------- | ------------------------------------------------------------------------------------------------- |
-| Windows | [Setup.exe](https://github.com/AgentWrapper/agent-orchestrator/releases/latest) |
-| macOS | [Agent Orchestrator.dmg](https://github.com/AgentWrapper/agent-orchestrator/releases/latest) |
-| Linux | [Agent Orchestrator.AppImage](https://github.com/AgentWrapper/agent-orchestrator/releases/latest) |
+
## Witness AO's Journey on X
diff --git a/frontend/src/landing/content/docs/installation.mdx b/frontend/src/landing/content/docs/installation.mdx
index f71cd70baa..b27410c1cf 100644
--- a/frontend/src/landing/content/docs/installation.mdx
+++ b/frontend/src/landing/content/docs/installation.mdx
@@ -8,11 +8,12 @@ import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Step, Steps } from "fumadocs-ui/components/steps";
import { Accordions, Accordion } from "fumadocs-ui/components/accordion";
-This page gets your machine ready to run Agent Orchestrator. By the end, the `ao` command should be on your `PATH`, your source-control CLI should be authenticated, and `ao doctor` should be able to explain what is ready or missing.
+This page gets your machine ready to run Agent Orchestrator. By the end, the desktop app (or the legacy `ao` CLI) should be installed, your source-control CLI should be authenticated, and an agent CLI should be ready to do the coding.
- The published package is `@aoagents/ao`. It provides the global `ao` command and includes the built-in CLI, dashboard,
- and plugin packages.
+ The recommended install is the **desktop app** from GitHub Releases. It bundles the daemon, dashboard, and plugins,
+ and updates itself. The `@aoagents/ao` npm package is the legacy on-ramp: it ships the `ao` CLI, whose `ao start`
+ fetches and opens the same desktop app. The npm package is frozen and no longer updated.
## Prerequisites
@@ -43,43 +44,33 @@ If you plan to use GitLab or Linear, install and authenticate their CLIs or cred
## Install AO
-
-
-
-```bash
-npm install -g @aoagents/ao
-```
-
-
-
-
-```bash
-pnpm add -g @aoagents/ao
-```
-
-
-
+The recommended way to install AO is the desktop build from GitHub Releases. Download the latest build for your platform, then open it:
-```bash
-yarn global add @aoagents/ao
-```
-
-
-
+| Platform | Download |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| macOS (Apple silicon) | [.zip](https://github.com/AgentWrapper/agent-orchestrator/releases/latest/download/agent-orchestrator-darwin-arm64.zip) |
+| macOS (Intel) | [.zip](https://github.com/AgentWrapper/agent-orchestrator/releases/latest/download/agent-orchestrator-darwin-x64.zip) |
+| Windows | [.exe](https://github.com/AgentWrapper/agent-orchestrator/releases/latest/download/agent-orchestrator-win32-x64.exe) |
+| Linux | [.AppImage](https://github.com/AgentWrapper/agent-orchestrator/releases/latest/download/agent-orchestrator-linux-x64.AppImage) |
-```bash
-git clone https://github.com/AgentWrapper/agent-orchestrator
-cd agent-orchestrator
-pnpm install
-pnpm build
-pnpm --filter @aoagents/ao link --global
-```
+The desktop app owns the daemon, dashboard, and auto-updates, so a desktop install needs no CLI. Skip ahead to [Authenticate Your Tools](#authenticate-your-tools).
-
+
+ The `@aoagents/ao` npm package is frozen and no longer receives updates. It ships the `ao` CLI for existing users; `ao
+ start` fetches and opens the same desktop build above. Use it only if you already run AO from the CLI:
+
+
+ ```bash npm install -g @aoagents/ao ```
+ ```bash pnpm add -g @aoagents/ao ```
+ ```bash yarn global add @aoagents/ao ```
+
+ ```bash git clone https://github.com/AgentWrapper/agent-orchestrator cd agent-orchestrator pnpm install pnpm build
+ pnpm --filter @aoagents/ao link --global ```
+
-Confirm the command is available:
+If you installed the CLI, confirm it is available (desktop users can skip this):
```bash
ao --version
@@ -158,16 +149,16 @@ opencode --help
### Start AO in a repo
-Run `ao start` from a repository you want AO to manage:
+**Desktop app:** open Agent Orchestrator and add the repository you want it to manage. The app starts the daemon, dashboard, and an orchestrator session for the project.
+
+**CLI (legacy):** run `ao start` from a repository you want AO to manage:
```bash
cd ~/code/my-repo
ao start
```
-If there is no `agent-orchestrator.yaml`, AO creates one. It also starts the dashboard and an orchestrator session for the project.
-
-You can also start from a path or clone from a URL:
+If there is no `agent-orchestrator.yaml`, AO creates one. You can also start from a path or clone from a URL:
```bash
ao start ~/code/my-repo