diff --git a/README.md b/README.md
index 66ec620..c278746 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,11 @@
# vf
-Command-line interface for the *Realtime* API.
-
-[](https://www.speakeasy.com/?utm_source=github-com/voiceflow/cli&utm_campaign=cli)
-[](https://opensource.org/licenses/MIT)
+The Voiceflow CLI. Build, test, and operate AI agents on [Voiceflow](https://www.voiceflow.com), the AI agent platform for customer experience automation — from your terminal, your CI, or your coding agent.
+`vf` covers the full agent lifecycle: workspaces, projects, environments, playbooks, functions, knowledge base documents, conversations, tests, evaluations, transcripts, and analytics. Every read command speaks JSON (and [TOON](https://github.com/toon-format/spec)); every failure names its own fix.
-
-> [!IMPORTANT]
-> This CLI is not yet ready for production use. To complete setup please follow the steps outlined in your [workspace](https://app.speakeasy.com/org/voiceflow/engineering). Delete this section before > publishing to a package manager.
+[](https://www.speakeasy.com/?utm_source=github-com/voiceflow/cli&utm_campaign=cli)
+[](https://opensource.org/license/Apache-2.0)
## Summary
@@ -38,6 +35,18 @@ Realtime: Realtime gateway API service
## CLI Installation
+### npm
+
+```bash
+# Run without installing
+npx -y @voiceflow/cli --help
+
+# Or install globally (provides both `vf` and `voiceflow`)
+npm install -g @voiceflow/cli
+```
+
+Installs a prebuilt binary for your platform (macOS, Linux, Windows — arm64 and x64) with no postinstall scripts and no compilation.
+
### Quick Install (Linux/macOS)
```bash
@@ -63,6 +72,41 @@ go install github.com/voiceflow/cli/cmd/vf@latest
Download pre-built binaries for your platform from the [releases page](https://github.com/voiceflow/cli/releases).
+## Quickstart: zero to a talking agent
+
+Runnable end to end by a person or by a coding agent. You need an access token and [`jq`](https://jqlang.org) (used only to pull IDs out of the JSON responses). Create a **personal access token** in Voiceflow under **Settings → Access tokens** (tokens start with `vfp_`; they expire, default 30 days), then:
+
+```bash
+export VF_TOKEN=vfp_... # every command also accepts --token
+
+# 1. Pick a workspace (also proves the token works)
+WORKSPACE_ID=$(vf workspace list --output-format json | jq -r '.workspaces[0].id')
+
+# 2. Create an agent project
+PROJECT_ID=$(vf project create --name "My Agent" --type webchat \
+ --workspace-id "$WORKSPACE_ID" --output-format json | jq -r '.project.id')
+
+# 3. Start a conversation (fresh projects have one environment, alias "main")
+vf conversation send --user-id quickstart-user --project-id "$PROJECT_ID" \
+ --environment-alias main --version-param draft \
+ --action '{"type":"launch"}' --output-format json
+
+# 4. Say something — same user-id continues the same conversation
+vf conversation send --user-id quickstart-user --project-id "$PROJECT_ID" \
+ --environment-alias main --version-param draft \
+ --action '{"type":"text","payload":"What can you help me with?"}' --output-format json
+```
+
+The agent's replies arrive as `text` traces in the response. From here: edit the agent's instructions (`vf agent update`), add knowledge (`vf document create-url`), run tests (`vf test run create`), and publish (`vf environment publish`).
+
+Worth knowing before you script against the CLI:
+
+- **Use `--version-param draft`** — a fresh project has no published release yet.
+- **Pass `--output-format json` explicitly when piping.** Inside AI coding agents (`CLAUDE_CODE`, `CURSOR_AGENT`, …) the default output is TOON, not JSON.
+- **Capture values with `--output-format json | jq -r`** — the built-in `--jq` flag emits JSON, so strings keep their quotes.
+- **`vf whoami` is offline** — it shows which credential source is configured but does not validate the token. `vf workspace list` is the real check.
+- **Look things up in-band**: `vf docs search "publish an environment"` and `vf docs get ` bring the documentation to the terminal — no browser, no auth.
+
## Shell Completion