From dccf83c8faabaeeb91110defda2eb5cd11eb4a61 Mon Sep 17 00:00:00 2001
From: Samuel Onoja <samiodev@icloud.com>
Date: Thu, 24 Sep 2026 16:45:57 +0100
Subject: [PATCH] docs: add direct session validation runbook

---
 README.md              | 23 +++++++++++++++++++++++
 compositor/src/main.rs |  4 ++--
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1455a59..bb04b43 100644
--- a/README.md
+++ b/README.md
@@ -22,3 +22,26 @@ cargo run -p ferese -- foot
 ```
 
 Set `RUST_LOG=ferese=debug` for detailed compositor logging.
+
+### Direct DRM session
+
+Run the hardware backend from a spare TTY, outside another graphical session:
+
+```bash
+RUST_LOG=ferese=debug cargo run -p ferese -- --backend=drm -- foot
+```
+
+Do not run that command from a terminal inside the active desktop: the direct
+backend requests control of the seat and primary DRM device. Use
+Ctrl+Alt+F1–F12 to switch virtual terminals.
+
+M4 validation requires the direct session to:
+
+- start `foot` and render the same animated tiling workload as the nested path;
+- retain keyboard and pointer input;
+- pause when switching away and redraw after switching back; and
+- log page-flip timing and any missed presentation deadlines on the reference
+  integrated GPU.
+
+The direct path currently targets one connected output. Multi-output hotplug is
+part of M5.
diff --git a/compositor/src/main.rs b/compositor/src/main.rs
index 9ff456f..7bcd600 100644
--- a/compositor/src/main.rs
+++ b/compositor/src/main.rs
@@ -49,7 +49,7 @@ fn spawn_client(mut args: Vec<std::ffi::OsString>) {
     let program = args.remove(0);
 
     match Command::new(&program).args(args).spawn() {
-        Ok(child) => info!(program = ?program, pid = child.id(), "spawned nested client"),
-        Err(error) => warn!(program = ?program, %error, "failed to spawn nested client"),
+        Ok(child) => info!(program = ?program, pid = child.id(), "spawned Wayland client"),
+        Err(error) => warn!(program = ?program, %error, "failed to spawn Wayland client"),
     }
 }