From c43cd0fb5d2a500eff5384d4452e1402bf176185 Mon Sep 17 00:00:00 2001
From: viettranx <viettranx@gmail.com>
Date: Fri, 27 Mar 2026 10:33:24 +0700
Subject: [PATCH] docs: add desktop edition notes to CLAUDE.md

Desktop tech stack, build commands, edition system, WS param naming,
auto-update flow, release process, lite limits, tool gating, file
serving security model. Add sqliteonly build check to post-impl checklist.
---
 CLAUDE.md | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1cd5a3a0..f87fde6b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,7 +6,9 @@ PostgreSQL multi-tenant AI agent gateway with WebSocket RPC + HTTP API.
 
 **Backend:** Go 1.26, Cobra CLI, gorilla/websocket, pgx/v5 (database/sql, no ORM), golang-migrate, go-rod/rod, telego (Telegram)
 **Web UI:** React 19, Vite 6, TypeScript, Tailwind CSS 4, Radix UI, Zustand, React Router 7. Located in `ui/web/`. **Use `pnpm` (not npm).**
-**Database:** PostgreSQL 18 with pgvector. Raw SQL with `$1, $2` positional params. Nullable columns: `*string`, `*time.Time`, etc.
+**Desktop UI:** React 19, Vite 6, TypeScript, Tailwind CSS 4, Zustand, Framer Motion. Located in `ui/desktop/frontend/`. **Use `pnpm`.**
+**Desktop App:** Wails v2 (`//go:build sqliteonly`). Located in `ui/desktop/`. Embeds gateway + React frontend in single binary.
+**Database:** PostgreSQL 18 with pgvector (standard). SQLite via `modernc.org/sqlite` (desktop/lite). Raw SQL with `$1, $2` (PG) or `?` (SQLite) positional params. Nullable columns: `*string`, `*time.Time`, etc.
 
 ## Project Structure
 
@@ -71,15 +73,39 @@ go build -o goclaw . && ./goclaw onboard && source .env.local && ./goclaw
 go test -v ./tests/integration/     # Integration tests
 
 cd ui/web && pnpm install && pnpm dev   # Web dashboard (dev)
+
+# Desktop (Wails + SQLite)
+make desktop-dev                        # Dev mode with hot reload
+make desktop-build VERSION=0.1.0        # Build .app (macOS) or .exe (Windows)
+make desktop-dmg VERSION=0.1.0          # Create .dmg installer (macOS only)
 ```
 
+## Desktop Edition (Lite)
+
+- **Build tag:** `//go:build sqliteonly` — desktop binary includes only SQLite, no PostgreSQL
+- **Edition system:** `internal/edition/edition.go` — `Lite` preset auto-selected for SQLite backend. Check `edition.Current()` for feature limits
+- **Entry point:** `ui/desktop/main.go` + `ui/desktop/app.go` — Wails bindings, embedded gateway
+- **Secrets:** OS keyring (`go-keyring`) with file fallback at `~/.goclaw/secrets/`
+- **Data dir:** `~/.goclaw/data/` (SQLite DB, configs)
+- **Workspace:** `~/.goclaw/workspace/` (agent files, team workspace)
+- **Port:** 18790 (localhost only), configurable via `GOCLAW_PORT`
+- **WS params:** All WS method params use **camelCase** (`teamId`, `taskId`, `sessionKey`) — match Go struct `json:"..."` tags
+- **Version:** `cmd.Version` set via `-ldflags` at build time. Frontend calls `wails.getVersion()`
+- **Auto-update:** `internal/updater/updater.go` checks GitHub Releases for `lite-v*` tags. Frontend `UpdateBanner` shows notification
+- **Releases:** Tag `lite-v*` triggers `.github/workflows/release-desktop.yaml` → builds macOS (arm64+amd64) + Windows → GitHub Release
+- **Install scripts:** `scripts/install-lite.sh` (macOS), `scripts/install-lite.ps1` (Windows PowerShell)
+- **Lite limits:** 5 agents, 1 team, 5 members, 50 sessions. No channels, heartbeat, file storage UI, skill self-manage, KG, RBAC, multi-tenant
+- **Tool gating:** `TeamActionPolicy` in `internal/tools/team_action_policy.go` — lite blocks comment/review/approve/reject/attach/ask_user. `skill_manage`/`publish_skill` not registered in lite
+- **File serving:** 2-layer path isolation in `internal/http/files.go` — workspace boundary (all editions) + tenant scope (standard only with RBAC)
+
 ## Post-Implementation Checklist
 
 After implementing or modifying Go code, run these checks:
 
 ```bash
 go fix ./...                        # Apply Go version upgrades (run before commit)
-go build ./...                      # Compile check
+go build ./...                      # Compile check (PG build)
+go build -tags sqliteonly ./...     # Compile check (Desktop/SQLite build)
 go vet ./...                        # Static analysis
 go test -race ./tests/integration/  # Integration tests with race detector
 ```