diff --git a/README.md b/README.md
index 2bccb26..0a8d687 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,66 @@
-# advanced-calculator
-A free-form calculator that uses [CS-MIC](https://github.com/wagesj45/cs-mic) to parse and process expressions.
+# Advanced Calculator
 
-![SCREEN_SHOT](screen_shot.png?raw=true "Advanced Calculator Screen Shot")
+A simple, fast, free‑form calculator. You can type full math expressions, define variables, and see results right away. It runs on desktop, the web (WebAssembly), and Android. The math engine is powered by [CS‑MIC](https://github.com/wagesj45/cs-mic).
 
----
+![Screenshot of Advanced Calculator](screen_shot.png?raw=true "Advanced Calculator Screen Shot")
 
-For information on what expressions are possible, please see the [CS-MIC Usage Documentation](http://cs-mic.com/usage/).
+## Features
+
+- Easy input: Type expressions like `2 + 2 * 3` and press Enter.
+- Variables: Save values and reuse them in later expressions.
+- Linked expressions: Define variables that compute from other variables.
+- History: See past inputs and results; copy any item with a click.
+- Function browser: Browse built‑in functions and insert them quickly.
+- Cross‑platform: Desktop (Windows, macOS, Linux), Web, and Android.
+
+## Quick Start
+
+Prerequisite: Install the .NET 8 SDK.
+
+- Desktop: `dotnet run --project src/AdvancedCalculator.Desktop`
+- Web (WASM): `dotnet run --project src/AdvancedCalculator.Browser` then open the URL shown in the console.
+- Android: Build with `dotnet build src/AdvancedCalculator.Android -c Debug`. Install the APK from the `bin` folder using Android Studio or `adb`.
+
+## How To Use
+
+- Evaluate: Type an expression and press Enter, or click the Evaluate button.
+- Define variables:
+  - Set a value: `x :: 5`
+  - Link to an expression: `y := x * 2`
+  The Variables panel shows both the stored value and, for linked ones, the current computed result.
+- Insert helpers: Use the Variables panel or the Functions button to insert names into the input box.
+- Copy: Right‑click a history item to copy the input, output, or both.
+
+For all supported operators and functions, see the CS‑MIC usage guide: http://cs-mic.com/usage/
+
+## Build and Publish
+
+You can create self‑contained builds for desktop platforms.
+
+- Windows (x64):
+  - `dotnet publish src/AdvancedCalculator.Desktop -c Release -r win-x64 --self-contained true`
+- Linux (x64):
+  - `dotnet publish src/AdvancedCalculator.Desktop -c Release -r linux-x64 --self-contained true`
+- macOS (Intel or Apple Silicon):
+  - `dotnet publish src/AdvancedCalculator.Desktop -c Release -r osx-x64 --self-contained true`
+  - `dotnet publish src/AdvancedCalculator.Desktop -c Release -r osx-arm64 --self-contained true`
+
+Web build output is written to the `out` folder when running the Browser project.
+
+## Technology
+
+- UI: [Avalonia](https://avaloniaui.net/)
+- Language/runtime: C# on .NET 8
+- Math engine: [CS‑MIC](https://github.com/wagesj45/cs-mic)
+
+## Privacy
+
+This app does not send your data anywhere. All calculations run on your device.
+
+## Contributing
+
+Issues and pull requests are welcome. If you want to add features or fix bugs, please open an issue to discuss first.
+
+## License
+
+MIT License. See the LICENSE file for details.