docs: add FAQ section for common questions

README.md

@@ -136,3 +136,101 @@ The tool uses a cloud-based LLM (OpenAI's GPT-4o and o1-preview models).
 
 ### LLM Training
 The LLM is not trained or improved by the usage of this tool.
+
+## FAQ
+
+### General
+
+**What is Integuru?**
+Integuru is an AI agent that generates integration code by reverse-engineering platforms' internal APIs. It analyzes browser network requests (via HAR files) to understand how a platform works, then generates runnable Python code that can perform the same actions programmatically.
+
+**How does Integuru work?**
+Integuru uses a three-step process:
+1. **Capture**: Use `create_har.py` to record your browser session while performing the desired action
+2. **Analyze**: The AI agent builds a dependency graph of all API requests involved
+3. **Generate**: Converts the graph into runnable Python functions that hit the platform's internal endpoints
+
+**What models does Integuru support?**
+Integuru currently supports OpenAI models:
+- **gpt-4o** (recommended for graph generation - supports function calling)
+- **o3-mini**, **o1**, **o1-mini** (used for code generation)
+- The agent automatically switches to o1-preview for code generation if available
+
+### Setup & Configuration
+
+**What are the system requirements?**
+- Python 3.12+
+- Poetry (Python package manager)
+- OpenAI API key (with access to gpt-4o or better)
+- Jupyter Notebook (optional, for interactive use)
+
+**How do I install Integuru?**
+```bash
+# Clone the repository
+git clone https://github.com/Integuru-AI/Integuru.git
+cd Integuru
+
+# Install dependencies
+poetry install
+
+# Activate the virtual environment
+poetry shell
+
+# Register Jupyter kernel (optional)
+poetry run ipython kernel install --user --name=integuru
+```
+
+**How do I set up my OpenAI API key?**
+Set the `OPENAI_API_KEY` environment variable:
+```bash
+export OPENAI_API_KEY="your-api-key-here"
+```
+
+### Usage
+
+**How do I capture browser requests?**
+Run `create_har.py` to spawn a browser, log into the target platform, perform the desired action (e.g., download a utility bill), and the tool will generate:
+- `network_requests.har` - All browser network requests
+- `cookies.json` - Authentication cookies/tokens
+
+**What is a HAR file?**
+HAR (HTTP Archive) is a JSON-formatted file that records all network requests made by your browser. It contains URLs, headers, cookies, and response data that Integuru uses to understand the platform's API structure.
+
+**How do I generate integration code?**
+```bash
+poetry run integuru --prompt "download utility bills" --model gpt-4o --generate-code
+```
+
+**What are input variables?**
+Input variables allow you to parameterize the generated code. For example, you can specify a YEAR variable to download documents for different years:
+```bash
+poetry run integuru --prompt "download utility bills" --input_variables YEAR 2024 --generate-code
+```
+
+### Troubleshooting
+
+**Graph generation fails or times out**
+- Ensure you are using gpt-4o (required for function calling)
+- Check your OpenAI API key is valid and has sufficient quota
+- Reduce `--max_steps` if the platform has many requests
+- Verify the HAR file contains all necessary requests
+
+**Code generation produces errors**
+- The agent may switch to o1-preview for code generation - ensure your account has access
+- Check that the dependency graph was correctly built
+- Review the generated code and fix any platform-specific issues manually
+
+**2FA authentication issues**
+- Complete the full 2FA process in the browser before capturing
+- Ensure the cookies.json file contains valid session tokens after 2FA
+- Some platforms may require re-authentication periodically
+
+**Poetry installation fails**
+- Ensure Python 3.12+ is installed
+- Try updating Poetry: `poetry self update`
+- Clear the Poetry cache: `poetry cache clear . --all`
+
+**CI tests fail**
+- Run tests locally first: `poetry run pytest`
+- Ensure all dependencies are installed: `poetry install`
+- Check Python version compatibility