docs: clarify installation steps (#329)

* readme

* clarify-installation

* cleanup

* remove-extra-sentence

* add-ocr-troubleshooting-entry

* explain-uvx-error-more

* explain-uvx-difference-more

* bump-pdf

README.md

@@ -26,11 +26,17 @@ OpenRAG is a comprehensive Retrieval-Augmented Generation platform that enables
 
 ## Quickstart
 
-Use the OpenRAG Terminal User Interface (TUI) to manage your OpenRAG installation without complex command-line operations.
+To quickly run OpenRAG without creating or modifying any project files, use `uvx`:
 
-To quickly install and start OpenRAG, run `uvx openrag`.
+```bash
+uvx openrag
+```
+This runs OpenRAG without installing it to your project or globally.
+To run a specific version of OpenRAG, add the version to the command, such as: `uvx --from openrag==0.1.25 openrag`.
 
-To first set up a project and then install OpenRAG, do the following:
+## Install Python package
+
+To first set up a project and then install the OpenRAG Python package, do the following:
 
 1. Create a new project with a virtual environment using `uv init`.
 
@@ -42,17 +48,22 @@ To first set up a project and then install OpenRAG, do the following:
    The `(venv)` prompt doesn't change, but `uv` commands will automatically use the project's virtual environment.
    For more information on virtual environments, see the [uv documentation](https://docs.astral.sh/uv/pip/environments).
 
-2. Ensure all dependencies are installed and updated in your virtual environment.
+2. Add OpenRAG to your project.
    ```bash
-   uv sync
+   uv add openrag
    ```
 
-3. Install and start the OpenRAG TUI.
+   To add a specific version of OpenRAG:
    ```bash
-   uvx openrag
+   uv add openrag==0.1.25
    ```
-   
-   To install a specific version of the Langflow package, add the required version to the command, such as `uvx --from openrag==0.1.25 openrag`.
+
+3. Start the OpenRAG TUI.
+   ```bash
+   uv run openrag
+   ```
+
+4. Continue with the [Quickstart](https://docs.openr.ag/quickstart).
 
 For the full TUI installation guide, see [TUI](https://docs.openr.ag/install).
 

docs/docs/get-started/install.mdx

@@ -7,7 +7,7 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; 
 
-[Install the OpenRAG Python wheel](#install-python-wheel), and then run the [OpenRAG Terminal User Interface(TUI)](#setup) to start your OpenRAG deployment with a guided setup process.
+[Install OpenRAG](#install) and then run the [OpenRAG Terminal User Interface(TUI)](#setup) to start your OpenRAG deployment with a guided setup process.
 
 The OpenRAG Terminal User Interface (TUI) allows you to set up, configure, and monitor your OpenRAG deployment directly from the terminal.
 
@@ -28,17 +28,13 @@ If you prefer running Podman or Docker containers and manually editing `.env` fi
 - Create an [OpenAI API key](https://platform.openai.com/api-keys). This key is **required** to start OpenRAG, but you can choose a different model provider during [Application Onboarding](#application-onboarding).
 - Optional: Install GPU support with an NVIDIA GPU, [CUDA](https://docs.nvidia.com/cuda/) support, and compatible NVIDIA drivers on the OpenRAG host machine. If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment.
 
+## Install OpenRAG {#install}
+
 :::note Windows users
 To use OpenRAG on Windows, use [WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install).
 :::
 
-## Install the OpenRAG Python wheel {#install-python-wheel}
-
-The OpenRAG wheel installs the Terminal User Interface (TUI) for configuring and running OpenRAG.
-
-To quickly install and start OpenRAG, run `uvx openrag`.
-
-To first set up a project and then install OpenRAG, do the following:
+To set up a project and install OpenRAG as a dependency, do the following:
 
 1. Create a new project with a virtual environment using `uv init`.
 
@@ -50,20 +46,23 @@ To first set up a project and then install OpenRAG, do the following:
    The `(venv)` prompt doesn't change, but `uv` commands will automatically use the project's virtual environment.
    For more information on virtual environments, see the [uv documentation](https://docs.astral.sh/uv/pip/environments).
 
-2. Ensure all dependencies are installed and updated in your virtual environment.
+2. Add OpenRAG to your project.
    ```bash
-   uv sync
+   uv add openrag
    ```
 
-3. Install and start the OpenRAG TUI.
+   To add a specific version of OpenRAG:
    ```bash
-   uvx openrag
+   uv add openrag==0.1.25
+   ```
+
+3. Start the OpenRAG TUI.
+   ```bash
+   uv run openrag
    ```
-   
-   To install a specific version of the Langflow package, add the required version to the command, such as `uvx --from openrag==0.1.25 openrag`.
 
     <details closed>
-    <summary>Install a local wheel without uvx</summary>
+    <summary>Install a local wheel</summary>
     
     If you downloaded the OpenRAG wheel to your local machine, follow these steps:
 

docs/docs/support/troubleshoot.mdx

@@ -38,6 +38,26 @@ This example increases the machine size to 8 GB of RAM, which should be sufficie
 
 Ensure ports 3000, 7860, 8000, 9200, 5601 are available.
 
+## OCR ingestion fails (easyocr not installed)
+
+If Docling ingestion fails with an OCR-related error and mentions `easyocr` is missing, this is likely due to a stale `uv` cache.
+
+`easyocr` is already included as a dependency in OpenRAG's `pyproject.toml`. Project-managed installations using `uv sync` and `uv run` always sync dependencies directly from your `pyproject.toml`, so they should have `easyocr` installed.
+
+If you're running OpenRAG with `uvx openrag`, `uvx` creates a cached, ephemeral environment that doesn't modify your project. This cache may become stale. 
+
+On macOS, this cache directory is typically a user cache directory such as `/Users/USER_NAME/.cache/uv`.
+1. To clear the uv cache, run:
+    ```bash
+    uv cache clean
+    ```
+2. Start OpenRAG:
+    ```bash
+    uvx openrag
+    ```
+
+If you do not need OCR, you can disable OCR-based processing in your ingestion settings to avoid requiring `easyocr`.
+
 ## Langflow container already exists
 
 If you are running other versions of Langflow containers on your machine, you may encounter an issue where Docker or Podman  thinks Langflow is already up.