docs: update CONTRIBUTING, remove wails3 CLI dependency

- Makefile desktop target uses go build directly (no wails3 required)
- CI workflow simplified: go build instead of wails3 build
- CONTRIBUTING: add make install, desktop auth docs, auto-update docs
- CONTRIBUTING: add file listing for icon.png, icon.icns, Taskfile, plist

.gitea/workflows/desktop.yml

@@ -37,12 +37,8 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev
 
-      - run: go install github.com/wailsapp/wails/v3/cmd/wails3@latest
+      - run: CGO_ENABLED=1 go build -o build/bin/oikos-desktop .
-
-      - run: wails3 build
         working-directory: cmd/desktop
-        env:
-          CGO_ENABLED: 1
 
       - run: |
           cd cmd/desktop/build/bin

CONTRIBUTING.md

@@ -28,8 +28,31 @@ make build
 
 # SPA dev server (proxies to api/nomos, injecting the same token)
 cd web && OIKOS_API_TOKEN=dev-token npm run dev
+
+# Desktop app (macOS)
+make desktop                  # build .app bundle
+make install                  # build + install to /Applications
+./cmd/desktop/build/bin/oikos-desktop.app/Contents/MacOS/oikos-desktop  # run from terminal to see logs
 ```
 
+### Desktop app auth
+
+The desktop app uses the same API as the browser SPA. First launch:
+
+1. Enter `https://oikos.hubris.network` as Server URL
+2. **Login with Authentik** tab → opens system browser → authenticate
+3. Callback page shows token → copy → paste into Token tab → Connect
+4. Token is persisted to the macOS keychain — subsequent launches skip setup
+
+The app stores credentials via `github.com/zalando/go-keyring` (service: `com.hubris.oikos-desktop`).
+
+### Desktop app auto-update
+
+- Checks Gitea releases every 6 hours
+- System tray → **Check for Updates** triggers an immediate check
+- Download, extract, replace the app in `/Applications`, and relaunch
+- Versions are compared against the `version` const in `main.go`
+
 ## Project structure
 
 ```
@@ -37,6 +60,10 @@ cmd/desktop/        Wails v3 desktop app (macOS + Linux)
   main.go            Thin shell: webview, system tray, notifications, auto-update
   wails.json         Wails project config
   entitlements.plist macOS code-signing entitlements
+  icon.png           System tray icon (embedded)
+  icon.icns          App bundle icon (white logo on black rounded rect)
+  Taskfile.yml       Wails v3 build tasks
+  Info.plist.template macOS bundle metadata
 cmd/oikos/          Single-binary entry point
 cmd/nomos/          Nomos MCP client gateway
 cmd/webhook/        Gitea deploy-webhook receiver (push-to-deploy on mac-mini)
@@ -88,6 +115,7 @@ docs/operations/    Runbooks (rollback, etc.)
 | `make deploy-ui` | Build + deploy the SPA to the Caddy host |
 | `make desktop` | Build the Wails desktop app for the current platform |
 | `make desktop-package` | Build + package (zip on macOS, tar.gz on Linux) |
+| `make install` | Build + install to `/Applications` (macOS) |
 | `make webhook` | Build `cmd/webhook` (deploy-webhook receiver) |
 | `make tidy` | `go mod tidy` |
 

Makefile

@@ -56,7 +56,7 @@ desktop: ui   ## Build the Wails desktop app for the current platform
 	rm -rf cmd/desktop/frontend/dist
 	mkdir -p cmd/desktop/frontend/dist
 	cp -r web/dist/* cmd/desktop/frontend/dist/
-	cd cmd/desktop && wails3 build
+	cd cmd/desktop && CGO_ENABLED=1 go build -o build/bin/oikos-desktop .
 
 desktop-package: desktop   ## Build + package the desktop app (zip on macOS, tar.gz on Linux)
 	@case $$(uname -s) in \