From dbd357f0fd4046a8854fa2b1de5984c8649fcedc Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Fri, 13 Mar 2026 13:38:02 +0000
Subject: [PATCH] docs: add CLAUDE.md project instructions

Co-Authored-By: Virgil <virgil@lethean.io>
---
 CLAUDE.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..594d4c0
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is `forge.lthn.ai/core/gui` — a display/windowing module for the Core web3 desktop framework. It provides window management, dialogs, system tray, clipboard, notifications, theming, layouts, and real-time WebSocket events. Built on **Wails v3** (Go backend) with an **Angular 20** custom element frontend.
+
+## Build & Development Commands
+
+### Go backend
+```bash
+go build ./...              # Build all packages
+go test ./...               # Run all tests
+go test ./pkg/display/...   # Run display package tests
+go test -race ./...         # Run tests with race detection
+go test -cover ./...        # Run tests with coverage
+go test -run TestNew ./pkg/display/  # Run a single test
+```
+
+### Angular frontend (pkg/display/ui/)
+```bash
+cd pkg/display/ui
+npm install                 # Install dependencies
+npm run build               # Production build
+npm run watch               # Dev watch mode
+npm run start               # Dev server (localhost:4200)
+npm test                    # Unit tests (Karma/Jasmine)
+```
+
+## Architecture
+
+### Service-based design with Core DI
+
+The display `Service` registers with `forge.lthn.ai/core/go`'s service container via `Register(c *core.Core)`. It embeds `core.ServiceRuntime[Options]` for lifecycle management and access to sibling services.
+
+### Interface abstraction for testability
+
+All Wails application APIs are abstracted behind interfaces in `interfaces.go` (`App`, `WindowManager`, `MenuManager`, `DialogManager`, etc.). The `wailsApp` adapter wraps the real Wails app. Tests inject a `mockApp` instead — see `mocks_test.go` and the `newServiceWithMockApp(t)` helper.
+
+### Key files in pkg/display/
+
+| File | Responsibility |
+|------|---------------|
+| `display.go` | Service struct, lifecycle (`Startup`), window CRUD, screen queries, tiling/snapping/layout, workflow presets |
+| `window.go` | `WindowOption` functional options pattern, `Window` type alias for `application.WebviewWindowOptions` |
+| `window_state.go` | `WindowStateManager` — persists window position/size across restarts |
+| `layout.go` | `LayoutManager` — save/restore named window arrangements |
+| `events.go` | `WSEventManager` — WebSocket pub/sub for window/theme/screen events |
+| `interfaces.go` | Abstract interfaces + Wails adapter implementations |
+| `actions.go` | `ActionOpenWindow` IPC message type |
+| `menu.go` | Application menu construction |
+| `tray.go` | System tray setup |
+| `dialog.go` | File/directory dialogs |
+| `clipboard.go` | Clipboard read/write |
+| `notification.go` | System notifications |
+| `theme.go` | Dark/light mode detection |
+| `mocks_test.go` | Mock implementations of all interfaces for testing |
+
+### Patterns used throughout
+
+- **Functional options**: `WindowOption` functions (`WindowName()`, `WindowTitle()`, `WindowWidth()`, etc.) configure `application.WebviewWindowOptions`
+- **Type alias**: `Window = application.WebviewWindowOptions` — direct alias, not a wrapper
+- **Event broadcasting**: `WSEventManager` uses gorilla/websocket with a buffered channel (`eventBuffer`) and per-client subscription filtering (supports `"*"` wildcard)
+- **Window lookup by name**: Most Service methods iterate `s.app.Window().GetAll()` and type-assert to `*application.WebviewWindow`, then match by `Name()`
+
+## Testing
+
+- Framework: `testify` (assert + require)
+- Pattern: `newServiceWithMockApp(t)` creates a `Service` with mock Wails app — no real window system needed
+- `newTestCore(t)` creates a real `core.Core` instance for integration-style tests
+- Some tests use `defer func() { recover() }()` to handle nil panics from mock methods that return nil pointers (e.g., `Dialog().Info()`)
+
+## CI/CD
+
+Forgejo Actions (`.forgejo/workflows/`):
+- **test.yml**: Runs `go test` with race detection and coverage on push to main/dev and PRs to main
+- **security-scan.yml**: Security scanning on push to main/dev/feat/* and PRs to main
+
+Both use reusable workflows from `core/go-devops`.
+
+## Dependencies
+
+- `forge.lthn.ai/core/go` — Core framework with service container and DI
+- `github.com/wailsapp/wails/v3` — Desktop app framework (alpha.74)
+- `github.com/gorilla/websocket` — WebSocket for real-time events
+- `github.com/stretchr/testify` — Test assertions
+
+## Repository migration note
+
+Import paths were recently migrated from `github.com/Snider/Core` to `forge.lthn.ai/core/*`. The `cmd/` directories visible in git status are deleted artifacts from this migration and prior app scaffolds.