docs: update README

.github/pull_request_template.md

@@ -2,6 +2,6 @@
 
 ### Checklist
 
+- [ ] **Docs** are autogenerated from CLI help — make sure the help text reflects your changes
 - [ ] **Helm chart** (`charts/k8s-reporter/`) updated, if needed. Note: these changes live in a **separate PR**
 - [ ] **Terraform provider** and related changes ([terraform-provider-kosli](https://github.com/kosli-dev/terraform-provider-kosli), [terraform-aws-evidence-reporter](https://github.com/kosli-dev/terraform-aws-evidence-reporter), [terraform-aws-kosli-reporter](https://github.com/kosli-dev/terraform-aws-kosli-reporter)) updated, if needed
-- [ ] **Docs** are autogenerated from CLI help — make sure the help text reflects your changes

README.md

@@ -5,9 +5,79 @@
 
 # Kosli CLI
 
-This repo contains the Kosli CLI, for recording and querying software delivery events to [Kosli](www.kosli.com).
+The Kosli CLI records and queries software delivery events with [Kosli](https://www.kosli.com), giving you a tamper-evident record of how your software was built, tested, and deployed.
 
-Some useful links:
+With it you can:
+
+* **Fingerprint artifacts** — compute the SHA256 of files, directories, and OCI/Docker images.
+* **Record attestations and evidence** — bind test results, security scans (Snyk, SonarQube), pull-request approvals, Jira issues, and custom evidence to your flows and trails.
+* **Snapshot running environments** — report what is actually running in Kubernetes, ECS, Lambda, S3, Docker, Azure Web Apps, GCP Cloud Run, servers, and filesystem paths.
+* **Query and assert compliance** — search and diff snapshots, and gate your CI/CD pipelines with `kosli assert` commands.
+
+See the [documentation site](https://docs.kosli.com/) for the full command reference and usage guides.
+
+## Installation
+
+Install with whichever method suits your platform. After installing, run `kosli version` to verify.
+
+### Install script (Linux / macOS)
+
+```sh
+curl -sSL https://raw.githubusercontent.com/kosli-dev/cli/main/install-cli.sh | sh
+```
+
+The script detects your OS and architecture and installs the matching release binary into a directory on your `PATH`. To install a specific version, pass the tag as an argument:
+
+```sh
+curl -sSL https://raw.githubusercontent.com/kosli-dev/cli/main/install-cli.sh | sh -s -- v<X.Y.Z>
+```
+
+### Homebrew (macOS / Linux)
+
+```sh
+brew install kosli-cli
+```
+
+Upgrade later with `brew upgrade kosli-cli`.
+
+### npm
+
+```sh
+npm install -g @kosli/cli
+```
+
+> `npx @kosli/cli` is **not** supported — `npx` skips the optional platform dependency, so install the package first.
+
+### Docker
+
+```sh
+docker run --rm ghcr.io/kosli-dev/cli:v<X.Y.Z> version
+```
+
+Images are published to `ghcr.io/kosli-dev/cli` for each release tag.
+
+### Download a release binary
+
+Every release ships prebuilt archives, `.deb`/`.rpm` packages, and checksums on the [GitHub Releases](https://github.com/kosli-dev/cli/releases) page. Download the archive for your OS and architecture, extract it, and move the `kosli` binary onto your `PATH`. For example, on Linux amd64:
+
+```sh
+curl -L https://github.com/kosli-dev/cli/releases/download/v<X.Y.Z>/kosli_<X.Y.Z>_linux_amd64.tar.gz | tar xz
+sudo mv kosli /usr/local/bin/
+kosli version
+```
+
+Archive names follow `kosli_<X.Y.Z>_<os>_<arch>.tar.gz` for Linux and macOS, and `kosli_<X.Y.Z>_windows_<arch>.zip` for Windows. See the [install docs](https://docs.kosli.com/getting_started/install/) for the complete list of options.
+
+### Build from source
+
+```sh
+make build      # produces ./kosli
+./kosli version
+```
+
+See the [developer guide](/dev-guide.md) for full build details, including Windows.
+
+## Documentation and links
 
 * [Documentation site](https://docs.kosli.com/) for full details on usage.
 * [Developer guide](/dev-guide.md) for details on working with the code in this repo.