Add static docs site and agent-friendly CLI output

.gitignore

@@ -5,3 +5,5 @@ node_modules/
 /beeper-desktop-cli
 .upstream/
 *.exe
+
+.claude/

README.md

@@ -1,6 +1,15 @@
-# beeper — One CLI for all your chats
+<div align="center">
 
-> Built for you and your agent. Batteries included.
+# beeper
+
+**One CLI for all your chats.** Built for you and your agent — batteries included.
+
+[![npm](https://img.shields.io/npm/v/beeper-cli.svg?label=npm&color=6E56F8)](https://www.npmjs.com/package/beeper-cli)
+[![license](https://img.shields.io/badge/license-MIT-6E56F8.svg)](https://github.com/beeper/cli/blob/main/packages/cli/LICENSE)
+[![docs](https://img.shields.io/badge/docs-online-6E56F8.svg)](https://beeper.github.io/cli)
+[![built with Bun](https://img.shields.io/badge/built%20with-Bun-6E56F8.svg)](https://bun.sh)
+
+</div>
 
 Talks to Beeper Desktop on this machine, to a Beeper Server you self-host, or
 to either one running somewhere else. Send and receive across the chat
@@ -13,7 +22,7 @@ Facebook Messenger · X (Twitter) DMs · LinkedIn · Slack ·
 Google Messages (RCS/SMS) · Google Chat · Matrix · IRC · Bluesky.
 Run `beeper bridges list` for the live list on your target.
 
-Command manual: `beeper man` · CLI docs: `beeper docs`
+📖 **[Read the docs](https://beeper.github.io/cli)** · command manual: `beeper man` · open docs: `beeper docs`
 
 ## Features
 
@@ -193,19 +202,22 @@ WhatsApp, Telegram, Discord, iMessage, and the rest show up under `accounts list
 
 ## Documentation
 
+Full documentation lives at **[beeper.github.io/cli](https://beeper.github.io/cli)**
+(built from [`docs/`](docs/) with Astro Starlight — a fully static site).
+
 | Topic | Page | Commands |
 | --- | --- | --- |
-| **Setup + install** | [setup](docs/setup.md) · [auth](docs/auth.md) | `setup` · `install desktop` · `install server` · `verify` · `status` · `doctor` · `auth status` |
-| **Targets** | [targets](docs/targets.md) | `targets list` · `targets add desktop` · `targets add server` · `targets add remote` · `targets use` · `targets status` · `targets logs` |
-| **Bridges + accounts** | [accounts](docs/accounts.md) | `bridges list` · `bridges show` · `accounts list` · `accounts add` · `accounts show` · `accounts use` · `accounts remove` |
-| **Chats** | [chats](docs/chats.md) | `chats list` · `chats search` · `chats show` · `chats start` · `chats archive` · `chats pin` · `chats mute` · `chats priority` · `chats remind` · `chats rename` · `chats draft` · `chats focus` |
-| **Messages** | [messages](docs/messages.md) · [send](docs/send.md) · [presence](docs/presence.md) | `messages list` · `messages search` · `messages export` · `send text` · `send file` · `send sticker` · `send voice` · `send react` · `presence` |
-| **Contacts + media** | [contacts](docs/contacts.md) · [media](docs/media.md) · [export](docs/export.md) | `contacts list` · `contacts search` · `media download` · `export` |
-| **Automation** | [watch](docs/watch.md) · [rpc](docs/rpc.md) · [api](docs/api.md) | `watch` · `watch --webhook` · `rpc` · `man` · `api get` · `api post` · `api request` |
-| **Maintenance** | [config](docs/config.md) · [update](docs/update.md) | `update` · `config` · `completion` · `docs` · `version` |
+| **Setup + install** | [connect](https://beeper.github.io/cli/connect/) · [install](https://beeper.github.io/cli/install/) · [auth](https://beeper.github.io/cli/auth/) | `setup` · `install desktop` · `install server` · `verify` · `status` · `doctor` · `auth status` |
+| **Targets** | [targets](https://beeper.github.io/cli/targets/) | `targets list` · `targets add desktop` · `targets add server` · `targets add remote` · `targets use` · `targets status` · `targets logs` |
+| **Bridges + accounts** | [accounts](https://beeper.github.io/cli/accounts/) | `bridges list` · `bridges show` · `accounts list` · `accounts add` · `accounts show` · `accounts use` · `accounts remove` |
+| **Chats** | [chats](https://beeper.github.io/cli/chats/) | `chats list` · `chats search` · `chats show` · `chats start` · `chats archive` · `chats pin` · `chats mute` · `chats priority` · `chats remind` · `chats rename` · `chats draft` · `chats focus` |
+| **Messages** | [messages](https://beeper.github.io/cli/messages/) · [send](https://beeper.github.io/cli/send/) · [presence](https://beeper.github.io/cli/presence/) | `messages list` · `messages search` · `messages export` · `send text` · `send file` · `send sticker` · `send voice` · `send react` · `presence` |
+| **Contacts + media** | [contacts](https://beeper.github.io/cli/contacts/) · [media](https://beeper.github.io/cli/media/) · [export](https://beeper.github.io/cli/export/) | `contacts list` · `contacts search` · `media download` · `export` |
+| **Automation** | [scripting](https://beeper.github.io/cli/scripting/) · [watch](https://beeper.github.io/cli/watch/) · [rpc](https://beeper.github.io/cli/rpc/) · [api](https://beeper.github.io/cli/api/) | `watch` · `watch --webhook` · `rpc` · `man` · `api get` · `api post` · `api request` |
+| **Maintenance** | [config](https://beeper.github.io/cli/config/) · [update](https://beeper.github.io/cli/update/) | `update` · `config` · `completion` · `docs` · `version` |
 
 Use `beeper docs` to open the CLI docs and `beeper man` to print the local
-command manual.
+command manual. To work on the docs site locally: `cd docs && bun install && bun run dev`.
 
 ## Configuration
 

docs/.gitignore

@@ -0,0 +1,16 @@
+# build output
+dist/
+# generated types
+.astro/
+# dependencies
+node_modules/
+# environment
+.env
+.env.production
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+# macOS
+.DS_Store

docs/astro.config.mjs

@@ -0,0 +1,100 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+// Fully static export. `output: 'static'` is Astro's default; it is set
+// explicitly here so the intent is obvious and `astro build` always emits a
+// self-contained `./dist` you can drop on any static host or CDN.
+//
+// When you pick a home for the docs, set `site` to the canonical origin (used
+// for sitemap + canonical URLs) and, if serving from a sub-path, set `base`.
+export default defineConfig({
+  site: 'https://beeper.github.io',
+  base: '/cli/',
+  output: 'static',
+  trailingSlash: 'always',
+  integrations: [
+    starlight({
+      title: 'Beeper CLI',
+      description:
+        'One CLI for all your chats — WhatsApp, iMessage, Telegram, Signal, Discord and more, shaped for scripts, agents, and humans in a hurry.',
+      tagline: 'One CLI for all your chats. Built for you and your agent.',
+      logo: {
+        src: './src/assets/logo.svg',
+        replacesTitle: false,
+      },
+      social: [
+        {
+          icon: 'github',
+          label: 'GitHub',
+          href: 'https://github.com/beeper/cli',
+        },
+      ],
+      editLink: {
+        baseUrl:
+          'https://github.com/beeper/cli/edit/main/docs/',
+      },
+      customCss: ['./src/styles/theme.css'],
+      // Starlight ships full-text search (Pagefind) and dark mode by default.
+      sidebar: [
+        {
+          label: 'Start here',
+          items: [
+            { label: 'Overview', link: '/' },
+            { label: 'Install', link: '/install/' },
+            { label: 'Connect a target', link: '/connect/' },
+            { label: 'Quick start', link: '/quickstart/' },
+          ],
+        },
+        {
+          label: 'Targets & accounts',
+          items: [
+            { label: 'Targets', link: '/targets/' },
+            { label: 'Bridges & accounts', link: '/accounts/' },
+            { label: 'Auth & verification', link: '/auth/' },
+          ],
+        },
+        {
+          label: 'Messaging',
+          items: [
+            { label: 'Chats', link: '/chats/' },
+            { label: 'Messages', link: '/messages/' },
+            { label: 'Sending', link: '/send/' },
+            { label: 'Contacts', link: '/contacts/' },
+            { label: 'Media', link: '/media/' },
+            { label: 'Export', link: '/export/' },
+            { label: 'Presence', link: '/presence/' },
+          ],
+        },
+        {
+          label: 'Automation & agents',
+          items: [
+            { label: 'Output & scripting', link: '/scripting/' },
+            { label: 'Watch (live events)', link: '/watch/' },
+            { label: 'RPC', link: '/rpc/' },
+            { label: 'Raw API access', link: '/api/' },
+            { label: 'Exit codes', link: '/exit-codes/' },
+          ],
+        },
+        {
+          label: 'Reference',
+          items: [
+            { label: 'Configuration', link: '/config/' },
+            { label: 'Plugins', link: '/plugins/' },
+            { label: 'Updating', link: '/update/' },
+            {
+              label: 'Full command reference',
+              link: 'https://github.com/beeper/cli/blob/main/packages/cli/README.md',
+              attrs: { target: '_blank' },
+            },
+            {
+              label: 'Desktop API reference',
+              link: 'https://developers.beeper.com/desktop-api-reference',
+              attrs: { target: '_blank' },
+            },
+          ],
+        },
+      ],
+    }),
+  ],
+});