docs: add desktop client section and v1 API server documentation

New pages: - desktop-client/index.mdx — overview, architecture, features - desktop-client/installation.mdx — download, setup, requirements - desktop-client/development.mdx — dev environment, project structure, conventions - desktop-client/api-server.mdx — pocketpaw serve command, full endpoint reference, auth
2026-05-13 21:21:53 +00:00 · 2026-03-10 18:38:55 +05:30
parent 12cc9f4def
commit 423b66827a
6 changed files with 760 additions and 2 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -17,6 +17,7 @@ docs/
 ├── public/                    # Static assets (logos, OG images)
 ├── introduction/              # Welcome & overview
 ├── getting-started/           # Install, quick-start, config, project structure
+├── desktop-client/            # Desktop app overview, installation, development, API server
 ├── concepts/                  # Architecture, message bus, agent loop, memory, tools, security
 ├── channels/                  # 9+ channel guides (Telegram, Discord, Slack, WhatsApp, etc.)
 ├── backends/                  # Claude Agent SDK, OpenAI Agents, Google ADK, Codex CLI, OpenCode, Copilot SDK
--- a/docs/desktop-client/api-server.mdx
+++ b/docs/desktop-client/api-server.mdx
@@ -0,0 +1,296 @@
+---
+title: "API Server: Headless Mode with pocketpaw serve"
+description: "Run PocketPaw as a headless API server using pocketpaw serve. REST API and WebSocket endpoints for external clients, scripts, and the desktop app."
+section: Desktop Client
+ogType: article
+keywords: ["pocketpaw serve", "api server", "headless mode", "rest api", "websocket api"]
+tags: ["api", "server", "headless", "rest"]
+---
+
+# API Server (`pocketpaw serve`)
+
+The `pocketpaw serve` command starts PocketPaw as a **headless API server** without the web dashboard frontend. It exposes the full REST API and WebSocket endpoints, making it ideal for:
+
+- The **desktop client** (Tauri app) connecting over localhost
+- **Custom scripts** and automation
+- **External integrations** that only need the API
+- **Docker** and headless server deployments
+
+## Quick Start
+
+```bash
+# Start the API server (default: localhost:8888)
+pocketpaw serve
+
+# Custom host and port
+pocketpaw serve --host 0.0.0.0 --port 9000
+
+# Development mode with auto-reload
+pocketpaw serve --dev
+```
+
+## What's Included
+
+The API server starts the full PocketPaw backend:
+
+| Component | Status |
+| --- | --- |
+| REST API (`/api/v1/`) | Active |
+| WebSocket (`/ws`, `/api/v1/ws`) | Active |
+| Message bus | Active |
+| Agent loop | Active |
+| Memory system | Active |
+| Scheduler | Active |
+| Channel adapters | Active (if configured) |
+| Web dashboard UI | **Not served** |
+
+The only difference from the default `pocketpaw` command is that no HTML/CSS/JS frontend is served. All API endpoints work identically.
+
+## Authentication
+
+The API server supports multiple authentication methods:
+
+### Master Token
+
+On first run, PocketPaw generates a master access token saved at `~/.pocketpaw/access_token`. Use it as a Bearer token:
+
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8888/api/v1/health
+```
+
+### Session Tokens
+
+Exchange the master token for a short-lived session token:
+
+```bash
+# Get a session token
+curl -X POST http://localhost:8888/api/v1/auth/session \
+  -H "Authorization: Bearer YOUR_MASTER_TOKEN"
+
+# Response: { "session_token": "uuid:hmac_signature" }
+```
+
+### API Keys
+
+Create scoped API keys for long-lived access:
+
+```bash
+# Create an API key
+curl -X POST http://localhost:8888/api/v1/auth/api-keys \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-script", "scopes": ["chat", "sessions"]}'
+
+# Response includes the key (shown once): { "key": "pp_xxxx...", "id": "..." }
+```
+
+### OAuth2 (PKCE)
+
+For desktop and third-party apps, use the OAuth2 PKCE flow:
+
+1. `GET /api/v1/oauth/authorize?client_id=...&code_challenge=...`
+2. User approves consent
+3. `POST /api/v1/oauth/token` with authorization code
+4. Use the returned access token (`ppat_*` prefix)
+
+### Localhost Bypass
+
+By default, requests from `127.0.0.1` or `::1` skip authentication. Disable this with:
+
+```bash
+export POCKETPAW_LOCALHOST_AUTH_BYPASS=false
+```
+
+## API Endpoints
+
+All endpoints are prefixed with `/api/v1/`. Here's a summary by category:
+
+### Chat
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `POST` | `/chat` | Send message, get complete response (blocking) |
+| `POST` | `/chat/stream` | Send message, receive SSE stream |
+| `POST` | `/chat/stop` | Cancel in-flight response |
+
+### Sessions
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `POST` | `/sessions` | Create new session |
+| `GET` | `/sessions` | List sessions (paginated) |
+| `DELETE` | `/sessions/{id}` | Delete session |
+| `POST` | `/sessions/{id}/title` | Update session title |
+| `GET` | `/sessions/search` | Search sessions by content |
+| `GET` | `/sessions/{id}/history` | Get message history |
+| `GET` | `/sessions/{id}/export` | Export as JSON or Markdown |
+
+### Settings
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/settings` | Get current settings |
+| `PUT` | `/settings` | Update settings |
+
+### Memory
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/memory/long_term` | Get long-term memories (paginated) |
+| `DELETE` | `/memory/long_term/{id}` | Delete memory entry |
+| `GET` | `/memory/settings` | Get memory backend config |
+| `POST` | `/memory/settings` | Save memory backend config |
+| `GET` | `/memory/stats` | Get memory statistics |
+
+### Health & Diagnostics
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/version` | Version and backend info |
+| `GET` | `/health` | Health engine summary |
+| `GET` | `/health/errors` | Recent errors (paginated) |
+| `POST` | `/health/check` | Trigger health check |
+| `GET` | `/audit` | Audit log entries |
+| `POST` | `/security-audit` | Run security audit |
+| `GET` | `/metrics/system` | CPU, RAM, disk, battery |
+| `GET` | `/metrics/usage` | Token usage and costs |
+
+### Identity
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/identity` | Get all identity files |
+| `PUT` | `/identity` | Save identity file edits |
+
+### Channels
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/channels/status` | Status of all channel adapters |
+| `POST` | `/channels/save` | Save channel configuration |
+| `POST` | `/channels/toggle` | Start or stop a channel |
+
+### MCP Servers
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/mcp/status` | Status of MCP servers |
+| `POST` | `/mcp/add` | Add MCP server |
+| `POST` | `/mcp/remove` | Remove MCP server |
+| `POST` | `/mcp/toggle` | Toggle MCP server |
+| `POST` | `/mcp/test` | Test connection |
+| `GET` | `/mcp/presets` | List presets |
+| `POST` | `/mcp/presets/install` | Install preset |
+
+### Skills
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/skills` | List installed skills |
+| `GET` | `/skills/search` | Search skill library |
+| `POST` | `/skills/install` | Install skill |
+| `POST` | `/skills/remove` | Remove skill |
+
+### Reminders & Intentions
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/reminders` | List reminders |
+| `POST` | `/reminders` | Create reminder (natural language) |
+| `DELETE` | `/reminders/{id}` | Delete reminder |
+| `GET` | `/intentions` | List intentions |
+| `POST` | `/intentions` | Create intention |
+| `POST` | `/intentions/{id}/toggle` | Toggle intention |
+
+### Backends
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/backends` | List backends with availability |
+| `POST` | `/backends/install` | Install backend SDK |
+
+### Kits (Command Centers)
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/kits/catalog` | List kit catalog |
+| `POST` | `/kits/catalog/{id}/install` | Install kit |
+| `GET` | `/kits` | List installed kits |
+| `DELETE` | `/kits/{id}` | Uninstall kit |
+| `POST` | `/kits/{id}/activate` | Activate kit |
+
+### Files
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/files/browse` | List directory contents |
+| `GET` | `/files/content` | Get file content |
+| `GET` | `/files/recent` | Recently accessed files |
+
+### Remote Access
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/remote/status` | Tunnel status |
+| `POST` | `/remote/start` | Start Cloudflare tunnel |
+| `POST` | `/remote/stop` | Stop tunnel |
+
+### Events (SSE)
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/events/stream` | Subscribe to real-time system events |
+
+## WebSocket
+
+Connect to the WebSocket for real-time streaming:
+
+```javascript
+const ws = new WebSocket('ws://localhost:8888/api/v1/ws?token=YOUR_TOKEN');
+
+// Send a chat message
+ws.send(JSON.stringify({
+  type: 'chat',
+  content: 'Hello, PocketPaw!',
+  session_id: 'my-session'
+}));
+
+// Receive streaming responses
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  // data.type: 'chunk', 'stream_end', 'tool_start', 'tool_result', 'thinking', 'error'
+};
+```
+
+WebSocket paths: `/ws`, `/api/v1/ws`, `/v1/ws` (all equivalent).
+
+## Comparison: `serve` vs Default Mode
+
+| | `pocketpaw` (default) | `pocketpaw serve` |
+| --- | --- | --- |
+| Web dashboard | Served at root | Not served |
+| REST API | `/api/v1/` | `/api/v1/` |
+| WebSocket | Available | Available |
+| Auto-opens browser | Yes | No |
+| All backend services | Running | Running |
+| Best for | Browser-based usage | Desktop app, scripts, headless |
+
+## OpenAPI Documentation
+
+When the API server is running, interactive API docs are available at:
+
+- **Swagger UI:** `http://localhost:8888/api/v1/docs`
+- **ReDoc:** `http://localhost:8888/api/v1/redoc`
+- **OpenAPI JSON:** `http://localhost:8888/api/v1/openapi.json`
+
+<CardGroup>
+  <Card title="API Reference" icon="lucide:server" href="/api">
+    Full endpoint documentation with request and response examples.
+  </Card>
+  <Card title="WebSocket Protocol" icon="lucide:radio" href="/api/websocket">
+    Real-time streaming protocol details.
+  </Card>
+  <Card title="Configuration" icon="lucide:settings" href="/getting-started/configuration">
+    Environment variables and settings reference.
+  </Card>
+</CardGroup>
--- a/docs/desktop-client/development.mdx
+++ b/docs/desktop-client/development.mdx
@@ -0,0 +1,226 @@
+---
+title: "Desktop Client Development: Build and Contribute"
+description: "Set up the PocketPaw desktop client development environment. Tauri 2.0, SvelteKit, Svelte 5, Tailwind CSS 4, and shadcn-svelte."
+section: Desktop Client
+ogType: article
+keywords: ["pocketpaw development", "tauri development", "sveltekit app", "desktop client build"]
+tags: ["desktop", "development", "contributing"]
+---
+
+# Desktop Client Development
+
+The desktop client source lives in `client/` at the repository root. It's a **Tauri 2.0** app with a **SvelteKit** frontend.
+
+## Prerequisites
+
+- **[Bun](https://bun.sh/)** for package management (not npm or yarn)
+- **[Rust](https://rustup.rs/)** toolchain for the Tauri backend
+- **Python backend** running on `localhost:8888`
+
+### Platform-Specific Requirements
+
+**Windows:**
+- Visual Studio C++ Build Tools
+- WebView2 (included in Windows 10 1803+)
+
+**macOS:**
+- Xcode Command Line Tools (`xcode-select --install`)
+
+**Linux:**
+- `build-essential`, `libwebkit2gtk-4.1-dev`, `libssl-dev`, `libayatana-appindicator3-dev`
+
+## Getting Started
+
+<Steps>
+  <Step>
+    **Clone the repository and install dependencies:**
+
+    ```bash
+    git clone https://github.com/pocketpaw/pocketpaw.git
+    cd pocketpaw/client
+    bun install
+    ```
+  </Step>
+  <Step>
+    **Start the Python backend** (in a separate terminal):
+
+    ```bash
+    # From the repo root
+    uv run pocketpaw
+    ```
+  </Step>
+  <Step>
+    **Run the desktop app in development mode:**
+
+    ```bash
+    cd client
+    bun run tauri dev
+    ```
+
+    This starts both the Vite dev server (port 1420) and the Tauri shell with hot reload.
+  </Step>
+</Steps>
+
+## Development Commands
+
+```bash
+cd client
+
+# Frontend only (no Tauri shell)
+bun run dev                    # Vite dev server at http://localhost:1420
+
+# Full desktop app
+bun run tauri dev              # Frontend + Tauri shell with hot reload
+
+# Type checking
+bun run check                  # svelte-kit sync + svelte-check
+bun run check:watch            # Watch mode
+
+# Production builds
+bun run build                  # Frontend build only
+bun run tauri build            # Full desktop app installer
+
+# Mobile (experimental)
+bun run tauri:android          # Android dev
+bun run tauri:ios              # iOS dev
+```
+
+## Project Structure
+
+```
+client/
+  src/                         # SvelteKit frontend
+    routes/                    # SPA routes
+      +layout.svelte           # App entry point (auth + store init)
+      +page.svelte             # Chat view (main route)
+      settings/                # Settings page
+      onboarding/              # First-run wizard
+      sidepanel/               # Side panel window
+      quickask/                # Quick ask popup window
+      oauth-callback/          # OAuth redirect handler
+    lib/
+      api/
+        client.ts              # REST client with 401 auto-refresh
+        websocket.ts           # WebSocket with auto-reconnect
+        config.ts              # Backend URL + API prefix
+      stores/                  # Svelte 5 rune-based stores
+        connection.svelte.ts   # REST + WebSocket lifecycle
+        chat.svelte.ts         # Messages, streaming, abort
+        session.svelte.ts      # Session list, active session
+        settings.svelte.ts     # Backend settings
+        activity.svelte.ts     # Activity log
+        ui.svelte.ts           # Sidebar, search, UI state
+      components/
+        ui/                    # shadcn-svelte components
+      auth/                    # OAuth2 PKCE flow
+    styles/
+      global.css               # Design tokens (oklch CSS vars)
+  src-tauri/                   # Rust backend
+    src/
+      lib.rs                   # Tauri entry point
+      commands.rs              # IPC commands (read_access_token, etc.)
+      tray.rs                  # System tray menu
+      side_panel.rs            # Side panel window management
+      quick_ask.rs             # Quick ask window management
+      oauth.rs                 # OAuth token CRUD
+    capabilities/
+      default.json             # Desktop permissions
+      mobile.json              # Mobile permissions
+    tauri.conf.json            # Tauri configuration
+```
+
+## Key Conventions
+
+### Svelte 5 Runes
+
+The client uses Svelte 5 runes exclusively:
+
+```svelte
+<script>
+  // Props — always use let, not const
+  let { title, count = 0 } = $props();
+
+  // Reactive state
+  let messages = $state([]);
+
+  // Derived values
+  let total = $derived(messages.length);
+
+  // Derived with function body (note: .by())
+  let filtered = $derived.by(() => {
+    return messages.filter(m => m.visible);
+  });
+</script>
+```
+
+### Tailwind CSS 4
+
+Never use string interpolation in class attributes:
+
+```svelte
+<!-- Wrong — breaks Tailwind 4 -->
+<div class="p-4 {isActive ? 'bg-blue-500' : ''}">
+
+<!-- Correct -->
+<div class={cn("p-4", isActive && "bg-blue-500")}>
+```
+
+### State Management
+
+Stores are singleton class instances using `$state` and `$derived`:
+
+```typescript
+// src/lib/stores/example.svelte.ts
+class ExampleStore {
+  items = $state<Item[]>([]);
+  loading = $state(false);
+  count = $derived(this.items.length);
+
+  async load() {
+    this.loading = true;
+    this.items = await api.getItems();
+    this.loading = false;
+  }
+}
+
+export const exampleStore = new ExampleStore();
+```
+
+### API Layer
+
+The REST client handles authentication and retries:
+
+```typescript
+import { client } from '$lib/api/client';
+
+// GET request
+const sessions = await client.get('/sessions');
+
+// POST with body
+const result = await client.post('/chat', { message: 'Hello' });
+
+// Streaming via SSE
+const stream = client.stream('/chat/stream', { message: 'Hello' });
+for await (const event of stream) {
+  // handle chunks
+}
+```
+
+## Contributing
+
+1. Create a feature branch off `dev`
+2. Make your changes in `client/`
+3. Run `bun run check` to verify type safety
+4. Test with `bun run tauri dev`
+5. Open a PR targeting `dev`
+
+See the [Contributing Guide](https://github.com/pocketpaw/pocketpaw/blob/dev/CONTRIBUTING.md) for full details.
+
+<CardGroup>
+  <Card title="Desktop Client Overview" icon="lucide:monitor" href="/desktop-client">
+    Architecture and feature overview.
+  </Card>
+  <Card title="API Reference" icon="lucide:server" href="/api">
+    REST and WebSocket API documentation.
+  </Card>
+</CardGroup>
--- a/docs/desktop-client/index.mdx
+++ b/docs/desktop-client/index.mdx
@@ -0,0 +1,99 @@
+---
+title: "Desktop Client: Native App for PocketPaw"
+description: "PocketPaw's native desktop app built with Tauri and SvelteKit. System tray, global shortcuts, multi-window support, and one-click backend installation."
+section: Desktop Client
+ogType: article
+keywords: ["pocketpaw desktop", "tauri app", "sveltekit desktop", "native ai client", "desktop ai agent"]
+tags: ["desktop", "client", "tauri", "sveltekit"]
+---
+
+# Desktop Client
+
+The PocketPaw desktop client is a native application built with **Tauri 2.0** and **SvelteKit**. It connects to the Python backend over REST and WebSocket, providing a polished native experience on Windows, macOS, and Linux.
+
+## Why a Desktop App?
+
+The web dashboard works great in a browser, but a native app unlocks features that browsers can't provide:
+
+- **System tray** with quick access menu and background operation
+- **Global keyboard shortcuts** that work even when the app isn't focused
+- **Multi-window support** with a side panel and quick-ask popup
+- **One-click installation** that sets up the Python backend automatically
+- **Auto-updates** via Tauri's built-in updater
+- **Native notifications** for reminders, task completions, and agent alerts
+
+## Downloads
+
+| Platform | Download |
+| --- | --- |
+| **Windows** | [PocketPaw-Setup.exe](https://github.com/pocketpaw/pocketpaw/releases/latest/download/PocketPaw-Setup.exe) |
+| **macOS** | [PocketPaw.dmg](https://github.com/pocketpaw/pocketpaw/releases/latest/download/PocketPaw.dmg) |
+| **Linux** | [PocketPaw.AppImage](https://github.com/pocketpaw/pocketpaw/releases/latest/download/PocketPaw.AppImage) |
+
+## Architecture
+
+The client is split into two layers:
+
+### Frontend (SvelteKit)
+
+- **SvelteKit 2** with **Svelte 5** runes for reactive state management
+- **Tailwind CSS 4** with oklch-based design tokens
+- **shadcn-svelte** (bits-ui) component library
+- Static SPA mode (no SSR), bundled into the Tauri shell
+
+### Rust Backend (Tauri)
+
+- **System tray** with Open, Quick Ask, Settings, and Quit actions
+- **Close-to-tray** behavior (window hides instead of closing)
+- **Multi-window management** for side panel and quick-ask windows
+- **Global shortcuts** registered from the frontend
+- **OAuth token storage** and IPC commands
+
+### How It Connects
+
+The desktop client communicates with the PocketPaw Python backend (running on `localhost:8888`) through:
+
+1. **REST API** (`/api/v1/`) for CRUD operations (sessions, settings, memory, etc.)
+2. **WebSocket** (`/api/v1/ws`) for real-time streaming (chat responses, system events)
+3. **SSE** (`/api/v1/chat/stream`) for chat message streaming
+
+Authentication uses an OAuth2 PKCE flow or a master access token read from `~/.pocketpaw/access_token`.
+
+## Key Features
+
+### Onboarding Wizard
+
+First-time users get a guided setup that:
+1. Detects if the Python backend is installed
+2. Offers one-click installation (downloads and configures Python + PocketPaw)
+3. Walks through API key configuration
+4. Connects to the running backend
+
+### Chat Interface
+
+Full-featured chat with:
+- Real-time streaming responses
+- Tool call visualization (tool start, result, thinking indicators)
+- Code block syntax highlighting via CodeMirror
+- File attachment support
+- Session management (create, rename, delete, search, export)
+
+### Side Panel
+
+A compact secondary window for quick interactions without leaving your current task. Accessible via global shortcut or system tray.
+
+### Quick Ask
+
+A lightweight popup window for fast one-off questions. Opens and closes instantly.
+
+<CardGroup>
+  <Card title="Installation" icon="lucide:download" href="/desktop-client/installation">
+    Download and set up the desktop app.
+  </Card>
+  <Card title="Development" icon="lucide:code" href="/desktop-client/development">
+    Build and contribute to the desktop client.
+  </Card>
+  <Card title="API Server" icon="lucide:server" href="/desktop-client/api-server">
+    Run the headless API server for external clients.
+  </Card>
+</CardGroup>
--- a/docs/desktop-client/installation.mdx
+++ b/docs/desktop-client/installation.mdx
@@ -0,0 +1,111 @@
+---
+title: "Desktop Client Installation: Download and Setup"
+description: "Install the PocketPaw desktop app on Windows, macOS, or Linux. Includes one-click backend setup and manual installation options."
+section: Desktop Client
+ogType: article
+keywords: ["pocketpaw install", "desktop app download", "tauri install", "pocketpaw setup"]
+tags: ["desktop", "installation", "setup"]
+---
+
+# Desktop Client Installation
+
+## Download
+
+Grab the latest release for your platform:
+
+| Platform | Download | Format |
+| --- | --- | --- |
+| **Windows** | [PocketPaw-Setup.exe](https://github.com/pocketpaw/pocketpaw/releases/latest/download/PocketPaw-Setup.exe) | NSIS installer |
+| **macOS** | [PocketPaw.dmg](https://github.com/pocketpaw/pocketpaw/releases/latest/download/PocketPaw.dmg) | DMG disk image |
+| **Linux** | [PocketPaw.AppImage](https://github.com/pocketpaw/pocketpaw/releases/latest/download/PocketPaw.AppImage) | AppImage |
+
+## First Launch
+
+When you open the desktop app for the first time, the onboarding wizard will guide you through setup:
+
+<Steps>
+  <Step>
+    **Backend Detection** - The app checks if the PocketPaw Python backend is installed on your machine. If found, it connects automatically.
+  </Step>
+  <Step>
+    **One-Click Install** (if needed) - If the backend isn't installed, the app offers to set it up for you. This downloads Python (if needed) and installs PocketPaw via pip.
+  </Step>
+  <Step>
+    **API Key Configuration** - Enter your Anthropic API key (or configure Ollama for free local inference). You can skip this and add it later from Settings.
+  </Step>
+  <Step>
+    **Ready to Chat** - The app connects to the backend and opens the chat interface. You're good to go.
+  </Step>
+</Steps>
+
+## Requirements
+
+### All Platforms
+
+- The PocketPaw Python backend must be running on `localhost:8888` (the app can install it for you)
+- An LLM provider API key (Anthropic, OpenAI, etc.) or Ollama for local inference
+
+### Windows
+
+- Windows 10 or later
+- WebView2 runtime (included in Windows 10 1803+ and Windows 11)
+
+### macOS
+
+- macOS 10.15 (Catalina) or later
+
+### Linux
+
+- WebKitGTK 4.1+
+- `libappindicator3` (for system tray support)
+
+## Manual Backend Setup
+
+If you prefer to install the backend separately:
+
+```bash
+# Install via pip
+pip install pocketpaw
+
+# Or use uv
+uv pip install pocketpaw
+
+# Start the backend
+pocketpaw
+```
+
+The desktop app will automatically detect the running backend on `localhost:8888`.
+
+## Running the API Server
+
+For headless operation (no web dashboard), use the `serve` command:
+
+```bash
+pocketpaw serve
+```
+
+This starts the REST API and WebSocket server without serving the web dashboard frontend. The desktop client connects to it the same way. See the [API Server guide](/desktop-client/api-server) for details.
+
+## Auto-Updates
+
+The desktop app checks for updates automatically via GitHub releases. When an update is available, you'll see a notification with the option to download and install it.
+
+## Uninstalling
+
+### Windows
+Use "Add or Remove Programs" in Windows Settings, or run the uninstaller from the Start Menu.
+
+### macOS
+Drag PocketPaw from Applications to the Trash.
+
+### Linux
+Delete the AppImage file. Remove `~/.local/share/com.pocketpaw.app/` for app data.
+
+<CardGroup>
+  <Card title="Quick Start" icon="lucide:rocket" href="/getting-started/quick-start">
+    Get up and running with PocketPaw in 5 minutes.
+  </Card>
+  <Card title="Configuration" icon="lucide:settings" href="/getting-started/configuration">
+    Configure API keys, backends, and channels.
+  </Card>
+</CardGroup>
--- a/docs/docs-config.json
+++ b/docs/docs-config.json
@@ -1,7 +1,7 @@
 {
  "metadata": {
    "name": "PocketPaw",
-    "description": "Self-hosted AI agent controlled via Telegram, Discord, Slack, WhatsApp, or a web dashboard",
+    "description": "Self-hosted AI agent with a native desktop app. Controlled via Telegram, Discord, Slack, WhatsApp, or a web dashboard.",
    "url": "https://pocketpaw.xyz",
    "version": "1.0.0"
  },
@@ -114,7 +114,7 @@
        "label": "Documentation",
        "href": "/introduction",
        "icon": "lucide:book-open",
-        "groups": ["Introduction", "Getting Started", "Guides", "Core Concepts", "Channels", "Agent Backends", "Tools", "Integrations", "Security", "Memory", "Advanced", "Deployment"]
+        "groups": ["Introduction", "Getting Started", "Guides", "Core Concepts", "Desktop Client", "Channels", "Agent Backends", "Tools", "Integrations", "Security", "Memory", "Advanced", "Deployment"]
      },
      {
        "label": "API Reference",
@@ -206,6 +206,31 @@
          }
        ]
      },
+      {
+        "label": "Desktop Client",
+        "items": [
+          {
+            "label": "Overview",
+            "href": "/desktop-client",
+            "icon": "lucide:monitor"
+          },
+          {
+            "label": "Installation",
+            "href": "/desktop-client/installation",
+            "icon": "lucide:download"
+          },
+          {
+            "label": "Development",
+            "href": "/desktop-client/development",
+            "icon": "lucide:code"
+          },
+          {
+            "label": "API Server (serve)",
+            "href": "/desktop-client/api-server",
+            "icon": "lucide:server"
+          }
+        ]
+      },
      {
        "label": "Core Concepts",
        "items": [