From 98673b57ff5914f7b950ce682d260df044fa4c41 Mon Sep 17 00:00:00 2001
From: portersky <24420859+portersky@users.noreply.github.com>
Date: Wed, 6 May 2026 00:15:43 +0200
Subject: [PATCH] docs: update README and AGENTS.md to match current project

Updated project description from 'cube timer' to 'OpenGL 3D
renderer with multiple scenes'. Added usage section with CLI
flags and key bindings. Listed both available scenes.

Updated AGENTS.md to include the sphere scene in static
libraries and source layout. Normalized run command to
./build/cuber for cross-platform consistency.
---
 AGENTS.md |  9 ++++---
 README.md | 79 ++++++++++++++++++++++++++++++++++---------------------
 2 files changed, 55 insertions(+), 33 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 4d3f471..34872ed 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-`cuber` is a simple cube timer application.
+`cuber` is an OpenGL 3D renderer with multiple scenes.
 
 ## Build System
 
@@ -15,7 +15,7 @@
   ```sh
   cmake -S . -B build -GNinja
   ninja -C build
-  .\build\cuber.exe
+  ./build/cuber
   ```
 
 ### Dependencies
@@ -36,7 +36,8 @@ The project is split into static libraries:
 
 - **`cbt_opengl`** — OpenGL abstraction and window management (window, context, buffer, texture, vao, shader, descriptor)
 - **`cbt_scene`** — Base scene class
-- **`scenes_cube`** — Cube scene implementation
+- **`scenes_cube`** — Spinning cube scene implementation
+- **`scenes_sphere`** — Cube-to-sphere mapped mesh with diffuse lighting
 
 ### CMake Module Path
 
@@ -120,6 +121,8 @@ cuber/
   scenes/             # Application scenes
     cube.hpp          # Spinning cube scene
     cube.cpp          # Cube scene implementation
+    sphere.hpp        # Cube-to-sphere mapped mesh
+    sphere.cpp        # Sphere scene implementation
   deps/               # Custom Find*.cmake scripts
     Findfmt.cmake     # fmt library
 ```
diff --git a/README.md b/README.md
index d98e5f7..0a70b12 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,49 @@
-# cuber
-
-`cuber` is a simple cube timer.
-
-## Requirements
-
-- CMake 3.21+
-- Ninja
-- C++23 compiler
-
-## Development
-
-**Configure**:
-
-```sh
-cmake -S . -B build -GNinja
-```
-
-**Build**:
-
-```sh
-ninja -C build
-```
-
-**Run**:
-
-```bash
-./build/cuber.exe
-```
-
+# cuber
+
+`cuber` is an OpenGL 3D renderer with multiple scenes.
+
+## Requirements
+
+- CMake 3.21+
+- Ninja
+- C++23 compiler
+
+All dependencies (fmt, GLFW, GLAD, asio, GLM, stb) are fetched
+automatically via CMake FetchContent.
+
+## Development
+
+**Configure**:
+
+```sh
+cmake -S . -B build -GNinja
+```
+
+**Build**:
+
+```sh
+ninja -C build
+```
+
+**Run**:
+
+```sh
+./build/cuber
+```
+
+## Usage
+
+```
+--duration <seconds>  Auto-terminate after N seconds (for testing/CI)
+--scene <cube|sphere> Select initial scene (default: cube)
+--screenshot          Render one frame, save screenshot, and exit
+S key                 Take screenshot (saved as screenshot.png)
+1/2 key               Switch between cube/sphere scene
+Q key                 Quit
+```
+
+## Scenes
+
+- **cube** — spinning colored cube with per-face colors
+- **sphere** — cube-to-sphere mapped mesh with per-face colors and
+  diffuse lighting