diff --git a/CLAUDE.md b/CLAUDE.md
index 79f5603..9b436bc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8,11 +8,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # First-time setup: generate the Gradle wrapper (requires Gradle installed)
 gradle wrapper --gradle-version 8.9
 
-# Build debug APK
-./gradlew assembleDebug
+# Build debug APK (inside nix dev shell)
+nix develop --command gradle --no-daemon assembleDebug
 
-# Build release APK
-./gradlew assembleRelease
+# Build release APK — requires android-signing-env (sets signing vars + PUSH_GATEWAY_URL)
+android-signing-env nix develop --command gradle --no-daemon assembleRelease
 
 # Install on connected device/emulator
 ./gradlew installDebug
@@ -24,6 +24,20 @@ gradle wrapper --gradle-version 8.9
 ./gradlew clean
 ```
 
+### Secrets setup (required before release build)
+
+```bash
+# Creates symlinks for google-services.json, firebase-service-account.json, .mc/credentials.json
+# Only needed once per boot (symlinks point into /run/agenix which is tmpfs)
+matrix-android-secrets /home/ltadeu6/Projetos/Codigo/matrix-android
+```
+
+### Deploy Cloudflare Worker (push gateway)
+
+```bash
+cloudflare-worker-env nix develop --command wrangler deploy --config gateway/wrangler.toml
+```
+
 The project has no unit tests yet. Android Studio is the recommended way to open, sync, and run the project.
 
 ## Architecture