Merge pull request 'docs(readme): clarify WLTurbo scope and place in the stack' (#1) from docs/readme-scope into main

Reviewed-on: https://git.bnema.dev/bnema/wlturbo/pulls/1

commit: dfba464aefa1ccef3283fd8f1a9aee4c0d5e87b8
author: bnema · 20d ago · 2026-10-02 04:17 UTC
merge of: f02b08f + 8265b22 · diff against the first parent
signature: unsigned

2 files · +16 -4

M .gitignore +1 -1


@@ -45,4 +45,4 @@ NOTES.md
45	45
46	46		# Build artifacts
47	47		dist/
48		-	build/⏎̸
	48	+	build/.worktrees/


@@ -45,4 +45,4 @@ NOTES.md
45			45
46		# Build artifacts	46		# Build artifacts
47		dist/	47		dist/
48	-	build/⏎̸	48	+	build/.worktrees/

M README.md +15 -3

@@ -1,10 +1,20 @@
1		-	# WLTurbo - Wayland Client Library for Go
	1	+	# WLTurbo
2	2
3		-	A performance-focused Wayland client runtime for Go, the foundation for protocol bindings and Wayland applications.
	3	+	A performance-focused, low-level Wayland client runtime for Go.
4	4
5	5		## Overview
6	6
7		-	WLTurbo is a low-level Wayland client runtime: connection, wire framing, descriptor passing, object lifecycle and the bootstrap registry. Protocol bindings are provided separately (see [Protocol bindings](#protocol-bindings)).
	7	+	WLTurbo is the transport layer: connection, wire framing, descriptor passing, object lifecycle and the bootstrap registry. It is not a complete Wayland client. It has no windows, surfaces, seats, input handling or rendering, and it knows no protocol beyond the bootstrap objects. Protocol bindings are provided separately (see [Protocol bindings](#protocol-bindings)).
	8	+
	9	+	## Where it fits
	10	+
	11	+	```
	12	+	Application or toolkit windows, input, rendering, policy
	13	+	└─ Protocol bindings generated code, one package per protocol
	14	+	└─ WLTurbo transport and objects (this module)
	15	+	```
	16	+
	17	+	Use WLTurbo directly to speak raw Wayland or to write your own bindings or toolkit. Ready-made bindings are available in [go-wayland-bindings](https://github.com/bnema/go-wayland-bindings).
8	18
9	19		## Architecture
10	20

@@ -39,6 +49,8 @@ After `display.Roundtrip()` discovers globals, call `display.Registry().BindNego
39	49
40	50		## Quick Start
41	51
	52	+	This opens a connection and dispatches events. Binding globals needs the protocol packages from `go-wayland-bindings`.
	53	+
42	54		```go
43	55		package main
44	56

-# WLTurbo - Wayland Client Library for Go
+# WLTurbo
-A performance-focused Wayland client runtime for Go, the foundation for protocol bindings and Wayland applications.
+A performance-focused, low-level Wayland client runtime for Go.
 ## Overview
-WLTurbo is a low-level Wayland client runtime: connection, wire framing, descriptor passing, object lifecycle and the bootstrap registry. Protocol bindings are provided separately (see [Protocol bindings](#protocol-bindings)).
+WLTurbo is the transport layer: connection, wire framing, descriptor passing, object lifecycle and the bootstrap registry. It is not a complete Wayland client. It has no windows, surfaces, seats, input handling or rendering, and it knows no protocol beyond the bootstrap objects. Protocol bindings are provided separately (see [Protocol bindings](#protocol-bindings)).
+## Where it fits
+```
+Application or toolkit    windows, input, rendering, policy
+└─ Protocol bindings      generated code, one package per protocol
+   └─ WLTurbo             transport and objects  (this module)
+```
+Use WLTurbo directly to speak raw Wayland or to write your own bindings or toolkit. Ready-made bindings are available in [go-wayland-bindings](https://github.com/bnema/go-wayland-bindings).
 ## Architecture
 ## Quick Start
+This opens a connection and dispatches events. Binding globals needs the protocol packages from `go-wayland-bindings`.
 ```go
 package main