diff --git a/README.md b/README.md
index 9d806b4..390b8d1 100644
--- a/README.md
+++ b/README.md
@@ -27,11 +27,11 @@ Once installed, the `capiscio` command is available in your terminal. It passes
 # Validate an agent
 capiscio validate https://my-agent.example.com
 
-# Check compliance score
-capiscio score https://my-agent.example.com
+# Validate with JSON output (includes scores)
+capiscio validate https://my-agent.example.com --json
 
 # Check version
-capiscio --version
+capiscio version
 ```
 
 ### Wrapper Utilities
diff --git a/docs/index.md b/docs/index.md
index 309b46c..b0281c3 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,7 +5,10 @@ description: Official documentation for the CapiscIO Python CLI wrapper.
 
 # CapiscIO Python CLI
 
-The **CapiscIO Python CLI** is a lightweight wrapper around the CapiscIO Core binary, designed for seamless integration into Python environments.
+The **CapiscIO Python CLI** is a lightweight wrapper around the [CapiscIO Core](https://github.com/capiscio/capiscio-core) binary, designed for seamless integration into Python environments.
+
+!!! info "This is a Wrapper Package"
+    This package does NOT contain validation logic. It downloads and executes the `capiscio-core` Go binary, which performs the actual validation.
 
 <div class="grid cards" markdown>
 
@@ -21,14 +24,32 @@ The **CapiscIO Python CLI** is a lightweight wrapper around the CapiscIO Core bi
 
     ---
 
-    Command reference and usage.
+    Wrapper commands and usage.
 
     [:octicons-arrow-right-24: Commands](./reference/commands.md)
 
 </div>
 
-## Installation
+## Quick Start
 
 ```bash
+# Install
 pip install capiscio
+
+# Validate an agent card
+capiscio validate ./agent-card.json
+
+# Validate with JSON output (includes scores)
+capiscio validate ./agent-card.json --json
+
+# Check core binary version
+capiscio version
 ```
+
+## What This Package Does
+
+1. **Downloads** the correct `capiscio-core` binary for your platform (macOS/Linux/Windows, AMD64/ARM64)
+2. **Caches** the binary in your user cache directory
+3. **Executes** the binary with your arguments, using `os.execv()` for zero overhead
+
+All validation logic lives in `capiscio-core`. This wrapper just makes it easy to install via pip.
diff --git a/docs/reference/commands.md b/docs/reference/commands.md
index 9b4f097..05b3341 100644
--- a/docs/reference/commands.md
+++ b/docs/reference/commands.md
@@ -20,8 +20,27 @@ $ capiscio --wrapper-clean
 Cleaned cache directory: /Users/username/Library/Caches/capiscio/bin
 ```
 
-## Environment Variables
+---
 
-| Variable | Description |
-|----------|-------------|
-| `CAPISCIO_CORE_PATH` | (Optional) Override the path to the `capiscio-core` binary. If set, the wrapper will use this binary instead of downloading one. |
+## Core Commands
+
+All other commands are passed directly to the `capiscio-core` binary. See the [CLI Reference](https://docs.capisc.io/reference/cli/) for full documentation.
+
+### Common Commands
+
+```bash
+# Validate an agent card
+capiscio validate ./agent-card.json
+
+# Validate with JSON output
+capiscio validate ./agent-card.json --json
+
+# Validate with live endpoint testing
+capiscio validate https://agent.example.com --test-live
+
+# Check version of the core binary
+capiscio version
+
+# Generate a signing key
+capiscio key gen --output ./my-key.jwk
+```