diff --git a/.env.example b/.env.example
index 649734c..86ec55b 100644
--- a/.env.example
+++ b/.env.example
@@ -1,6 +1,9 @@
 ANTHROPIC_API_KEY=your_anthropic_api_key
-OPENAI_API_KEY=your_openai_api_key (optional, for ChatGPT visibility checks)
-GOOGLE_API_KEY=your_google_api_key (optional, for Gemini visibility checks)
+# optional, for ChatGPT visibility checks
+OPENAI_API_KEY=
+# optional, for Gemini visibility checks
+GOOGLE_API_KEY=
 CMS_API_URL=your_cms_api_endpoint
 CMS_API_KEY=your_cms_api_key
-APOLLO_API_KEY=your_apollo_key (optional, for enrichment)
+# optional, for enrichment
+APOLLO_API_KEY=
diff --git a/README.md b/README.md
index c58b2de..b60a372 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ Built by [Surface Labs](https://withsurface.com), a lead operations center that
 ## quick start
 
 ```bash
-git clone https://github.com/surface-labs/surface-aeo-geo-engine.git
+git clone https://github.com/trysurface/surface-aeo-geo-engine.git
 cd surface-aeo-geo-engine
 cp .env.example .env
 # add your api keys to .env
diff --git a/scripts/run-pipeline.sh b/scripts/run-pipeline.sh
index de61133..2ed1716 100755
--- a/scripts/run-pipeline.sh
+++ b/scripts/run-pipeline.sh
@@ -24,6 +24,13 @@ mkdir -p outputs drafts published reports
 
 read -r -p "transcript path, or leave blank to only generate questions: " TRANSCRIPT_PATH
 
+# validate the path before spending an agent run, not after.
+if [ -n "${TRANSCRIPT_PATH}" ] && [ ! -f "$TRANSCRIPT_PATH" ]; then
+  echo "transcript not found: $TRANSCRIPT_PATH"
+  echo "put the file in inputs/transcripts/ and pass the path to it, or leave the prompt blank to only generate questions."
+  exit 1
+fi
+
 run_agent "agents/01-question-generator" "outputs/01-question-generator.md" "create the 40-question list first."
 
 if [ -z "${TRANSCRIPT_PATH}" ]; then
@@ -31,11 +38,6 @@ if [ -z "${TRANSCRIPT_PATH}" ]; then
   exit 0
 fi
 
-if [ ! -f "$TRANSCRIPT_PATH" ]; then
-  echo "transcript not found: $TRANSCRIPT_PATH"
-  exit 1
-fi
-
 run_agent "agents/02-transcript-extractor" "outputs/02-transcript-extractor.md" "use transcript file $TRANSCRIPT_PATH."
 run_agent "agents/03-angle-spinner" "outputs/03-angle-spinner.md" "use outputs/02-transcript-extractor.md."
 run_agent "agents/04-aeo-geo-optimizer" "outputs/04-aeo-geo-optimizer.md" "use outputs/03-angle-spinner.md and choose the best 5 angles."
diff --git a/scripts/setup.sh b/scripts/setup.sh
index e2779cb..1a97308 100755
--- a/scripts/setup.sh
+++ b/scripts/setup.sh
@@ -6,9 +6,12 @@ cd "$ROOT_DIR"
 
 echo "setting up surface aeo/geo content engine"
 
+# collect every problem first, then report them together, so you fix one round
+# of errors instead of rerunning setup once per missing thing.
+PROBLEMS=()
+
 if ! command -v claude >/dev/null 2>&1; then
-  echo "claude code cli was not found. install it before running the pipeline: https://docs.anthropic.com/en/docs/claude-code"
-  exit 1
+  PROBLEMS+=("claude code cli not found. install it, then rerun: https://docs.anthropic.com/en/docs/claude-code")
 fi
 
 for dir in inputs/transcripts outputs drafts reports published; do
@@ -17,17 +20,39 @@ done
 
 if [ ! -f .env ]; then
   cp .env.example .env
-  echo "created .env from .env.example. add your api keys before publishing or visibility checks."
+  echo "created .env from .env.example"
 fi
 
-if grep -q "your_anthropic_api_key" .env; then
-  echo "ANTHROPIC_API_KEY still needs to be set in .env"
-else
-  echo "ANTHROPIC_API_KEY looks set"
+# .env is the documented place for keys, but nothing in this repo exports it,
+# so a key that is only in .env never reaches the claude subprocess. read the
+# file here and let an already-exported shell variable win.
+ENV_ANTHROPIC_KEY="$(sed -n 's/^[[:space:]]*ANTHROPIC_API_KEY[[:space:]]*=[[:space:]]*//p' .env | tail -n 1)"
+EFFECTIVE_ANTHROPIC_KEY="${ANTHROPIC_API_KEY:-$ENV_ANTHROPIC_KEY}"
+
+case "$EFFECTIVE_ANTHROPIC_KEY" in
+  "")
+    PROBLEMS+=("ANTHROPIC_API_KEY is empty or missing. set it in .env (ANTHROPIC_API_KEY=sk-ant-...) or export it in your shell.")
+    ;;
+  your_anthropic_api_key)
+    PROBLEMS+=("ANTHROPIC_API_KEY is still the placeholder 'your_anthropic_api_key'. replace it in .env with a real key.")
+    ;;
+  *)
+    echo "ANTHROPIC_API_KEY is set"
+    ;;
+esac
+
+if [ ${#PROBLEMS[@]} -gt 0 ]; then
+  echo
+  echo "setup failed. fix these first:"
+  for problem in "${PROBLEMS[@]}"; do
+    echo "  - $problem"
+  done
+  exit 1
 fi
 
+# non-fatal: drafts still generate without a cms, publishing just stays local.
 if grep -q "your_cms_api" .env; then
-  echo "cms keys are not set yet. you can still generate drafts, but publishing will stay in draft/payload mode."
+  echo "note: cms keys are not set. drafts will generate, publishing stays in draft/payload mode."
 fi
 
 echo "setup complete"