ClaudeVille: Enhanced, Improved, Refined

.claude/skills/troubleshooting/references/integration.md

@@ -1,42 +1,42 @@
 # Integration Troubleshooting
 
-### macOS 메뉴바 위젯 WKWebView WebSocket 연결 불가 [#1]
+### macOS Menu Bar Widget WKWebView WebSocket Connection Failure [#1]
 
-- **Symptom**: NSPopover 안의 WKWebView에서 widget.html 로드 후 `ws://localhost:4000` WebSocket 연결 시도하면 연결 안 됨. 같은 앱의 NSWindow WKWebView에서 `http://localhost:4000` 로드는 정상 동작. 메뉴바 뱃지가 `● 3` → `● 0`으로 깜빡임.
+- **Symptom**: Loading `widget.html` in the NSPopover `WKWebView` and then connecting to `ws://localhost:4000` fails. Loading `http://localhost:4000` in the same app's NSWindow `WKWebView` works. The menu bar badge flickers from `* 3` to `* 0`.
 - **Cause**:
-  1. WKWebView는 out-of-process 렌더링이라 `com.apple.security.network.client` entitlement 필요
-  2. `swiftc` 단일 파일 빌드는 Xcode entitlement 시스템 사용 불가
-  3. `loadFileURL` → `file://`에서 `ws://` 보안 차단, `loadHTMLString(baseURL: localhost)` → 여전히 차단
-  4. Info.plist `NSAllowsLocalNetworking` / `NSAllowsArbitraryLoadsInWebContent` 추가해도 효과 없음
-  5. JS→Swift bridge(`webkit.messageHandlers.badge`)가 WebSocket 실패 시 badge를 0으로 덮어써서 Swift 폴링 결과와 충돌
-- **Fix**: WKWebView를 순수 렌더링용으로만 사용, WebSocket 완전 제거:
-  1. Swift `Timer`로 3초마다 `/api/sessions` REST API 직접 호출 (`URLSession`)
-  2. 응답 JSON으로 Swift에서 HTML 문자열 동적 생성 (`buildHTML()`)
-  3. `webView.loadHTMLString(html, baseURL: nil)` → 네트워크 연결 불필요
-  4. 뱃지 업데이트는 Swift에서만 처리 (JS→Swift badge 통신 완전 제거)
-  5. `Open Dashboard` 버튼만 `webkit.messageHandlers.openDashboard`로 처리
+  1. Out-of-process `WKWebView` rendering requires a `com.apple.security.network.client` entitlement.
+  2. The single-file `swiftc` build does not use Xcode's entitlement system.
+  3. `loadFileURL` from `file://` blocks `ws://`; `loadHTMLString(baseURL: localhost)` still blocks it.
+  4. Adding `NSAllowsLocalNetworking` / `NSAllowsArbitraryLoadsInWebContent` to `Info.plist` did not fix the popover case.
+  5. The JS-to-Swift badge bridge (`webkit.messageHandlers.badge`) overwrote Swift polling results with `0` after WebSocket failure.
+- **Fix**: Use `WKWebView` as a render surface only and remove WebSocket use from the native popover:
+  1. Call `/api/sessions` and `/api/usage` directly from Swift with `URLSession` on a timer.
+  2. Build the HTML string in Swift from the response JSON (`buildHTML()`).
+  3. Use `webView.loadHTMLString(html, baseURL: nil)`, with no network from the popover web content.
+  4. Update the badge only from Swift.
+  5. Keep `webkit.messageHandlers.openDashboard` only for the Open Dashboard button.
 - **Files**: `widget/Sources/main.swift`, `widget/Info.plist`
 - **Date**: 2026-02-23
-- **Tags**: macOS, WKWebView, NSPopover, NSStatusItem, WebSocket, swiftc, entitlement, menubar, widget
+- **Tags**: macOS, WKWebView, NSPopover, NSStatusItem, WebSocket, swiftc, entitlement, menu bar, widget
 
 ---
 
-### fnm 임시 경로로 인한 서버 자동 시작 실패 [#2]
+### Server Autostart Failure From Temporary fnm Node Path [#2]
 
-- **Symptom**: 메뉴바 위젯에서 서버 자동 시작 기능이 동작 안 함. 빌드 시점에 기록된 node 경로가 앱 재실행 시 존재하지 않음.
-- **Cause**: `which node`가 fnm 임시 multishell 경로 반환 (`~/.local/state/fnm_multishells/{PID}_{TIMESTAMP}/bin/node`). 이 경로는 쉘 세션마다 바뀌므로 앱 번들에 기록해도 다음 실행 시 파일이 없음.
-- **Fix**: `build.sh`에서 `readlink -f "$(which node)"`로 심볼릭 링크를 해제한 실제 영구 경로를 기록. 영구 경로 예시: `~/.local/share/fnm/node-versions/v20.20.0/installation/bin/node`. Swift 코드에서도 fallback으로 fnm 영구 경로 직접 탐색: `~/.local/share/fnm/node-versions/*/installation/bin/node`.
+- **Symptom**: The menu bar widget cannot autostart the server. The Node path recorded at build time no longer exists when the app is relaunched.
+- **Cause**: `which node` returned an fnm temporary multishell path (`~/.local/state/fnm_multishells/{PID}_{TIMESTAMP}/bin/node`). That path changes per shell session, so recording it in the app bundle makes the next launch stale.
+- **Fix**: `build.sh` records the resolved stable path with `readlink -f "$(which node)"`. Example stable path: `~/.local/share/fnm/node-versions/v20.20.0/installation/bin/node`. Swift also falls back to scanning `~/.local/share/fnm/node-versions/*/installation/bin/node`.
 - **Files**: `widget/build.sh`, `widget/Sources/main.swift`
 - **Date**: 2026-02-23
-- **Tags**: fnm, node, readlink, symlink, macOS, 자동시작, build.sh
+- **Tags**: fnm, node, readlink, symlink, macOS, autostart, build.sh
 
 ---
 
-### macOS 앱 내 Process()로 lsof 실행 시 무한 대기 [#3]
+### `Process()` Running `lsof` Hangs Inside macOS App [#3]
 
-- **Symptom**: 위젯 앱 `applicationDidFinishLaunching`에서 `Process()`로 `/usr/bin/lsof -ti :4000` 실행 후 `waitUntilExit()` 호출하면 영원히 반환 안 됨. 로그에 "서버 시작 체크..." 한 줄만 찍히고 이후 진행 없음.
-- **Cause**: LSUIElement 메뉴바 앱 환경에서 `lsof` 프로세스가 행(hang). Finder/Spotlight에서 실행된 앱은 터미널과 다른 보안 컨텍스트에서 동작하며, `lsof`가 네트워크 소켓 정보 접근 시 권한 문제로 무한 대기할 수 있음.
-- **Fix**: 포트 체크 로직 자체를 제거. 서버 중복 실행 시 `server.js`가 `EADDRINUSE` 에러를 내므로, 그냥 항상 서버 시작을 시도하고 실패하면 무시. `try? proc.run()` 패턴 사용.
+- **Symptom**: In `applicationDidFinishLaunching`, running `/usr/bin/lsof -ti :4000` through `Process()` and then calling `waitUntilExit()` never returns.
+- **Cause**: `lsof` can hang in the security context of an LSUIElement menu bar app launched from Finder or Spotlight.
+- **Fix**: Remove the `lsof` port-check path. Let `server.js` report `EADDRINUSE` when a duplicate server start is attempted, and ignore the failed start attempt with the existing `try? proc.run()` pattern.
 - **Files**: `widget/Sources/main.swift`
 - **Date**: 2026-02-23
-- **Tags**: macOS, Process, lsof, waitUntilExit, hang, LSUIElement, 메뉴바앱
+- **Tags**: macOS, Process, lsof, waitUntilExit, hang, LSUIElement

.claude/skills/verify-architecture/SKILL.md

@@ -31,14 +31,15 @@ src/
 
 ### 2. No Framework Dependencies
 
-Verify the project uses pure HTML/CSS/JS with no npm dependencies:
+Verify the project uses pure HTML/CSS/JS at runtime with no runtime npm dependencies:
 
-- `package.json` should only have `scripts`, no `dependencies` or `devDependencies`
-- No `node_modules/` directory
+- `package.json` should not have runtime `dependencies`
+- `devDependencies` are allowed for sprite validation, visual diffs, and Playwright capture scripts
 - All imports use relative paths or ES modules
 
-- **PASS**: No external dependencies
-- **FAIL**: npm dependencies found
+- **PASS**: No runtime dependencies
+- **WARN**: Dev dependencies changed; confirm they are still development-only
+- **FAIL**: Runtime dependencies added without updating README and design decisions
 
 ### 3. Adapter Pattern Compliance
 

.claude/skills/verify-server/SKILL.md

@@ -9,31 +9,31 @@ Verify the ClaudeVille Node.js server operates correctly with all endpoints and
 
 ## Prerequisites
 
-- Server must NOT be running before test (port 4000 free)
+- Server may already be running on port 4000 in the operator's environment. Do not stop or replace an existing listener unless ownership is clear and the operator approves process cleanup.
 - Node.js available
 
 ## Check Items
 
 ### 1. Server Startup
 
-Start the server and verify it binds to port 4000:
+Start the server only when port 4000 is free, then verify it binds to port 4000:
 
 ```bash
-node claudeville/server.js &
+npm run dev
 sleep 2
 lsof -ti :4000
 ```
 
-- **PASS**: Server starts, port 4000 in use, ASCII logo printed
+- **PASS**: Server starts, port 4000 in use, startup summary printed
 - **FAIL**: Server crashes, port conflict, or startup error
 
 ### 2. Provider Detection
 
 Check server log output for active providers:
 
-- **PASS**: At least Claude Code provider detected (`~/.claude/` exists)
+- **PASS**: At least one provider detected (`~/.claude/`, `~/.codex/`, or `~/.gemini/` exists)
 - **WARN**: Only 1 provider detected
-- **FAIL**: No providers detected
+- **WARN**: No providers detected on a machine with no supported CLI session data
 
 ### 3. REST API - Sessions Endpoint
 
@@ -59,8 +59,8 @@ curl -s http://localhost:4000/api/teams
 curl -s http://localhost:4000/api/providers
 ```
 
-- **PASS**: Returns JSON with `{ providers: [...], count: N }`, count >= 1
-- **FAIL**: Non-200 status or empty providers
+- **PASS**: Returns JSON with `{ providers: [...], count: N }`
+- **FAIL**: Non-200 status or invalid JSON
 
 ### 6. Static File Serving
 
@@ -84,8 +84,4 @@ curl -s -I http://localhost:4000/api/sessions
 
 ## Cleanup
 
-After all checks, kill the server process:
-
-```bash
-kill $(lsof -ti :4000) 2>/dev/null
-```
+If you started the server in a dedicated terminal, stop only that process with Ctrl-C in that terminal. Do not kill arbitrary port-4000 listeners in a shared checkout.

.claude/skills/verify-widget-build/SKILL.md

@@ -22,7 +22,7 @@ Run the widget build script and verify it compiles without errors:
 cd widget && bash build.sh
 ```
 
-- **PASS**: Exit code 0, "빌드 완료" message printed
+- **PASS**: Exit code 0, "Build complete: ClaudeVilleWidget.app" message printed
 - **FAIL**: Compilation errors or non-zero exit code
 
 ### 2. App Bundle Structure

.gitignore

@@ -2,3 +2,20 @@ node_modules/
 .DS_Store
 *.log
 docs/plans/
+docs/superpowers/
+output/
+smoke-*.png
+/*.png
+widget/ClaudeVilleWidget
+widget/ClaudeVilleWidget.app/
+scripts/sprites/baselines/*-diff.png
+scripts/sprites/baselines/*-fresh.png
+!scripts/sprites/baselines/.gitkeep
+.playwright-cli/
+.playwright-mcp/
+.worktrees/
+.superpowers/
+.env
+.env.*
+.dev.var
+.dev.vars

AGENTS.md

@@ -0,0 +1,85 @@
+## Scope
+
+- Work from `/home/ahirice/Documents/git/claude-ville`.
+- ClaudeVille is a local, zero-build dashboard for watching AI coding CLI sessions as a browser "village" plus optional macOS and KDE widgets.
+- Desktop-only target: assume browser viewports ≥1280px wide. Do not add `@media` queries, mobile/narrow-viewport testing, or responsive shrinking.
+- Touch only files needed for the task. Shared checkout: start with `git status --short`, preserve unrelated edits, prefer `rg`/`rg --files` for discovery.
+- No install step, bundler, transpiler, lint, formatter, app test runner, or CI.
+
+Local dev-server (maintained): http://localhost:4000
+
+## Commands
+
+- Start: `npm run dev` → `http://localhost:4000`
+- Widget: `npm run widget:build`, then `npm run widget` (macOS only); KDE checks use `npm run widget:kde:check`
+- Run `npm install` only for dev scripts (sprite validation, visual diffs, Playwright capture).
+
+## Project Map
+
+| Area | Path | Onboarding doc |
+| --- | --- | --- |
+| Server / APIs / WebSocket | `claudeville/server.js` | [`claudeville/CLAUDE.md`](claudeville/CLAUDE.md) |
+| Provider adapters | `claudeville/adapters/` | [`adapters/README.md`](claudeville/adapters/README.md) |
+| Usage, quota, account | `claudeville/services/` | [`docs/design-decisions.md`](docs/design-decisions.md), [`docs/troubleshooting.md`](docs/troubleshooting.md) |
+| Frontend boot | `claudeville/src/presentation/App.js` | [`claudeville/CLAUDE.md`](claudeville/CLAUDE.md) |
+| World mode (canvas) | `claudeville/src/presentation/character-mode/` | [`character-mode/README.md`](claudeville/src/presentation/character-mode/README.md) |
+| Dashboard mode (DOM) | `claudeville/src/presentation/dashboard-mode/` | [`dashboard-mode/README.md`](claudeville/src/presentation/dashboard-mode/README.md) |
+| Shared UI | `claudeville/src/presentation/shared/` | [`shared/README.md`](claudeville/src/presentation/shared/README.md) |
+| Domain / application / config / infra | `claudeville/src/{domain,application,config,infrastructure}/` | [`claudeville/CLAUDE.md`](claudeville/CLAUDE.md) |
+| Sprite assets | `claudeville/assets/sprites/` | [`scripts/sprites/generate.md`](scripts/sprites/generate.md), [`docs/pixellab-reference.md`](docs/pixellab-reference.md) |
+| macOS widget | `widget/` | `README.md` § macOS Menu Bar Widget |
+| KDE Plasma widget | `widget/kde/` | [`widget/kde/README.md`](widget/kde/README.md), `README.md` § KDE Plasma Widget |
+
+## Agent Artifacts
+
+Committed agent outputs go under `/agents/`:
+
+- `/agents/plans/<slug>.md` — implementation plans
+- `/agents/research/<slug>/` — research notes, proofs, image dumps
+- `/agents/handover/<slug>.md` — handover memos
+
+Before using an old artifact as implementation input, check [`agents/README.md`](agents/README.md) for status, supersession notes, and reusable templates.
+
+## Workflow
+
+- Multi-part work or explicit swarm requests → follow [`docs/swarm-orchestration-procedure.md`](docs/swarm-orchestration-procedure.md) (quick modes, ownership, baselines, destructive-command and commit/push gates).
+- Single-file / single-owner tasks → direct execution unless swarm is requested.
+
+## Browser Verification
+
+The operator runs a server on http://localhost:4000/ that can be used to verify output.
+
+## Copy And Locale Policy
+
+Use English for all new/edited UI copy, docs, comments, and agent-facing text. Do not add non-English strings unless the task explicitly requests localization.
+
+## Validation
+
+Match validation to what you changed:
+
+| Change | Smoke check |
+| --- | --- |
+| `server.js`, `adapters/*.js`, `services/*.js` | `node --check <file>`; multiple: `find claudeville/adapters claudeville/services -name '*.js' -print0 \| xargs -0 -n1 node --check` |
+| Broad non-runtime regression pass | `npm run validate:quick` |
+| Adapter discovery or relationship state | `node scripts/smoke/adapters.mjs`; `NODE_NO_WARNINGS=1 node scripts/smoke/relationship.mjs` |
+| Runtime / API behavior | `npm run dev`; then `curl http://localhost:4000/api/{providers,sessions}` and confirm browser console |
+| Anything under `src/` | Open `http://localhost:4000`, test World + Dashboard, resize, agent select/deselect |
+| Sprite assets or `manifest.yaml` | `npm run sprites:audit-refresh`; for visuals, `sprites:capture-fresh` then `sprites:visual-diff` |
+| World building or terrain config | `npm run world:validate-buildings`; `npm run world:validate-terrain` |
+| `widget/` | macOS: `npm run widget:build`, then `npm run widget:check` or `npm run widget:verify-bundle`, then `npm run widget`; KDE: `npm run widget:kde:check`, then `npm run widget:kde:install` when KDE is available |
+| Root agent docs | parity must hold: `diff <(tail -n +3 CLAUDE.md) <(tail -n +3 AGENTS.md)` empty |
+| Docs-only | diff review + `git status --short` |
+
+First-hour failure modes: [`docs/troubleshooting.md`](docs/troubleshooting.md). Load-bearing constraints (port 4000, hand-written WebSocket, static pricing, polling cadence): [`docs/design-decisions.md`](docs/design-decisions.md).
+
+## GitHub And Remotes
+
+- `origin` → `https://github.com/TokenBrice/claude-ville.git` (fetch + push, working fork).
+- `upstream` → `https://github.com/honorstudio/claude-ville.git` (fetch only).
+- Do not change remotes, branches, or fork workflow unless explicitly asked.
+
+## Git Hygiene
+
+- Re-run `git status --short` before editing, before committing, and before final response.
+- Preserve unrelated local modifications and untracked files. Do not revert, stage, commit, delete, or format files outside the task scope.
+- Do not run destructive commands (`git reset --hard`, `git checkout --`, `git restore`, `git clean`, `rm -rf`, `git stash drop/clear`, bulk formatters, `kill`/`pkill`/`killall`, port-killing pipelines) without explicit approval.