docs: migrate to scalar on github pages

.github/workflows/docs-pages.yml

@@ -0,0 +1,43 @@
+name: Docs (Scalar)
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "scalar/**"
+      - ".github/workflows/docs-pages.yml"
+      - "docs/**"
+      - "README.md"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./scalar
+
+      - name: Deploy To GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -37,7 +37,8 @@ Output controls:
 
 ```bash
 bluebubbles contact list
-bluebubbles chat list -o json
+bluebubbles chats list -o wide
+bluebubbles chats list -o json
 ```
 
 Human-readable output (`columnify`) is the default:
@@ -48,7 +49,7 @@ Alex Rivera     +1-555-0100       alex@example.com
 Taylor Kim      +1-555-0199       taylor@example.com
 ```
 
-`message list` uses the same default table style:
+`messages list` uses the same default table style:
 
 ```text
 GUID                        FROM       TEXT                          AGE   CHAT
@@ -74,45 +75,45 @@ JSON output is available with `-o json` or `--json`:
 For messages:
 
 ```bash
-bluebubbles message list --chat 'iMessage;+;chat123'
-bluebubbles message list --chat 'iMessage;+;chat123' --json
+bluebubbles messages list --chat 'iMessage;+;chat123'
+bluebubbles messages list --chat 'iMessage;+;chat123' --json
 ```
 
 Pagination defaults are conservative for message-heavy commands:
 
-- `bluebubbles message list` defaults to `--limit 50`
-- `bluebubbles chat messages <guid>` defaults to `--limit 50`
+- `bluebubbles messages list` defaults to `--limit 50`
+- `bluebubbles chats messages <guid>` defaults to `--limit 50`
 
 ## Query and filter examples
 
 Get all messages for one conversation in pages:
 
 ```bash
-bluebubbles message list --chat 'iMessage;+;chat123' --limit 50 --offset 0 --json
-bluebubbles message list --chat 'iMessage;+;chat123' --limit 50 --offset 50 --json
-bluebubbles message list --chat 'iMessage;+;chat123' --limit 50 --offset 100 --json
+bluebubbles messages list --chat 'iMessage;+;chat123' --limit 50 --offset 0 --json
+bluebubbles messages list --chat 'iMessage;+;chat123' --limit 50 --offset 50 --json
+bluebubbles messages list --chat 'iMessage;+;chat123' --limit 50 --offset 100 --json
 ```
 
 Filter by date window (epoch seconds):
 
 ```bash
-bluebubbles message list --chat 'iMessage;+;chat123' --after 1710000000 --before 1710086400 --json
+bluebubbles messages list --chat 'iMessage;+;chat123' --after 1710000000 --before 1710086400 --json
 ```
 
 Common filters:
 
 ```bash
-bluebubbles message list --chat 'iMessage;+;chat123' --text 'invoice' --limit 50 --json
-bluebubbles message list --chat 'iMessage;+;chat123' --from '+15551234567' --not-from-me --json
-bluebubbles message list --chat 'iMessage;+;chat123' --from-me --has-attachments --json
+bluebubbles messages list --chat 'iMessage;+;chat123' --text 'invoice' --limit 50 --json
+bluebubbles messages list --chat 'iMessage;+;chat123' --from '+15551234567' --not-from-me --json
+bluebubbles messages list --chat 'iMessage;+;chat123' --from-me --has-attachments --json
 ```
 
 Common filters are applied client-side to the returned page. Use `--where` for raw server-side filtering.
 
 Advanced filtering via raw API `where` clauses:
 
 ```bash
-bluebubbles message list \
+bluebubbles messages list \
   --where '[{"statement":"message.text LIKE :q","args":{"q":"%hello%"}}]' \
   --limit 50 \
   --json
@@ -121,27 +122,38 @@ bluebubbles message list \
 Conversation endpoint alternative:
 
 ```bash
-bluebubbles chat messages 'iMessage;+;chat123' --limit 50 --offset 0 --json
-bluebubbles chat messages 'iMessage;+;chat123' --after 1710000000 --before 1710086400 --json
+bluebubbles chats messages 'iMessage;+;chat123' --limit 50 --offset 0 --json
+bluebubbles chats messages 'iMessage;+;chat123' --after 1710000000 --before 1710086400 --json
 ```
 
 ## Command shape
 
 ```bash
 bluebubbles ping
 bluebubbles server info
+bluebubbles server open
 bluebubbles server status
 bluebubbles server logs
 bluebubbles server logs --source api
-bluebubbles chat list
-bluebubbles message send --chat <guid> --message "hello"
-bluebubbles message schedule list
+bluebubbles chats list
+bluebubbles messages send --chat <guid> --message "hello"
+bluebubbles messages schedule list
 bluebubbles handle availability <address>
 bluebubbles attachment download <guid>
 bluebubbles contact query --address user@example.com
 bluebubbles icloud account
 ```
 
+Verbose diagnostics:
+
+```bash
+bluebubbles messages list --chat 'iMessage;+;chat123' --verbose
+```
+
+`--verbose` prints request/response diagnostics to stderr. You can also set `BLUEBUBBLES_VERBOSE=1`.
+
+Request timeout defaults to `10000ms` and can be overridden with `BLUEBUBBLES_REQUEST_TIMEOUT_MS`.
+
 ## Configuration
 
 Persist config:
@@ -166,14 +178,19 @@ export BLUEBUBBLES_PASSWORD='your#server#password'
 
 ## Docs
 
-Mintlify is configured through the local `mint` dev dependency.
+Docs are served via Scalar and deployed to GitHub Pages.
 
 ```bash
-bun run docs:sync-openapi
 bun run docs:dev
 bun run docs:validate
 ```
 
+GitHub Pages workflow publishes `scalar/index.html` at:
+
+```text
+https://anmho.github.io/bluebubbles-cli/
+```
+
 `test:commands` is local-only by design. It exercises all registered CLI commands and can skip unavailable API/local prerequisites in tolerant mode. It uses the same auth sources as normal CLI runs (`BLUEBUBBLES_*` env vars or persisted `bluebubbles config` values).
 
 The API Reference tab renders from `docs/openapi.yaml`, which is a pinned copy of the official BlueBubbles OpenAPI source:

docs/cli-reference.mdx

@@ -10,8 +10,8 @@ bluebubbles config ...
 bluebubbles doctor
 bluebubbles ping
 bluebubbles server ...
-bluebubbles chat ...
-bluebubbles message ...
+bluebubbles chats ...
+bluebubbles messages ...
 bluebubbles handle ...
 bluebubbles attachment ...
 bluebubbles contact ...
@@ -23,8 +23,9 @@ bluebubbles webhook ...
 
 Most API commands support:
 
-- `-o, --output <format>` where format is `table` or `json`
+- `-o, --output <format>` where format is `table`, `wide`, or `json`
 - `--json` as an alias for `-o json`
+- `-v, --verbose` for API diagnostics to stderr
 
 ## Endpoint-mapped commands
 
@@ -41,6 +42,8 @@ Most API commands support:
   Local process manager, no API endpoint
 - `bluebubbles server logs --source api [--count <n>]`
   API: `GET /api/v1/server/logs`
+- `bluebubbles server open`
+  Local process manager, no API endpoint
 - `bluebubbles server start`
   Local process manager, no API endpoint
 - `bluebubbles server status`
@@ -76,59 +79,59 @@ Most API commands support:
 
 ### Chat
 
-- `bluebubbles chat list`
+- `bluebubbles chats list`
   API: `POST /api/v1/chat/query`
-- `bluebubbles chat get <guid>`
+- `bluebubbles chats get <guid>`
   API: `GET /api/v1/chat/<Chat GUID>`
-- `bluebubbles chat messages <guid>`
+- `bluebubbles chats messages <guid>`
   API: `GET /api/v1/chat/<Chat GUID>/message`
   Notes: defaults to `--limit 50`; supports `--after` and `--before`
-- `bluebubbles chat update <guid> --name <name>`
+- `bluebubbles chats update <guid> --name <name>`
   API: `PUT /api/v1/chat/<Chat GUID>`
-- `bluebubbles chat delete <guid> [--yes]`
+- `bluebubbles chats delete <guid> [--yes]`
   API: `DELETE /api/v1/chat/<Chat GUID>`
-- `bluebubbles chat group leave <guid> [--yes]`
+- `bluebubbles chats group leave <guid> [--yes]`
   API: `POST /api/v1/chat/<Chat GUID>/leave`
-- `bluebubbles chat group participant add <guid> <address>`
+- `bluebubbles chats group participant add <guid> <address>`
   API: `POST /api/v1/chat/<Chat GUID>/participant`
-- `bluebubbles chat group participant remove <guid> <address> [--yes]`
+- `bluebubbles chats group participant remove <guid> <address> [--yes]`
   API: `DELETE /api/v1/chat/<Chat GUID>/participant`
-- `bluebubbles chat group icon set <guid>`
+- `bluebubbles chats group icon set <guid>`
   API: `POST /api/v1/chat/<Chat GUID>/icon`
-- `bluebubbles chat group icon remove <guid> [--yes]`
+- `bluebubbles chats group icon remove <guid> [--yes]`
   API: `DELETE /api/v1/chat/<Chat GUID>/icon`
-- `bluebubbles chat typing start <guid>`
+- `bluebubbles chats typing start <guid>`
   API: `POST /api/v1/chat/<Chat GUID>/typing`
-- `bluebubbles chat typing stop <guid>`
+- `bluebubbles chats typing stop <guid>`
   API: `DELETE /api/v1/chat/<Chat GUID>/typing`
 
 ### Message
 
-- `bluebubbles message list`
+- `bluebubbles messages list`
   API: `POST /api/v1/message/query`
   Notes: defaults to `--limit 50`; supports `--chat`, `--after`, `--before`, common filters (`--text`, `--from`, `--from-me`, `--not-from-me`, `--has-attachments`), and raw `--where '<json>'`. `--text`, `--from`, and `--has-attachments` are applied client-side to the returned page.
-- `bluebubbles message get <guid>`
+- `bluebubbles messages get <guid>`
   API: `GET /api/v1/message/<GUID>`
-- `bluebubbles message send --chat <guid> --message <text>`
+- `bluebubbles messages send --chat <guid> --message <text>`
   API: `POST /api/v1/message/text`
-- `bluebubbles message react <guid> --chat <guid> --reaction <type>`
+- `bluebubbles messages react <guid> --chat <guid> --reaction <type>`
   API: `POST /api/v1/message/react`
-- `bluebubbles message edit <guid> --message <text>`
+- `bluebubbles messages edit <guid> --message <text>`
   API: `POST /api/v1/message/<GUID>/edit`
-- `bluebubbles message unsend <guid> [--yes]`
+- `bluebubbles messages unsend <guid> [--yes]`
   API: `POST /api/v1/message/<GUID>/unsend`
 
 ### Message Schedule
 
-- `bluebubbles message schedule list`
+- `bluebubbles messages schedule list`
   API: `GET /api/v1/message/schedule`
-- `bluebubbles message schedule get <id>`
+- `bluebubbles messages schedule get <id>`
   API: `GET /api/v1/message/schedule/<ID>`
-- `bluebubbles message schedule create --chat <guid> --message <text> --date <date>`
+- `bluebubbles messages schedule create --chat <guid> --message <text> --date <date>`
   API: `POST /api/v1/message/schedule`
-- `bluebubbles message schedule update <id>`
+- `bluebubbles messages schedule update <id>`
   API: `PUT /api/v1/message/schedule/<ID>`
-- `bluebubbles message schedule delete <id> [--yes]`
+- `bluebubbles messages schedule delete <id> [--yes]`
   API: `DELETE /api/v1/message/schedule/<ID>`
 
 ### Handle

docs/development.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Development"
-description: "Build, test, and validate the curated BlueBubbles CLI and Mintlify docs."
+description: "Build, test, and validate the curated BlueBubbles CLI and Scalar docs."
 ---
 
 ## CLI workflow
@@ -16,24 +16,22 @@ bun run build
 
 ## Docs workflow
 
-The repo uses the local `mint` dev dependency. There is no separate scraper step in the current setup.
+Docs are served from the `scalar/` directory and deployed with GitHub Pages.
 
 ```bash
-bun run docs:sync-openapi
 bun run docs:dev
 bun run docs:validate
 ```
 
-Mintlify reads `docs/openapi.yaml`, which is kept as a pinned copy of the official upstream spec:
+Scalar reads the official upstream OpenAPI spec directly:
 
 ```text
-docs/openapi.yaml
+https://raw.githubusercontent.com/Jish2/bluebubbles-sdk/main/openapi.yaml
 ```
 
 ## Notes
 
 - CLI usage docs are hand-curated.
-- API reference pages are rendered from the pinned OpenAPI file rather than maintained as generated MDX snapshots.
+- API reference pages are rendered by Scalar from the upstream OpenAPI file.
 - The upstream source of truth remains `https://raw.githubusercontent.com/Jish2/bluebubbles-sdk/main/openapi.yaml`.
-- `docs:sync-openapi` applies a minimal Mint compatibility patch when the upstream file has empty `responses` objects.
 - The CLI runtime uses the repo's `@anmho/bluebubbles-sdk` client layer.

docs/doctor.mdx

@@ -12,7 +12,7 @@ description: "Diagnostic checks for API connectivity, local server readiness, an
 - local app discovery on macOS
 - local process state
 - BlueBubbles API reachability via `ping`
-- the official OpenAPI spec URL used by Mintlify
+- the official OpenAPI spec URL used by Scalar docs
 - configured log path availability
 
 ## Example

docs/index.mdx

@@ -25,7 +25,7 @@ description: "A curated BlueBubbles terminal CLI organized around the resources
     icon="power-off"
     href="/local-server"
   >
-    Manage a local BlueBubbles Server app through `bluebubbles server start|stop|restart|status|logs`.
+    Manage a local BlueBubbles Server app through `bluebubbles server open|start|stop|restart|status|logs`.
   </Card>
   <Card
     title="Webhooks"
@@ -38,15 +38,15 @@ description: "A curated BlueBubbles terminal CLI organized around the resources
     title="API reference"
     icon="square-code"
   >
-    Mintlify renders a pinned copy of the official BlueBubbles OpenAPI spec from `docs/openapi.yaml`.
+    Scalar renders the official BlueBubbles OpenAPI spec as an interactive API reference.
   </Card>
 </Columns>
 
 ## Positioning
 
 This CLI is intentionally curated.
 
-- Root help is resource-first: `ping`, `server`, `chat`, `message`, `handle`, `attachment`, `contact`, `icloud`, `webhook`, `config`, `doctor`.
+- Root help is resource-first: `ping`, `server`, `chats`, `messages`, `handle`, `attachment`, `contact`, `icloud`, `webhook`, `config`, `doctor`.
 - Low-value or risky clutter like `fcm`, `mac`, and web-only commands is removed.
 - Server-owned admin state is nested under `server`, including `server settings` and `server theme`.
 - Each retained command is documented with the API endpoint it corresponds to.
@@ -55,4 +55,4 @@ This CLI is intentionally curated.
 
 - API commands go through the `@anmho/bluebubbles-sdk` client layer in this repo.
 - Local lifecycle commands manage an installed BlueBubbles Server app on macOS.
-- Mintlify uses `docs/openapi.yaml`, a pinned copy of the official BlueBubbles OpenAPI spec.
+- Scalar docs read the official BlueBubbles OpenAPI spec from upstream.

docs/local-server.mdx

@@ -8,6 +8,7 @@ description: "Manage an installed BlueBubbles Server app on macOS."
 These commands are local process-manager operations, not API calls.
 
 ```bash
+bluebubbles server open
 bluebubbles server start
 bluebubbles server status
 bluebubbles server stop