Initial commit: multimodal RAG guide with Claude Code

Prompt-driven guide for building multimodal search using
Gemini Embedding 2 + Pinecone + Claude Code. Includes example
data (NASA public domain), step-by-step prompts, concepts
explainer, cost breakdown, and troubleshooting guide.

troubleshooting.md

@@ -0,0 +1,96 @@
+# Troubleshooting
+
+Common problems and how to fix them.
+
+## 1. "API key not found" or "Invalid API key"
+
+**What happened:** The .env file is missing, in the wrong place,
+or the key was copied incorrectly.
+
+**Fix:** Open the .env file in your project folder. Check that:
+- The file is named exactly `.env` (not `env.txt` or `.env.txt`)
+- There are no spaces around the `=` sign
+- The key is complete (no missing characters from copy-paste)
+
+Tell Claude Code: "Check if my .env file is set up correctly."
+
+## 2. "Module not found" or dependency errors
+
+**What happened:** The project dependencies were not installed.
+
+**Fix:** Tell Claude Code: "Install the project dependencies."
+It will run the right install command for you.
+
+## 3. Image search returns bad results
+
+**What happened:** The image descriptions are too vague.
+
+**Fix:** Open `descriptions.md` and improve the descriptions.
+Compare your descriptions to the "good" examples in that file.
+Then tell Claude Code: "Re-index the images with the updated
+descriptions."
+
+## 4. PDF content is not showing up in search
+
+**What happened:** The PDF might be scanned (image-based)
+rather than text-based, or it might be too large.
+
+**Fix:** Tell Claude Code: "Check if the PDFs contain extractable
+text." If a PDF is image-based, Claude Code can use OCR to
+extract the text.
+
+## 5. Search is slow
+
+**What happened:** This is normal for the first search after
+starting the app. The system needs to load.
+
+**Fix:** Wait a few seconds. Subsequent searches will be faster.
+If it stays slow, tell Claude Code: "The search is slow. Can you
+optimize the query?"
+
+## 6. "Rate limit exceeded" from Google
+
+**What happened:** You sent too many requests too quickly.
+
+**Fix:** Wait one minute and try again. The free tier allows
+1,500 requests per day but has a per-minute limit too. For the
+example files in this guide, you should never hit this limit.
+
+## 7. Pinecone index not found
+
+**What happened:** The index name in your code does not match
+what you created in Pinecone.
+
+**Fix:** Log into pinecone.io, check your index name, and tell
+Claude Code: "My Pinecone index is named [your-index-name].
+Update the configuration."
+
+## 8. Claude Code asks me something I do not understand
+
+**What happened:** Claude Code sometimes asks technical questions
+about implementation choices.
+
+**Fix:** You can safely answer with: "Use the simplest option"
+or "You decide, I trust your judgment." Claude Code will pick
+sensible defaults.
+
+## 9. The app works but results are not great
+
+**What happened:** Search quality depends on the descriptions
+and the chunking strategy.
+
+**Fix:** Three things to try:
+1. Improve your image descriptions (this makes the biggest difference)
+2. Tell Claude Code: "The search results are not relevant enough.
+   Can you adjust the chunking or add re-ranking?"
+3. Try rephrasing your search query in different ways
+
+## 10. Something else is broken
+
+Tell Claude Code exactly what you see. Copy-paste the error message.
+Claude Code is very good at diagnosing and fixing problems when
+you give it the exact error text.
+
+If you are stuck, you can also start fresh: tell Claude Code
+"Let's start over. Delete the current search index and re-build
+everything from scratch."