docs: clarify installation paths and components (#153)

Rewrite Getting Started in README and website docs to explain the
daemon, put agent CLI prerequisites first, and split setup into
Desktop App (recommended, bundles daemon) and CLI/headless paths.
Add "Components at a glance" section to ARCHITECTURE.md.

README.md

@@ -26,20 +26,32 @@ Run agents in parallel on your own machines. Ship from your phone or your desk.
 
 ## Getting Started
 
-### Desktop app
+Paseo runs a local server called the daemon that manages your coding agents. Clients like the desktop app, mobile app, web app, and CLI connect to it.
 
-Download from [paseo.sh/download](https://paseo.sh/download) or the [GitHub releases page](https://github.com/getpaseo/paseo/releases). The app bundles its own daemon, so there's nothing else to install. It can also connect to daemons running on other machines.
+### Prerequisites
 
-### Headless / server mode
+You need at least one agent CLI installed and configured with your credentials:
 
-Run the daemon on any machine:
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+- [Codex](https://github.com/openai/codex)
+- [OpenCode](https://github.com/anomalyco/opencode)
+
+### Desktop app (recommended)
+
+Download it from [paseo.sh/download](https://paseo.sh/download) or the [GitHub releases page](https://github.com/getpaseo/paseo/releases). Open the app and the daemon starts automatically. Nothing else to install.
+
+To connect from your phone, scan the QR code shown in Settings.
+
+### CLI / headless
+
+Install the CLI and start Paseo:
 
 ```bash
 npm install -g @getpaseo/cli
 paseo
 ```
 
-Then connect from any client — desktop, web, mobile, or CLI. See [paseo.sh/download](https://paseo.sh/download) for all options.
+This shows a QR code in the terminal. Connect from any client. This path is useful for servers and remote machines.
 
 For full setup and configuration, see:
 - [Docs](https://paseo.sh/docs)

docs/ARCHITECTURE.md

@@ -31,6 +31,14 @@ Your code never leaves your machine. Paseo is local-first.
 └───────────┘ └────────┘ └──────────┘
 ```
 
+## Components at a glance
+
+- **Daemon:** Local server that spawns and manages agent processes and exposes the WebSocket API.
+- **App:** Cross-platform Expo client for iOS, Android, web, and the shared UI used by desktop.
+- **CLI:** Terminal interface for agent workflows that can also start and manage the daemon.
+- **Desktop app:** Electron wrapper around the web app that bundles and auto-manages its own daemon.
+- **Relay:** Optional encrypted bridge for remote access without opening ports directly.
+
 ## Packages
 
 ### `packages/server` — The daemon

packages/website/src/routes/docs/index.tsx

@@ -17,37 +17,17 @@ function GettingStarted() {
       <div>
         <h1 className="text-3xl font-medium font-title mb-4">Getting Started</h1>
         <p className="text-white/60 leading-relaxed">
-          Paseo connects to your local development environment and lets you manage your coding
+          Paseo has three main pieces: the daemon is the local server that manages your agents,
-          agents from anywhere.
+          the app is the client you use from mobile, web, or desktop, and the CLI is the terminal
+          interface that can also launch the daemon.
         </p>
       </div>
 
-      <section className="space-y-4">
-        <h2 className="text-xl font-medium">Installation</h2>
-        <p className="text-white/60">Install the CLI globally and run it on your machine:</p>
-        <div className="bg-card border border-border rounded-lg p-4 font-mono text-sm">
-          <span className="text-muted-foreground select-none">$ </span>
-          <span>npm install -g @getpaseo/cli</span>
-        </div>
-        <div className="bg-card border border-border rounded-lg p-4 font-mono text-sm">
-          <span className="text-muted-foreground select-none">$ </span>
-          <span>paseo</span>
-        </div>
-      </section>
-
-      <section className="space-y-4">
-        <h2 className="text-xl font-medium">Connect the App</h2>
-        <p className="text-white/60">
-          Open Paseo on your phone and scan the QR code displayed in your terminal, or enter the
-          server address manually.
-        </p>
-      </section>
-
       <section className="space-y-4">
         <h2 className="text-xl font-medium">Prerequisites</h2>
         <p className="text-white/60">
-          Paseo wraps CLI tools like Claude Code and Codex. You'll need to have them installed and
+          Paseo manages existing agent CLIs. Install at least one agent and make sure it already
-          configured with your own credentials before Paseo can manage them.
+          works with your credentials before you set up Paseo.
         </p>
         <ul className="text-white/60 space-y-2 list-disc list-inside">
           <li>
@@ -83,6 +63,63 @@ function GettingStarted() {
         </ul>
       </section>
 
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Desktop App</h2>
+        <p className="text-white/60">
+          Download the desktop app from{" "}
+          <a
+            href="https://paseo.sh/download"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="underline hover:text-white/80"
+          >
+            paseo.sh/download
+          </a>{" "}
+          or the{" "}
+          <a
+            href="https://github.com/getpaseo/paseo/releases"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="underline hover:text-white/80"
+          >
+            GitHub releases page
+          </a>
+          . Open it and you're done.
+        </p>
+        <p className="text-white/60">
+          The desktop app bundles and manages its own daemon automatically, so you do not need a
+          separate CLI install on that machine unless you want it.
+        </p>
+        <p className="text-white/60">
+          On first launch, you may briefly see a startup screen while the local server starts and
+          the app connects to it. After that, connect from your phone by scanning the QR code in
+          Settings if you want mobile access.
+        </p>
+      </section>
+
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">CLI / Server</h2>
+        <p className="text-white/60">
+          Use this path for headless setups, servers, or remote machines where you want the daemon
+          running without the desktop app.
+        </p>
+        <div className="bg-card border border-border rounded-lg p-4 font-mono text-sm">
+          <span className="text-muted-foreground select-none">$ </span>
+          <span>npm install -g @getpaseo/cli</span>
+        </div>
+        <div className="bg-card border border-border rounded-lg p-4 font-mono text-sm">
+          <span className="text-muted-foreground select-none">$ </span>
+          <span>paseo</span>
+        </div>
+        <p className="text-white/60">
+          Paseo prints a QR code in the terminal. Scan it from the mobile app, or enter the daemon
+          address manually from another client.
+        </p>
+        <p className="text-white/60">
+          Configuration and local state live under <code>PASEO_HOME</code>.
+        </p>
+      </section>
+
       <section className="space-y-4">
         <h2 className="text-xl font-medium">Voice Setup</h2>
         <p className="text-white/60">