From dc5088e03aef69edcd8616e0977595e05b5558bc Mon Sep 17 00:00:00 2001
From: TJ Kolleh <tinatuh@gmail.com>
Date: Sat, 4 Apr 2026 10:20:39 -0400
Subject: [PATCH] docs: update README and unify git hooks with lefthook

---
 .githooks/pre-commit | 12 ------------
 CONTRIBUTING.md      |  8 ++++++++
 README.md            | 46 ++++++++++++++++++++++++++++++++++----------
 lefthook.yml         |  3 ++-
 4 files changed, 46 insertions(+), 23 deletions(-)
 delete mode 100755 .githooks/pre-commit

diff --git a/.githooks/pre-commit b/.githooks/pre-commit
deleted file mode 100755
index 4161bc9..0000000
--- a/.githooks/pre-commit
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/bin/sh
-set -e
-
-echo "Running pre-commit checks..."
-
-# Run code quality checks via just
-if command -v just >/dev/null 2>&1; then
-    just check
-else
-    echo "Error: 'just' command not found. Please install just (https://github.com/casey/just)"
-    exit 1
-fi
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7c0f2a3..18ce6ad 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -50,6 +50,14 @@ luarocks install luasystem
 luarocks install busted --dev
 ```
 
+### Git Hooks
+
+We use [Lefthook](https://github.com/evilmartians/lefthook) to manage Git hooks (formatting, linting, tests). After installing lefthook (e.g., via `brew install lefthook` or `npm install -g @evilmartians/lefthook`), set up the hooks by running:
+
+```bash
+lefthook install
+```
+
 ### Project Structure
 
 ```
diff --git a/README.md b/README.md
index 484d613..7141f84 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,25 @@
 # Roda
 
-> Elegant terminal spinners for Lua
+> Elegant terminal spinners for bash scripts and Lua
 
 [![CI](https://github.com/tkolleh/roda.lua/actions/workflows/tests.yml/badge.svg)](https://github.com/tkolleh/roda.lua/actions/workflows/tests.yml)
 [![LuaRocks](https://img.shields.io/luarocks/v/tkolleh/roda)](https://luarocks.org/modules/tkolleh/roda)
 [![License: EUPL 1.2](https://img.shields.io/badge/License-EUPL--1.2-blue.svg)](https://opensource.org/licenses/EUPL-1.2)
 
-**Roda** (Portuguese for "wheel") is a pure Lua terminal spinner library.
+**Roda** (Portuguese for "wheel") is an elegant terminal spinner utility. It can be used as a standalone executable in bash scripts to show progress for long-running commands, or as a pure Lua library.
 
 ## Features
 
 ![Demo](./assets/demo.gif)
 
+- **Standalone Executable** - perfect for wrapping slow commands in bash scripts
 - **16 built-in spinner styles** - dots, line, arc, bounce, and more
 - **Colorized output**     - 9 terminal colors supported
 - **Terminal states**      - succeed, fail, warn, info with symbols
 - **Dynamic text updates** - change text while spinning
 - **Highly configurable**  - intervals, colors, prefixes, suffixes
 - **Minimal dependencies** - only requires `luasystem` and `luv`
-- **Lua 5.1+ compatible**  - works with Lua 5.1, 5.2, 5.3, 5.4, and LuaJIT
-- **Asynchronous**         - non-blocking execution using `luv`
+- **Asynchronous**         - non-blocking execution
 
 ## Installation
 
@@ -35,7 +35,33 @@ lx add roda
 luarocks install roda
 ```
 
-## Quick Start
+## Usage (CLI)
+
+Use Roda to add elegant loading indicators to your bash scripts. Simply wrap your long-running commands with `roda`:
+
+```bash
+# Basic usage
+roda --title "Installing dependencies..." -- npm install
+
+# Custom spinner style
+roda --title "Waiting for database..." --spinner "dots2" -- sleep 5
+
+# Show output of the command (by default output is hidden while spinning)
+roda --show-output --title "Building project..." -- make build
+```
+
+### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `--title TEXT` | Text to display next to the spinner |
+| `--spinner NAME` | Spinner style to use (e.g., `dots`, `line`, `arc`) |
+| `--show-output` | Display the command's stdout/stderr after it finishes |
+| `--` | Separates roda options from the command to execute |
+
+## Usage (Lua Library)
+
+Roda is compatible with Lua 5.1, 5.2, 5.3, 5.4, and LuaJIT.
 
 ```lua
 local roda = require("roda")
@@ -56,7 +82,7 @@ spinner:start()
 spinner:succeed()
 ```
 
-## Async Command Execution
+### Async Command Execution
 
 Roda supports running child processes asynchronously without blocking the Lua runtime.
 
@@ -76,9 +102,9 @@ end)
 roda.run()
 ```
 
-## API Reference
+### API Reference
 
-### `roda(opts)` / `roda.new(opts)`
+#### `roda(opts)` / `roda.new(opts)`
 
 Create a new spinner instance.
 
@@ -98,7 +124,7 @@ Create a new spinner instance.
 
 **Returns:** `Spinner` instance
 
-### Instance Methods
+#### Instance Methods
 
 - `:start(text?)` - Start the spinner. Optionally set new text.
 - `:stop()` - Stop and clear the spinner from the terminal.
@@ -113,7 +139,7 @@ Create a new spinner instance.
 - `:stopAndPersist(opts)` - Stop with custom symbol and text.
 - `:execute(command, args)` - Execute a child process asynchronously while spinning. Returns a Thunk that expects an `on_complete` callback.
 
-### Module Methods
+#### Module Methods
 
 - `roda.run()` - Run the libuv event loop. Blocks until all async tasks finish.
 
diff --git a/lefthook.yml b/lefthook.yml
index 446408c..9d5949e 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -1,4 +1,5 @@
 pre-commit:
+  parallel: true
   commands:
     format:
       glob: "*.lua"
@@ -11,4 +12,4 @@ pre-commit:
 pre-push:
   commands:
     test:
-      run: lx test
+      run: just validate