docs: add comprehensive README.md

Covers essentials modeled after gostations:
- Project description and galculator GTK inspiration
- MVP features (decimal math, BASE cycling via Tab, CERR policy, MOD, display layout, tactile keypad)
- Requirements
- Install via one-liner release scripts (Linux/macOS + PowerShell)
- Usage: display row, key bindings (Tab:BASE, m:MOD, Backspace:C, Del:AC, etc.)
- Building from source (make build/install/test)
- Development notes (links to spec.md, docs/ARCHITECTURE.md, docs/UI_DESIGN.md, workflows, engine/UI separation)
- Ties to personal apps/ ecosystem and REXX launcher

All naming is now consistently 'gralculator' (folder, binary, repo).

README.md

@@ -0,0 +1,106 @@
+# Gralculator
+
+**Gralculator** — Greg's Calculator. A terminal UI calculator.
+
+Portmanteau of "Greg" + "calculator". A fast, keyboard-centric TUI inspired by the visual layout of galculator (the GTK programmer's calculator), with a wide integrated display row and tactile keypad.
+
+All calculations are performed in decimal. Display bases (DEC / HEX / BIN / OCT) are purely for formatting the current value. A single `Tab` (BASE) key cycles the display format. Non-integer values trigger a brief "CERR" (conversion error) flash instead of silently truncating.
+
+## Features (v0.1 MVP)
+
+- Wide display row: `[BASE]` indicator on the left + large, right-aligned number area (LCD-style with green-on-dark styling and subtle borders).
+- Base cycling via `Tab` (or the visual BASE key if present in your build).
+- Core operations: `+` `-` `*` `/` and `MOD` (modulo).
+- Clear controls: `Backspace` for Clear Entry (`C`), `Delete` for All Clear (`AC`).
+- Decimal point, sign change (`+/-`), and standard digit entry.
+- Tactile visual keypad: individually bordered buttons with color-coded groups (numbers, operators, clears, MOD, BASE), height for "key" feel, and press-flash feedback (bright 63 background).
+- Minimal non-wrapping hint row at the bottom.
+- Content-sized, centered card layout (no stretching) using lipgloss patterns refined in the gostations project.
+- Pure, testable calculation engine (internal/calc) separate from the Bubble Tea UI.
+- Cross-platform static binary.
+
+## Requirements
+
+- Linux or macOS (Windows via installers or WSL)
+- For running the binary: a modern terminal (kitty, WezTerm, Ghostty, etc. recommended for Unicode and color)
+- For building from source: Go 1.24.2+
+
+## Install (for normal users)
+
+The easiest way is the one-liner installer attached to each release:
+
+### Linux / macOS
+```bash
+curl -L https://repos.gmgauthier.com/gmgauthier/gralculator/releases/download/v0.1.0/gralculator-install.sh \
+  | VERSION=0.1.0 bash
+```
+
+### Windows (PowerShell) / macOS / Linux with PowerShell
+```powershell
+irm https://repos.gmgauthier.com/gmgauthier/gralculator/releases/download/v0.1.0/gralculator-install.ps1 | iex
+```
+
+The installer:
+- Detects your OS and architecture.
+- Downloads the matching `gralculator-OS-ARCH-vX.Y.Z.tar.gz` (verifies checksum when possible).
+- Installs the binary to `~/.local/bin/gralculator` (`.exe` on Windows).
+- Prints `PATH` advice if needed and runs `gralculator -v`.
+
+After installation, just run `gralculator`.
+
+## Usage
+
+Run with no arguments to launch the TUI.
+
+### Display
+A single wide row inside a bordered LCD-style panel:
+- Left: current base indicator (e.g. `[DEC]`, `[HEX]`, `[BIN]`, or `[OCT]`)
+- Right: the current value, right-aligned and filling the available width
+
+### Keypad
+Tactile visual buttons below the display (numbers, operators, MOD, C, AC, +/-, etc.). The BASE action is keyboard-driven via `Tab` (the visual button was removed in favor of a clean grid + hint).
+
+### Key Bindings
+- `Tab` — cycle display base (DEC → HEX → BIN → OCT → DEC). Flashes "CERR" on the number area if the current value is non-integer.
+- `m` / `M` — MOD (modulo)
+- `Backspace` — Clear Entry (C)
+- `Delete` — All Clear (AC)
+- `0`-`9` — digits
+- `.` — decimal point
+- `+` `-` `*` `/` — operators
+- `=` or `Enter` — equals / commit pending operation
+- `+/-` — change sign
+- `q`, `Ctrl+C`, `Esc` — quit
+
+The hint row at the bottom always shows the essentials.
+
+## Building from Source
+
+```bash
+git clone https://repos.gmgauthier.com/gmgauthier/gralculator.git
+cd gralculator
+make build          # produces build/gralculator
+make install        # installs to ~/.local/bin/gralculator
+make test           # or make test-short
+```
+
+The Makefile supports cross-compilation (`make cross`), ldflags for version injection, and matches the conventions used by gostations and grokkit.
+
+## Development
+
+- `spec.md` — living high-level specification and design decisions (MVP scope, CERR policy, single BASE cycle, etc.).
+- `docs/ARCHITECTURE.md` — package structure, key decisions, and future-proofing notes.
+- `docs/UI_DESIGN.md` — detailed notes on the display row, keypad styling, and rendering approach.
+- Workflows in `.gitea/workflows/` (CI on push/PR + release on v* tags) are modeled after gostations and grokkit.
+- Pure engine in `internal/calc/` (easy to test independently of the UI).
+- UI in `internal/ui/` uses Bubble Tea + lipgloss (reuses patterns from gostations: centered cards, button cells, 140 ms color-63 flashes, minimal hints).
+
+The project is part of a personal collection of console apps (see the REXX `~/.local/bin/apps` launcher). It is designed to be keyboard-primary and pleasant to use in a modern terminal.
+
+## License
+
+See the UNLICENSE file (or equivalent in the root) for this personal project.
+
+---
+
+Built as an exercise in Bubble Tea TUI design, with heavy reuse of patterns from the gostations radio player. Feedback and iteration welcome!