diff --git a/README.md b/README.md
index 9e78662..f6945f6 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,134 @@
 # cs-mic-cli
 
-A CLI client that parses shell input.
\ No newline at end of file
+`cs-mic-cli` is a small command line client for [CS-MIC](https://cs-mic.com/), a numeric expression interpreter for .NET.
+
+Use it when you want CS-MIC's expression syntax from a terminal: quick calculations, reusable variables in an interactive session, or a simple native executable you can call from scripts.
+
+## Downloads
+
+Release builds provide native executables for:
+
+- Windows x64: `csmic-win-x64.exe`
+- Linux x64: `csmic-linux-x64`
+
+On Linux, you can rename or symlink the binary to `csmic` and place it somewhere on your `PATH`, such as `~/.local/bin`.
+
+## Usage
+
+Evaluate an expression directly:
+
+```sh
+csmic "2 + 3 * 4"
+```
+
+Output:
+
+```text
+14
+```
+
+Use CS-MIC standard library constants and functions:
+
+```sh
+csmic "pi * 10^2"
+csmic "degrees(pi / 2)"
+csmic "max(0, 5 - 12)"
+```
+
+Start an interactive session:
+
+```sh
+csmic --interactive
+```
+
+or:
+
+```sh
+csmic -i
+```
+
+Inside the interactive prompt, enter expressions one at a time:
+
+```text
+csmic> 2 + 2
+4
+csmic> exit()
+```
+
+Show version information:
+
+```sh
+csmic --version
+```
+
+Show help:
+
+```sh
+csmic --help
+```
+
+## Options
+
+```text
+Usage:
+  cs-mic-cli [<expression>...] [options]
+
+Arguments:
+  <expression>  Expression to evaluate.
+
+Options:
+  --verbose          Displays parser/runtime error details when a soft error occurs.
+  -i, --interactive  Starts an interactive session.
+  -?, -h, --help     Show help and usage information.
+  --version          Show version information.
+```
+
+## Configuration
+
+At startup, the CLI loads an optional init file:
+
+```text
+$XDG_CONFIG_HOME/csmic/init.csmic
+```
+
+If `XDG_CONFIG_HOME` is not set, it uses:
+
+```text
+~/.config/csmic/init.csmic
+```
+
+The file is created automatically if it does not exist. Put one CS-MIC expression per line to define variables or other startup state before your command or interactive session runs.
+
+## Building
+
+Requirements:
+
+- .NET 8 SDK
+- Linux shell environment for `build.sh`
+
+Build both release executables:
+
+```sh
+./build.sh
+```
+
+The script publishes:
+
+- `dist/csmic-linux-x64`
+- `dist/csmic-win-x64.exe`
+
+It also installs the Linux build to `~/.local/bin/csmic`.
+
+For local development, run the project directly:
+
+```sh
+dotnet run --project src/cs-mic-cli -- "2 + 3 * 4"
+```
+
+## CS-MIC Documentation
+
+Expression syntax, standard library functions, constants, and the embeddable .NET packages are documented at:
+
+- [CS-MIC](https://cs-mic.com/)
+- [Using CS-MIC](https://cs-mic.com/usage.html)
+- [Standard Library](https://cs-mic.com/standard-library.html)