quoroom 0.1.0 → 0.1.2

package/README.md

@@ -7,9 +7,12 @@
 # Quoroom
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![npm version](https://img.shields.io/badge/npm-v0.1.0-blue)](https://www.npmjs.com/package/quoroom)
-[![Tests](https://img.shields.io/badge/tests-806%20passing-brightgreen)](#)
+[![npm version](https://img.shields.io/npm/v/quoroom)](https://www.npmjs.com/package/quoroom)
+[![Tests](https://img.shields.io/badge/tests-804%20passing-brightgreen)](#)
 [![GitHub stars](https://img.shields.io/github/stars/quoroom-ai/room)](https://github.com/quoroom-ai/room/stargazers)
+[![macOS](https://img.shields.io/badge/macOS-.pkg-000000?logo=apple&logoColor=white)](https://github.com/quoroom-ai/room/releases/latest)
+[![Windows](https://img.shields.io/badge/Windows-.exe-0078D4?logo=windows&logoColor=white)](https://github.com/quoroom-ai/room/releases/latest)
+[![Linux](https://img.shields.io/badge/Linux-.deb-FCC624?logo=linux&logoColor=black)](https://github.com/quoroom-ai/room/releases/latest)
 
 **An open research project in autonomous agent collectives.**
 
@@ -40,18 +43,18 @@ The architecture draws from swarm intelligence research: decentralized decision-
 Quoroom is an open research project exploring autonomous agent collectives. Each collective (a **Room**) is a self-governing swarm of agents.
 
 - **Queen** — strategic brain, uses Claude CLI
-- **Workers** — a swarm of specialized agents, use Ollama (free)
+- **Workers** — specialized agents (Ollama, free): Researcher, Coder, Marketer, Analyst — or any custom role
 - **Quorum** — agents deliberate and vote on decisions
-- **Keeper** — the human who created and funds the room
+- **Keeper** — the human who sets goals and funds the wallet
 
 ## This Repo
 
-`quoroom-ai/room` is the headless engine: agent loop, quorum governance, goals, skills, self-modification, wallet, stations, memory, task scheduling, file watching, MCP server, and CLI.
+`quoroom-ai/room` is the engine: agent loop, quorum governance, goals, skills, self-modification, wallet, stations, memory, task scheduling, file watching, MCP server, HTTP/WebSocket API, dashboard UI, and CLI.
 
 | Repo | Purpose |
 |------|---------|
 | **room** (this) | Engine + HTTP server + UI |
-| [cloud](https://github.com/quoroom-ai/cloud) | Station infrastructure + portal |
+| [cloud](https://github.com/quoroom-ai/cloud) | Landing page, public rooms, PostgreSQL, station infrastructure |
 
 ---
 
@@ -59,6 +62,8 @@ Quoroom is an open research project exploring autonomous agent collectives. Each
 
 **Rooms** — Create autonomous agent collectives with a Queen and Workers. Pause, restart, monitor activity.
 
+**Activity Controls** — Throttle the queen per room: configurable cycle gap (sleep between runs), max turns per cycle, and quiet hours (time window where the queen rests). Plan-aware defaults (Pro/Max/API/None) apply automatically when you create a new room based on your Claude subscription tier.
+
 **Quorum Voting** — Agents propose and vote on decisions. Majority, supermajority, or unanimous — you choose the threshold.
 
 **Goals** — Hierarchical goal decomposition with progress tracking. Set a top-level objective and let agents break it down.
@@ -79,6 +84,14 @@ Quoroom is an open research project exploring autonomous agent collectives. Each
 
 **File Watching** — Monitor files and folders, trigger Claude Code actions on change.
 
+**Auto / Semi Mode** — Two autonomy modes. Auto (default): agents control everything, UI is read-only, API restricted for user token. Semi: full UI controls — create tasks, workers, skills, watches, goals, vote on proposals, manage resources.
+
+**Public Rooms** — Toggle your room public on [quoroom.ai/rooms](https://quoroom.ai/rooms). Stats, earnings leaderboard, auto/semi mode badges. Room registers with cloud and sends heartbeats every 5 minutes. No account needed to browse.
+
+**HTTP Server + REST API** — Full REST API with dual-token auth (agent + user) and WebSocket real-time events. Role-based access control per autonomy mode. Run `quoroom serve` to start.
+
+**Dashboard** — React SPA at [app.quoroom.ai](https://app.quoroom.ai). Manage rooms, agents, goals, memory, wallet — all from the browser. The UI loads from CDN but connects to your local server — all data stays on your machine.
+
 ---
 
 ## Architecture
@@ -100,22 +113,68 @@ Quoroom is an open research project exploring autonomous agent collectives. Each
 │  │ Wallet │  │ Stations │  │ Task Scheduler │  │
 │  │(Base L2)│  │(Fly/E2B) │  │ (cron/once)    │  │
 │  └────────┘  └──────────┘  └────────────────┘  │
-└─────────────────────────────────────────────────┘
-         ▲
-         │ stdio
-    MCP Server (quoroom_* tools)
+│                                                  │
+│  ┌──────────────────────────────────────────┐   │
+│  │  Auth: agent token (full) + user token   │   │
+│  │  Access: auto mode (restricted) / semi   │   │
+│  └──────────────────────────────────────────┘   │
+└────────────────────┬────────────────────────────┘
+                     │
+        ┌────────────┼────────────┐
+        │            │            │
+   MCP Server   HTTP/REST    WebSocket
+    (stdio)    (port 3700)   (real-time)
+                     │
+        ┌────────────┼────────────┐
+        │                         │
+ ┌──────┴──────┐         ┌───────┴───────┐
+ │  Dashboard  │         │  Cloud Sync   │
+ │ app.quoroom │         │ quoroom.ai    │
+ └─────────────┘         │  /rooms page  │
+                          └───────────────┘
 ```
 
 ---
 
+## Install
+
+### npm (recommended)
+
+```bash
+npm install -g quoroom
+```
+
+### Homebrew (macOS)
+
+```bash
+brew install quoroom-ai/quoroom/quoroom
+```
+
+### Download
+
+Download from [GitHub Releases](https://github.com/quoroom-ai/room/releases). Installers add `quoroom` to your PATH automatically. No dependencies needed.
+
+| Platform | Installer | Archive |
+|----------|-----------|---------|
+| macOS (Apple Silicon + Intel) | `.pkg` | `.tar.gz` |
+| Linux x64 | `.deb` | `.tar.gz` |
+| Windows x64 (signed) | `.exe` setup | `.zip` |
+
+---
+
 ## Quick Start
 
 ```bash
-npm install
-npm run build
-npm test          # 806+ tests
+# Start the HTTP/WebSocket API server + dashboard
+quoroom serve
 ```
 
+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 **[app.quoroom.ai](https://app.quoroom.ai)** — the dashboard loads from CDN but all API calls go to `localhost`. Your data never leaves your machine.
+
+> **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.
+
 ---
 
 ## All Tools
@@ -264,12 +323,20 @@ The room engine exposes an MCP server over stdio. All tools use the `quoroom_` p
 
 ```bash
 npm install              # Install dependencies
-npm run build            # Typecheck + bundle MCP server (esbuild)
+npm run build            # Typecheck + bundle MCP server + build UI
+npm run build:mcp        # Bundle MCP server only (esbuild)
+npm run build:ui         # Build UI SPA only (Vite)
+npm run dev:ui           # UI dev server with hot reload
 npm run typecheck        # Type-check only (tsc --noEmit)
 npm test                 # Run all tests (vitest, fork pool)
 npm run test:watch       # Watch mode
+npm run test:e2e         # End-to-end tests (Playwright)
 ```
 
+## Releasing
+
+Use the release runbook: [`docs/RELEASE_RUNBOOK.md`](docs/RELEASE_RUNBOOK.md)
+
 <details>
 <summary>Project structure</summary>
 
@@ -281,6 +348,18 @@ room/
 │   │   ├── server.ts      # Tool registration
 │   │   ├── db.ts          # Database initialization
 │   │   └── tools/         # 13 tool modules
+│   ├── server/            # HTTP/WebSocket API server
+│   │   ├── index.ts       # Server bootstrap
+│   │   ├── router.ts      # Request router
+│   │   ├── auth.ts        # Dual-token auth + CORS
+│   │   ├── access.ts      # Role-based access control
+│   │   ├── ws.ts          # WebSocket real-time events
+│   │   └── routes/        # REST API routes
+│   ├── ui/                # React SPA dashboard
+│   │   ├── App.tsx        # Root component
+│   │   ├── components/    # UI components
+│   │   ├── hooks/         # React hooks
+│   │   └── lib/           # API client, auth, WebSocket
 │   └── shared/            # Core engine
 │       ├── agent-loop.ts       # Worker agent loop with rate limiting
 │       ├── agent-executor.ts   # Claude Code CLI execution
@@ -295,13 +374,15 @@ room/
 │       ├── db-queries.ts       # Database query layer
 │       ├── schema.ts           # SQLite schema (WAL mode)
 │       ├── embeddings.ts       # Vector embeddings (all-MiniLM-L6-v2)
+│       ├── cloud-sync.ts      # Cloud registration + heartbeat
 │       └── __tests__/          # Test suite
+├── e2e/                    # Playwright end-to-end tests
 ├── scripts/
 │   └── build-mcp.js       # esbuild bundling
 └── docs/                   # Media assets
 ```
 
-**Tech stack**: TypeScript (strict), better-sqlite3, sqlite-vec, viem, MCP SDK, HuggingFace Transformers, node-cron, zod, esbuild, Vitest
+**Tech stack**: TypeScript (strict), React, Tailwind CSS, better-sqlite3, sqlite-vec, viem, MCP SDK, HuggingFace Transformers, node-cron, zod, esbuild, Vite, Vitest
 
 </details>