From 604cbda388c3a00e96d01c894fd88cce681fe04a Mon Sep 17 00:00:00 2001
From: Pit Friedrich <bp.webservice@gmail.com>
Date: Sun, 9 Aug 2026 20:07:33 +0200
Subject: [PATCH] created readme

---
 README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1b1856f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# dashboard
+
+A terminal dashboard (TUI) built with [go-tui](https://github.com/grindlemire/go-tui). Shows simulated CPU/memory/disk gauges, network sparklines, and a scrolling event feed. Single binary, no external services — everything is randomly generated for demo purposes.
+
+## Requirements
+
+- Go 1.24+ (module targets 1.26.5)
+
+## Getting started
+
+```sh
+# Regenerate dashboard_gsx.go from dashboard.gsx (required if the .go file is missing/stale)
+go run github.com/grindlemire/go-tui/cmd/tui generate ./...
+
+# Run the app
+go run .
+```
+
+## Commands
+
+```sh
+# Regenerate dashboard_gsx.go from dashboard.gsx
+go run github.com/grindlemire/go-tui/cmd/tui generate ./...
+
+# Build
+go build ./...
+
+# Vet
+go vet ./...
+
+# Run
+go run .
+```
+
+There are no test files in this repo yet.
+
+## Controls
+
+- `q` / `Esc` — quit
+- `j` / `k` or arrow keys — scroll the event feed
+- Mouse wheel — scroll the event feed
+
+## Architecture
+
+`dashboard.gsx` is the source of truth for the UI, written in `.gsx` — a JSX-like DSL (Tailwind-esque `class` strings, `{expr}` interpolation, `for`/`if` control flow) provided by go-tui. It also contains the non-templ Go code: the `dashboardApp` struct, helper funcs, and `produceEvents`.
+
+Running `tui generate` compiles `dashboard.gsx` into `dashboard_gsx.go`. That generated file is git-ignored and carries a `// Code generated by tui generate. DO NOT EDIT.` header — never hand-edit it. To change the UI, edit `dashboard.gsx` and regenerate.
+
+`main.go` wires up `tui.NewApp(tui.WithRootComponent(Dashboard(eventCh)), tui.WithMouse())` and runs it. A background goroutine (`produceEvents`) pushes random events onto `eventCh`.
+
+`dashboardApp` implements several optional go-tui interfaces (checked at compile time in the generated file):
+
+- `KeyMap()` — key bindings
+- `HandleMouse()` — mouse wheel scroll support
+- `Watchers()` — background subscriptions (a 500ms metrics-drift timer, an event-channel watch)
+- `Render()` — the generated view tree
+- `BindApp()` — generated; wires every `*tui.State[T]` field so state changes trigger re-renders
+
+All mutable UI state (`cpu`, `mem`, `sparkIn`, `events`, `scrollY`, ...) is `*tui.State[T]`, read via `.Get()` and mutated via `.Set()`.
+
+See [CLAUDE.md](CLAUDE.md) for more detail on the code-generation step and conventions.
+
+## CI
+
+`.gitea/workflows/build.yml` runs on push/PR to `main`: checkout → setup-go → `tui generate` → `go build` → `go vet`. The generated file is never committed — CI regenerates it from scratch every run.
-- 
2.52.0