quoroom 0.1.24 → 0.1.26

package/README.md

@@ -111,6 +111,8 @@ Quoroom is an open research project exploring autonomous agent collectives. Each
 
 **Dashboard** — React SPA served directly by your local Quoroom server at `http://localhost:3700` (or your configured port). Manage rooms, agents, goals, memory, wallet — all from the browser, with local-first data storage.
 
+**Clerk** — A fully functional keeper assistant in the dashboard. It can chat across all rooms, remember context and history, act proactively, and execute management actions (create/update rooms, tasks, reminders, messaging) while streaming live commentary about swarm activity.
+
 **Cloud Mode** — Deploy to the cloud and control your room remotely. Same dashboard works in both local and cloud mode. Cloud instances auto-detect their environment, support JWT-based auth, and serve the UI over HTTPS with strict CORS. Connect your Claude or Codex subscription from the remote Settings panel.
 
 **Inbox** — Rooms can message the keeper and other rooms. Cross-room communication with reply threading. Agents escalate decisions, share updates, or request resources from neighboring rooms.
@@ -185,6 +187,10 @@ brew install quoroom-ai/quoroom/quoroom
 
 Download from [GitHub Releases](https://github.com/quoroom-ai/room/releases). Installers add `quoroom` to your PATH automatically. No dependencies needed.
 
+Installer launchers:
+- macOS `.pkg`: open `/Applications/Quoroom Server.app`
+- Windows `.exe`: Start Menu -> Quoroom Server -> Open Quoroom Server
+
 | Platform | Installer | Archive |
 |----------|-----------|---------|
 | macOS (Apple Silicon + Intel) | `.pkg` | `.tar.gz` |
@@ -208,12 +214,35 @@ Removes Quoroom binaries, all data, and logs. Prompts for confirmation before pr
 quoroom serve
 ```
 
+If you installed with the macOS `.pkg` or Windows `.exe` installer, you can also use the launcher app/shortcut instead of command line.
+
 On first run, `quoroom serve` automatically registers the Quoroom MCP server in every AI coding tool you have installed (Claude Code, Claude Desktop, Cursor, Windsurf). Just **restart your AI client once** — after that, all `mcp__quoroom__*` tools are available automatically in every session.
 
 Open **http://localhost:3700** (or the port shown in your terminal). The dashboard and API run locally, and your room data stays on your machine by default.
 
 > **MCP-only mode** (no HTTP server): `quoroom mcp` starts just the stdio MCP transport, useful for scripting or testing. For normal use, `quoroom serve` is all you need.
 
+## Clerk
+
+The **Clerk** tab is your global assistant for the whole local system (not a single room).
+
+- Clerk is a full assistant, not only commentary: it can reason, remember, and execute actions for the keeper
+- Setup paths: Claude subscription (`claude`), Codex subscription (`codex`), OpenAI API (`openai:gpt-4o-mini`), Anthropic API (`anthropic:claude-3-5-sonnet-latest`)
+- API keys entered in Clerk Setup are validated before saving
+- Clerk can answer and do: room lifecycle, room settings, task creation, reminders, inter-room messaging, and keeper communication
+- Clerk can act proactively through scheduled tasks/reminders and activity-driven commentary
+- Telegram and Email are important Clerk control channels: connect at least one so Clerk can always reach you, keep reminders flowing, and store those conversations in Clerk memory
+- Email replies are threaded when possible, and Telegram replies are direct/real-time for fast keeper control
+- Live commentary streams over WebSocket channel `clerk` while rooms are running
+
+API key resolution for Clerk API models:
+
+1. Any room credential (`openai_api_key` or `anthropic_api_key`)
+2. Clerk-saved API key (`clerk_openai_api_key` / `clerk_anthropic_api_key`)
+3. Environment variable (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY`)
+
+See full guide: [docs/CLERK.md](docs/CLERK.md)
+
 ---
 
 ## All Tools