diff --git a/CLAUDE.md b/CLAUDE.md
index ec691065..acf1e335 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,6 +6,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Grazel is a Gradle plugin that automates migration of Android projects from Gradle to Bazel build system. It generates `BUILD.bazel` and `WORKSPACE` files based on existing Gradle configuration.
 
+**Important:** This project maintains both Gradle and Bazel builds. When working on new features, ensure that both build systems pass their respective tests.
+
 ## Build Commands
 
 ```bash
@@ -24,16 +26,36 @@ Grazel is a Gradle plugin that automates migration of Android projects from Grad
 # Generate Bazel scripts to test migration
 ./gradlew migrateToBazel
 
-# Clean generated Bazel files
-./gradlew bazelClean
-
-# Build and run bazel build on generated files
-./gradlew bazelBuildAll
-
 # Publish to local maven (for local testing)
 ./gradlew :grazel-gradle-plugin:publishToMavenLocal
 ```
 
+## Bazelisk
+
+This project uses **bazelisk** (a Bazel version manager/launcher) instead of invoking `bazel` directly. Bazelisk automatically downloads and uses the Bazel version specified in `.bazelversion`.
+
+**Installation:** https://github.com/bazelbuild/bazelisk#installation
+
+```bash
+# Build all generated Bazel targets
+bazelisk build //...
+
+# Build a specific target (format: //module:target_name)
+bazelisk build //sample-android-library:sample-android-library
+
+# Query available targets
+bazelisk query //...:*
+
+# Query android library targets only
+bazelisk query "kind(android_library, //...:*)"
+
+# Run tests via Bazel
+bazelisk test //...
+
+# Clean Bazel build artifacts
+bazelisk clean
+```
+
 ## Architecture
 
 ### Plugin Structure (`grazel-gradle-plugin/src/main/kotlin/com/grab/grazel/`)
@@ -65,7 +87,7 @@ Grazel is a Gradle plugin that automates migration of Android projects from Grad
 
 - **`extension/`**: Individual extension classes for each configuration block (Android, Kotlin, Maven, Dagger, etc.)
 
-- **`hybrid/`**: Experimental hybrid build support (not currently active)
+- **`hybrid/`**: Legacy hybrid build code (no longer used)
 
 ### Key Patterns
 
@@ -85,7 +107,7 @@ Grazel is a Gradle plugin that automates migration of Android projects from Grad
 
 ### Sample Modules
 
-The root project includes sample modules for testing migration:
+The root project includes sample modules used to test the migration. These modules can be built with both Gradle and Bazel:
 - `sample-android/`: Android application
 - `sample-android-library/`: Android library
 - `sample-kotlin-library/`: Pure Kotlin library
diff --git a/README.md b/README.md
index 2cb99b2d..0a4129c4 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,11 @@ to [Bazel build](https://bazel.build) system in an incremental and automated fas
 <img src="docs/images/grazel-demo.gif" width="85%">
 </p>
 
+## Requirements
+
+* Android SDK with `ANDROID_HOME` environment variable set
+* [Bazelisk](https://github.com/bazelbuild/bazelisk#installation) - to build generated Bazel files
+
 ## Components
 
 * [Gradle plugin](https://github.com/grab/grazel/tree/master/grazel-gradle-plugin)
@@ -27,6 +32,27 @@ to [Bazel build](https://bazel.build) system in an incremental and automated fas
 * Powered by [Grab Bazel Common](https://github.com/grab/grab-bazel-common) - custom Bazel rules for Android/Kotlin
 * Gradle remains the source of truth and minimal code changes required on Gradle side.
 
+## Usage
+
+Generate Bazel build files from your Gradle configuration:
+
+```bash
+./gradlew migrateToBazel
+```
+
+Build with Bazel using the generated files:
+
+```bash
+# Build all targets
+bazelisk build //...
+
+# Build a specific module
+bazelisk build //my-library:my-library-debug
+
+# Run tests
+bazelisk test //...
+```
+
 For documentation and usage instructions, please visit [website](https://grab.github.io/grazel/).
 
 ## How it works