From 26f6122ca2d513fd9eb89d5c60bd2c646e6afb08 Mon Sep 17 00:00:00 2001
From: root <root@dev-01.my.domain>
Date: Wed, 30 Sep 2026 15:21:01 +0000
Subject: [PATCH] docs: document controls, install and develop

Describe the filter focus rules, the column scrolling keys, and the
error and catalogue failure behaviour. Add the install, run and
develop sections pointing at the new Makefile targets.
---
 README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 47 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 9e70ce4..3d55bbc 100644
--- a/README.md
+++ b/README.md
@@ -15,19 +15,58 @@ This is a prototype to gather some feedback.
 ## Controls
 
 * `up/down`: scroll up / down (`jk` vim bindings also work)
-* `page up/down`: ;page up down (`ctrl+u/d` vim binding also work)
+* `page up/down`: page up / page down (`ctrl+u/d` vim bindings also work)
+* `home`/`g`: jump to the first row
+* `end`/`G`: jump to the last row
+* `shift+left`/`shift+right`: scroll between columns when they overflow
 * `/` or `f`: fuzzy filter against domain, server & recipe
-* `enter`: focus on table, select row, confirm
-* `esc`: reset filter
-* `q`: quit
+* `enter` or `esc`: confirm the filter and return focus to the table (`esc`
+  also clears it)
 * `s`: retrieve app deployment status (filter first to reduce scope)
+* `q` or `ctrl+c`: quit
 
-  Unreachable servers (e.g. SSH login issues) are skipped and reported in a
-  banner; statuses for the remaining servers are still shown. Press any key to
-  dismiss the banner and try again.
+Servers are queried at most five at a time, so a large fleet does not open one
+SSH connection per server all at once.
+
+### Errors
+
+Unreachable servers (e.g. SSH login issues) are skipped and reported in a
+banner; statuses for the remaining servers are still shown. The banner shows
+the first few problems and a count of the rest. Press any key to dismiss it
+and try again.
+
+If the recipe catalogue cannot be fetched, the deployment statuses are still
+rendered and only the `Updates` column is left unknown.
+
+## Install
+
+```
+make install
+```
+
+or, with Go installed:
+
+```
+go install coopcloud.tech/cctuip@latest
+```
 
 ## Run
 
 ```
-go run cctuip.go
+make run
+```
+
+or:
+
+```
+go run .
+```
+
+## Develop
+
+```
+make check   # gofmt and go vet
+make test    # unit tests
+make format  # apply gofmt
+make build   # build ./cctuip
 ```