docs: overhaul README for public audience

.github/pull_request_template.md

@@ -1,5 +0,0 @@
-
-
-## Checklist
-
-- [ ] [Technical docs](https://github.com/infracost/technical-docs) updated (or not needed)

README.md

@@ -5,26 +5,110 @@
 > This repository is in early alpha. Features may change and rough edges are expected.
 > [Open a discussion thread](https://github.com/infracost/infracost/discussions) to report bugs or
 > share feedback — it is genuinely appreciated.
-
-## Prerequisites
 
-### GitHub Access
+Infracost estimates cloud costs from infrastructure as code, helping you catch cost surprises before they hit your bill.
+It currently supports Terraform, Terragrunt, and CloudFormation.
 
-Plugins are hosted as GitHub release assets on this (currently private) repository. The CLI needs a GitHub token to 
-download them. It checks for a token in the following order:
+## Installation
 
-1. `GH_TOKEN` environment variable
-2. `GITHUB_TOKEN` environment variable
-3. `gh auth token` (if the [GitHub CLI](https://cli.github.com/) is installed and authenticated)
+Download the latest release archive for your platform from the
+[GitHub Releases page](https://github.com/infracost/cli/releases), then extract the binary and place it somewhere on
+your `PATH`.
+
+For example, on macOS (Apple Silicon):
+
+```bash
+# Download and extract
+tar -xzf infracost-preview_0.0.2_darwin_arm64.tar.gz
+
+# Move the binary onto your PATH
+mv infracost-preview /usr/local/bin/infracost-preview
+```
+
+On Linux (amd64):
+
+```bash
+tar -xzf infracost-preview_0.0.2_linux_amd64.tar.gz
+mv infracost-preview /usr/local/bin/infracost-preview
+```
+
+On Windows, download the `.zip` archive and extract it to a directory on your `PATH`.
+
+Once installed, verify it works:
+
+```bash
+infracost-preview help
+```
+
+### Uninstalling
+
+Remove the binary and the cached configuration/token data.
+
+On macOS:
+
+```bash
+rm $(which infracost-preview)
+rm -rf "$HOME/Library/Application Support/infracost"
+```
+
+On Linux:
+
+```bash
+rm $(which infracost-preview)
+rm -rf "${XDG_CONFIG_HOME:-$HOME/.config}/infracost"
+```
+
+On Windows (PowerShell):
+
+```powershell
+Remove-Item (Get-Command infracost-preview).Source
+Remove-Item -Recurse "$env:APPDATA\infracost"
+```
+
+### Building locally
+
+If you prefer to build from source:
+
+1. `make build`
+2. `./bin/infracost help`
+
+## Usage
+
+### Login
+
+Before running any commands, authenticate with Infracost:
+
+```bash
+infracost-preview login
+```
+
+This opens a browser-based login flow (PKCE). The resulting token is cached locally so you only need to log in once. If
+you don't have access to a browser or localhost, use the device flow instead:
+
+```bash
+infracost-preview login --oauth-use-device-flow
+```
+
+For non-interactive environments (CI/CD), set the `INFRACOST_CLI_AUTHENTICATION_TOKEN` environment variable to a
+service account token or personal access token instead of using the login command.
+
+### Scan
+
+```bash
+infracost-preview scan /path/to/directory
+```
+
+The target must be a directory. If no argument is given, it defaults to the current working directory. The CLI will
+auto-detect the IaC type from the directory contents, or you can configure projects explicitly via an `infracost.yml`
+config file.
 
 ### Plugins
 
-Plugins are downloaded automatically from the manifest when you run the CLI. No manual setup is required beyond having
-GitHub access configured above.
+Plugins are downloaded automatically from the manifest when you run the CLI. No manual setup is required.
 
 #### Version Pinning
 
-By default, the CLI downloads the latest version of each plugin. You can pin to a specific version using environment 
+By default, the CLI downloads the latest version of each plugin. You can pin to a specific version using environment
 variables:
 
 - `INFRACOST_CLI_PARSER_PLUGIN_VERSION` — pin the parser plugin version
@@ -39,7 +123,7 @@ version if one exists, and only downloads from the manifest if no cached version
 
 #### Local Plugin Overrides
 
-If you are developing plugins locally, you can bypass the download mechanism entirely by pointing the CLI at your local 
+If you are developing plugins locally, you can bypass the download mechanism entirely by pointing the CLI at your local
 builds:
 
 ```bash
@@ -53,18 +137,3 @@ export INFRACOST_CLI_PROVIDER_PLUGIN_AZURERM=/path/to/bin/infracost-provider-plu
 ```
 
 When a plugin path override is set, the CLI uses that binary directly and skips downloading for that plugin.
-
-## Running the CLI
-
-1. `make build`
-2. `./bin/infracost help`
-
-### Scan
-
-```bash
-./bin/infracost scan /path/to/directory
-```
-
-The target must be a directory. If no argument is given, it defaults to the current working directory. The CLI will 
-auto-detect the IaC type from the directory contents, or you can configure projects explicitly via an `infracost.yml` 
-config file.