diff --git a/README.md b/README.md
index 9ac74ce..b2359f1 100644
--- a/README.md
+++ b/README.md
@@ -2,23 +2,99 @@
 
 A command-line tool for managing Credential Engine platform resources.
 
-All commands follow the format:
-
-```
-ce <noun> [<noun>] <verb> [--<parameters>]
-```
-
 ## Requirements
-
-- Python 3.10+
-
+ 
+- Python 3.10 or later
+- `pip`
 ## Installation
-
+ 
+> **Recommended:** install inside a virtual environment. This avoids file-permission errors, PATH conflicts, and "invalid distribution" warnings from previous installs.
+ 
+### Option 1: Install from source with a virtual environment (recommended)
+ 
+**macOS / Linux:**
+ 
 ```bash
+git clone https://github.com/CredentialEngine/ce-cli.git
+cd ce-cli
+ 
+python3 -m venv .venv
+source .venv/bin/activate
+ 
 pip install -e .
 ```
+ 
+**Windows (PowerShell):**
+ 
+```powershell
+git clone https://github.com/CredentialEngine/ce-cli.git
+cd ce-cli
+ 
+python -m venv .venv
+.venv\Scripts\activate
+ 
+pip install -e .
+```
+ 
+When the venv is active you'll see `(.venv)` in your prompt, and `ce` is automatically on `PATH`. To leave the venv, run `deactivate`. To re-enter it next time, run the activate command above from the project folder.
+ 
+### Option 2: Install from a release
+ 
+1. Download the `.whl` from the [Releases page](https://github.com/CredentialEngine/ce-cli/releases).
+2. Install it (inside a venv is still recommended):
+   ```bash
+   pip install ce_cli-<version>-py3-none-any.whl
+   ```
+
+ ### Upgrading
+ 
+From a release `.whl`:
+ 
+```bash
+pip install --upgrade ce_cli-<version>-py3-none-any.whl
+```
+ 
+From source: `git pull` and re-run `pip install -e .` inside your venv.
+ 
+### Option 3: Install from source without a venv
+ 
+```bash
+git clone https://github.com/CredentialEngine/ce-cli.git
+cd ce-cli
+pip install -e .
+```
+ 
+This puts the `ce` command on your `$PATH`. On Windows, see the [Windows PATH note](#windows-path-note) below if `ce` isn't found.
+ 
+### Verify the installation
+ 
+```bash
+ce --help
+```
+ 
+You should see the top-level command list.
+ 
+### Windows PATH note
+ 
+When you install on Windows without a venv, pip often drops ce.exe into your user Scripts folder, which Windows doesn't put on PATH by default:
+ 
+```
+C:\Users\<you>\AppData\Roaming\Python\Python310\Scripts
+```
+ 
+If `ce --help` fails after install, either use a venv (recommended) or add that folder to your User PATH:
+ 
+```powershell
+[Environment]::SetEnvironmentVariable(
+  "Path",
+  $env:Path + ";C:\Users\$env:USERNAME\AppData\Roaming\Python\Python310\Scripts",
+  "User"
+)
+```
+ 
+Then **close and reopen PowerShell** existing windows won't pick up the new PATH.
+ 
 
-This puts the `ce` command on your `$PATH`.
 
 ## Quick start