feat: Add browser documentation

docs-site/docs/desktop-and-local-api.md

@@ -0,0 +1,75 @@
+---
+sidebar_position: 3
+---
+
+# Desktop and Local API
+
+## Electron Hosting Model
+
+The desktop app hosts local documentation through the existing Electron Local API server. This server is implemented with Node's `http` module in the Electron main process and uses async request handlers for routing, file reads, and streamed responses.
+
+The endpoint is manually activated. Opening the Docusaurus docs from the desktop title bar enables the local server and docs endpoint if necessary, then opens the system browser to the generated static site.
+
+This avoids:
+
+- starting a Docusaurus development server inside Electron;
+- blocking the renderer thread;
+- serving docs from a remote host;
+- exposing the endpoint unless the user chooses to activate it.
+
+## Local Server Settings
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `false` | Starts or stops the local HTTP server. |
+| `port` | `17878` | Listening port. |
+| `exposeOnLan` | `false` | Uses `127.0.0.1` by default; when true, binds to `0.0.0.0`. |
+| `scalarEnabled` | `false` | Enables `/docs` for the Scalar OpenAPI reference. |
+| `docusaurusEnabled` | `false` | Enables `/docusaurus` for the built Docusaurus documentation. |
+| `allowedSignalingServers` | `[]` | Server URLs allowed for Local API login. |
+
+## Routes
+
+| Endpoint | Purpose | Auth |
+| --- | --- | --- |
+| `GET /api/health` | Liveness, app version, timestamp, and LAN exposure status. | No |
+| `GET /api/openapi.json` | OpenAPI 3.1 document for local automation clients. | No |
+| `GET /docs` | Scalar API reference when Scalar docs are enabled. | No |
+| `GET /docusaurus` | Docusaurus documentation entrypoint when Docusaurus docs are enabled. | No |
+| `GET /docusaurus/*` | Static Docusaurus assets and pages. | No |
+| `POST /api/auth/login` | Exchanges username, password, and allowed signaling server URL for a local bearer token. | No |
+| `POST /api/auth/logout` | Revokes the current local bearer token. | Bearer |
+| `GET /api/profile` | Reads the current local user profile. | Bearer |
+| `GET /api/rooms` | Lists rooms known to this device. | Bearer |
+| `GET /api/rooms/{roomId}/messages` | Reads local room messages with `limit` and `offset`. | Bearer |
+
+## Authentication Flow
+
+1. Add trusted signaling server URLs in desktop settings.
+2. Start the Local API server.
+3. Call `POST /api/auth/login` with `username`, `password`, and `serverUrl`.
+4. MetoYou validates credentials through the signaling server.
+5. The desktop app issues an opaque local bearer token.
+6. Use `Authorization: Bearer <token>` for protected routes.
+
+Bearer tokens are local to the running desktop app and are cleared when the Local API server stops.
+
+## Static Documentation Build
+
+Docusaurus is a static site generator. The repo builds `docs-site/` into `docs-site/build/`, and Electron serves those files from the local API server.
+
+Development commands:
+
+```bash
+cd docs-site
+npm install
+npm run start
+```
+
+Build command:
+
+```bash
+npm run build:docs
+```
+
+Packaged desktop builds include the generated static output as an Electron extra resource.