From e844244d7e03336cb019dd294facf2d63dd09f07 Mon Sep 17 00:00:00 2001
From: April M <36110273+aimurphy@users.noreply.github.com>
Date: Tue, 16 Dec 2025 18:19:04 -0800
Subject: [PATCH] new paths for config etc

---
 docs/docs/_partial-factory-reset-warning.mdx |  5 +-
 docs/docs/_partial-setup.mdx                 |  6 +-
 docs/docs/core-components/agents.mdx         |  8 +-
 docs/docs/core-components/ingestion.mdx      |  2 +-
 docs/docs/core-components/knowledge.mdx      |  6 +-
 docs/docs/get-started/install-options.mdx    |  4 +-
 docs/docs/get-started/install-uv.mdx         |  6 +-
 docs/docs/get-started/install-uvx.mdx        |  4 +-
 docs/docs/get-started/install.mdx            |  2 +-
 docs/docs/get-started/manage-services.mdx    | 10 +-
 docs/docs/get-started/quickstart.mdx         |  6 +-
 docs/docs/get-started/reinstall.mdx          | 20 +---
 docs/docs/get-started/tui.mdx                |  2 +-
 docs/docs/get-started/uninstall.mdx          | 16 +---
 docs/docs/get-started/upgrade.mdx            |  2 +-
 docs/docs/reference/configuration.mdx        | 99 ++++++--------------
 docs/docs/support/troubleshoot.mdx           |  2 +-
 17 files changed, 68 insertions(+), 132 deletions(-)

diff --git a/docs/docs/_partial-factory-reset-warning.mdx b/docs/docs/_partial-factory-reset-warning.mdx
index 97f2ca7e..ab8cf85d 100644
--- a/docs/docs/_partial-factory-reset-warning.mdx
+++ b/docs/docs/_partial-factory-reset-warning.mdx
@@ -3,12 +3,11 @@ This is a destructive action that does the following:
 
 * Destroys all OpenRAG containers, volumes, and local images with `docker compose down --volumes --remove-orphans --rmi local`.
 * Prunes any additional container objects with `docker system prune -f`.
-* Deletes the contents of OpenRAG's `config` and `./opensearch-data` directories.
-* Deletes the `conversations.json` file.
+* Deletes the contents of OpenRAG's `~/.openrag/config`, `~/.openrag/flows`, and `~/.openrag/data` directories, including the `conversations.json` file.
 
 <p/>Destroyed containers and deleted data are lost and cannot be recovered after running this operation.
 
-This operation _doesn't_ remove the `.env` file or the contents of the `./openrag-documents` directory.
+This operation _doesn't_ remove the `.env` file or the contents of the `~/.openrag/documents` directory.
 :::
 
 <!--
diff --git a/docs/docs/_partial-setup.mdx b/docs/docs/_partial-setup.mdx
index 9af2ecbf..8142844d 100644
--- a/docs/docs/_partial-setup.mdx
+++ b/docs/docs/_partial-setup.mdx
@@ -37,7 +37,7 @@ If OpenRAG detects OAuth credentials during setup, it recommends **Advanced Setu
 
 4. Click **Save Configuration**.
 
-   Your passwords and API key, if provided, are stored in the [OpenRAG `.env` file](/reference/configuration) in your OpenRAG installation directory.
+   Your passwords and API key, if provided, are stored in the [OpenRAG `.env` file](/reference/configuration) at `~/.openrag/tui`.
    If you modified any credentials that were pulled from an existing `.env` file, those values are updated in the `.env` file.
 
 5. Click **Start All Services** to start the OpenRAG services that run in containers.
@@ -81,7 +81,7 @@ If OpenRAG detects OAuth credentials during setup, it recommends **Advanced Setu
    If you aren't sure which models or providers to use, you must provide an OpenAI API key to use OpenRAG's default model configuration.
    If you want to use a different model provider, you can leave this field empty.
 
-4. To upload documents from external storage, such as Google Drive, add the required OAuth credentials for the connectors that you want to use. These settings can be populated automatically if OpenRAG detects these credentials in an [OpenRAG `.env` file](/reference/configuration) in the OpenRAG installation directory.
+4. To upload documents from external storage, such as Google Drive, add the required OAuth credentials for the connectors that you want to use. These settings can be populated automatically if OpenRAG detects these credentials in an [OpenRAG `.env` file](/reference/configuration) at `~/.openrag/tui`.
 
    * **Amazon**: Provide your AWS Access Key ID and AWS Secret Access Key with access to your S3 instance. For more information, see the AWS documentation on [Configuring access to AWS applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-applications.html).
    * **Google**: Provide your Google OAuth Client ID and Google OAuth Client Secret. You can generate these in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials). For more information, see the [Google OAuth client documentation](https://developers.google.com/identity/protocols/oauth2).
@@ -95,7 +95,7 @@ Register these redirect values with your OAuth provider as they are presented in
 
 6. Click **Save Configuration**.
 
-   Your passwords, API key, and OAuth credentials, if provided, are stored in the [OpenRAG `.env` file](/reference/configuration) in your OpenRAG installation directory.
+   Your passwords, API key, and OAuth credentials, if provided, are stored in the [OpenRAG `.env` file](/reference/configuration) at `~/.openrag/tui`.
    If you modified any credentials that were pulled from an existing `.env` file, those values are updated in the `.env` file.
 
 7. Click **Start All Services** to start the OpenRAG services that run in containers.
diff --git a/docs/docs/core-components/agents.mdx b/docs/docs/core-components/agents.mdx
index d242552d..32387a59 100644
--- a/docs/docs/core-components/agents.mdx
+++ b/docs/docs/core-components/agents.mdx
@@ -32,7 +32,7 @@ For example, to view and edit the built-in **Chat** flow (the **OpenRAG OpenSear
 
    If prompted to acknowledge that you are entering Langflow, click **Proceed**.
 
-   If Langflow requests login information, enter the `LANGFLOW_SUPERUSER` and `LANGFLOW_SUPERUSER_PASSWORD` from your [OpenRAG `.env` file](/reference/configuration) in your OpenRAG installation directory.
+   If Langflow requests login information, enter the `LANGFLOW_SUPERUSER` and `LANGFLOW_SUPERUSER_PASSWORD` from your [OpenRAG `.env` file](/reference/configuration).
 
    ![OpenRAG OpenSearch Agent flow](/img/opensearch-agent-flow.png)
 
@@ -59,6 +59,12 @@ In addition to OpenRAG's built-in flows, all Langflow features are available thr
 
 Explore the [Langflow documentation](https://docs.langflow.org/) to learn more about the Langflow platform, features, and visual editor.
 
+## Modify a flow at runtime {#modify-a-flow-at-runtime}
+
+You can use _tweaks_ to modify flow settings at runtime without permanently changing the flow's configuration.
+Tweaks are one-time parameter modifications that are passed to specific Langflow components during flow execution.
+For more information on tweaks, see the Langflow documentation on [Input schema (tweaks)](https://docs.langflow.org/concepts-publish#input-schema).
+
 ## Set the Langflow version
 
 By default, OpenRAG is pinned to the latest Langflow Docker image for stability.
diff --git a/docs/docs/core-components/ingestion.mdx b/docs/docs/core-components/ingestion.mdx
index 7a69e3dd..f584405e 100644
--- a/docs/docs/core-components/ingestion.mdx
+++ b/docs/docs/core-components/ingestion.mdx
@@ -32,7 +32,7 @@ You can upload files and folders from your local machine to your knowledge base:
 
 3. To upload one file, click <Icon name="File" aria-hidden="true"/> **File**. To upload all documents in a folder, click <Icon name="Folder" aria-hidden="true"/> **Folder**.
 
-   The default path is the `./documents` subdirectory in your OpenRAG installation directory.
+   The default path is `~/.openrag/documents`.
    To change this path, see [Set the local documents path](/knowledge#set-the-local-documents-path).
 
 The selected files are processed in the background through the **OpenSearch Ingestion** flow.
diff --git a/docs/docs/core-components/knowledge.mdx b/docs/docs/core-components/knowledge.mdx
index 31c6d8a1..f4b80e1b 100644
--- a/docs/docs/core-components/knowledge.mdx
+++ b/docs/docs/core-components/knowledge.mdx
@@ -137,15 +137,17 @@ The default value is 200 characters, which represents an overlap of 20 percent i
 
 ### Set the local documents path {#set-the-local-documents-path}
 
-The default path for local uploads is the `./openrag-documents` subdirectory in your OpenRAG installation directory. This is mounted to the `/app/openrag-documents/` directory inside the OpenRAG container. Files added to the host or container directory are visible in both locations.
+The default path for local uploads is `~/.openrag/documents`. This is mounted to the `/app/openrag-documents/` directory inside the OpenRAG container. Files added to the host or container directory are visible in both locations.
 
 To change this location, modify the **Documents Paths** variable in either the [**Advanced Setup** menu](/install#setup) or in your [OpenRAG `.env` file](/reference/configuration).
 
 ## Delete knowledge {#delete-knowledge}
 
-To clear your entire knowledge base, delete the contents of the `./opensearch-data` folder in your OpenRAG installation directory.
+To clear your entire knowledge base, delete the contents of `~/.openrag/data`.
 This is a destructive operation that cannot be undone.
 
+It is recommended to do this by [resetting containers](/manage-services#reset-containers) or [reinstalling OpenRAG](/reinstall).
+
 ## See also
 
 * [Ingest knowledge](/ingestion)
diff --git a/docs/docs/get-started/install-options.mdx b/docs/docs/get-started/install-options.mdx
index 90f800a5..eac24d46 100644
--- a/docs/docs/get-started/install-options.mdx
+++ b/docs/docs/get-started/install-options.mdx
@@ -27,8 +27,8 @@ This is required for all installation methods because it prepares the minimum re
 For TUI-managed services, you must also complete initial setup before you start the OpenRAG services.
 For more information, see the instructions for your preferred installation method.
 
-Your OpenRAG configuration is stored in a `.env` file in the OpenRAG installation directory.
-When using TUI-managed services, this file is created automatically, or you can provide a pre-populated `.env` file before starting the TUI.
+Your OpenRAG configuration is stored in a `.env` file.
+When using TUI-managed services, this file is created automatically at `~/.openrag/tui`, or you can provide a pre-populated `.env` file in this directory before starting the TUI.
 The TUI prompts you for the required values during setup and onboarding, and any values detected in a preexisting `.env` file are populated automatically.
 When using self-managed services, you must provide a pre-populated `.env` file, as you would for any Docker or Podman deployment.
 For more information, see the instructions for your preferred installation method and the [OpenRAG environment variables reference](/reference/configuration).
\ No newline at end of file
diff --git a/docs/docs/get-started/install-uv.mdx b/docs/docs/get-started/install-uv.mdx
index 9a73546e..bbd7f44c 100644
--- a/docs/docs/get-started/install-uv.mdx
+++ b/docs/docs/get-started/install-uv.mdx
@@ -80,7 +80,7 @@ If you encounter errors during installation, see [Troubleshoot OpenRAG](/support
 
    For more options, see [Managing dependencies with `uv`](https://docs.astral.sh/uv/concepts/projects/dependencies/).
 
-4. Optional: If you want to use a pre-populated [OpenRAG `.env` file](/reference/configuration), copy it to this directory before starting OpenRAG.
+4. Optional: If you want to use a pre-populated [OpenRAG `.env` file](/reference/configuration), create one at `~/.openrag/tui` before starting OpenRAG.
 
 5. Start the OpenRAG TUI:
 
@@ -98,7 +98,7 @@ If you encounter errors during installation, see [Troubleshoot OpenRAG](/support
    uv pip install openrag
    ```
 
-3. Optional: If you want to use a pre-populated [OpenRAG `.env` file](/reference/configuration), copy it to this directory before starting OpenRAG.
+3. Optional: If you want to use a pre-populated [OpenRAG `.env` file](/reference/configuration), create one at `~/.openrag/tui` before starting OpenRAG.
 
 4. Start the OpenRAG TUI:
 
@@ -111,7 +111,7 @@ If you encounter errors during installation, see [Troubleshoot OpenRAG](/support
 When you install OpenRAG with `uv`, you manage the OpenRAG services with the TUI.
 The TUI guides you through the initial configuration process before you start the OpenRAG services.
 
-Your configuration values are stored in an [OpenRAG `.env` file](/reference/configuration) that is created automatically in the Python project where you installed OpenRAG.
+Your configuration values are stored in an [OpenRAG `.env` file](/reference/configuration) that is created automatically at `~/.openrag/tui`.
 If OpenRAG detects an existing `.env` file in this directory, then the TUI can populate those values automatically during setup and onboarding.
 
 Container definitions are stored in the `docker-compose` files in the same directory as the OpenRAG `.env` file.
diff --git a/docs/docs/get-started/install-uvx.mdx b/docs/docs/get-started/install-uvx.mdx
index a165191f..4c565f65 100644
--- a/docs/docs/get-started/install-uvx.mdx
+++ b/docs/docs/get-started/install-uvx.mdx
@@ -44,7 +44,7 @@ For other installation methods, see [Select an installation method](/install-opt
    cd openrag-workspace
    ```
 
-2. Optional: If you want to use a pre-populated [OpenRAG `.env` file](/reference/configuration), copy it to this directory before invoking OpenRAG.
+2. Optional: If you want to use a pre-populated [OpenRAG `.env` file](/reference/configuration), create one at `~/.openrag/tui` before invoking OpenRAG.
 
 3. Invoke OpenRAG:
 
@@ -70,7 +70,7 @@ If you encounter errors during installation, see [Troubleshoot OpenRAG](/support
 When you install OpenRAG with `uvx`, you manage the OpenRAG services with the TUI.
 The TUI guides you through the initial configuration process before you start the OpenRAG services.
 
-Your configuration values are stored in an [OpenRAG `.env` file](/reference/configuration) that is created automatically in the OpenRAG installation directory, which is the directory where you invoked OpenRAG.
+Your configuration values are stored in an [OpenRAG `.env` file](/reference/configuration) that is created automatically at `~/.openrag/tui`.
 If OpenRAG detects an existing `.env` file in this directory, then the TUI can populate those values automatically during setup and onboarding.
 
 Container definitions are stored in the `docker-compose` files in the same directory as the OpenRAG `.env` file.
diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx
index d044e48e..b1091905 100644
--- a/docs/docs/get-started/install.mdx
+++ b/docs/docs/get-started/install.mdx
@@ -69,7 +69,7 @@ If you encounter errors during installation, see [Troubleshoot OpenRAG](/support
 When you install OpenRAG with the installer script, you manage the OpenRAG services with the TUI.
 The TUI guides you through the initial configuration process before you start the OpenRAG services.
 
-Your configuration values are stored in an [OpenRAG `.env` file](/reference/configuration) that is created automatically in the OpenRAG installation directory, which is the directory where you ran the installer script.
+Your configuration values are stored in an [OpenRAG `.env` file](/reference/configuration) that is created automatically at `~/.openrag/tui`.
 If OpenRAG detects an existing `.env` file in this directory, then the TUI can populate those values automatically during setup and onboarding.
 
 Container definitions are stored in the `docker-compose` files in the same directory as the OpenRAG `.env` file.
diff --git a/docs/docs/get-started/manage-services.mdx b/docs/docs/get-started/manage-services.mdx
index 4ba0cc1d..4cd62875 100644
--- a/docs/docs/get-started/manage-services.mdx
+++ b/docs/docs/get-started/manage-services.mdx
@@ -142,7 +142,7 @@ This command destroys and recreates the containers. Data stored exclusively on t
 
 If you want to preserve customized flows, see [Export customized flows before resetting containers](#export-customized-flows-before-resetting-containers).
 
-The `.env` file, `config` directory, `./openrag-documents` directory, `./opensearch-data` directory, and the `conversations.json` file are preserved.
+The `.env` file and the `~/.openrag/documents` directory are preserved.
 
 ```bash title="Docker"
 docker compose up --build --force-recreate --remove-orphans
@@ -165,13 +165,7 @@ Destroyed containers and deleted data are lost and cannot be recovered after run
 
    <PartialDockerComposeDownAndPrune />
 
-2. Optional: Remove data that wasn't deleted by the previous commands:
-
-   * OpenRAG's `.env` file
-   * The contents of OpenRAG's `config` directory
-   * The contents of the `./openrag-documents` directory
-   * The contents of the `./opensearch-data` directory
-   * The `conversations.json` file
+2. Optional: Remove OpenRAG's `.env` file and the `~/.openrag` directory, which aren't deleted by the previous commands.
 
 3. If you deleted the `.env` file, prepare a new `.env` before redeploying the containers.
 For more information, see [Deploy OpenRAG with self-managed services](/docker).
diff --git a/docs/docs/get-started/quickstart.mdx b/docs/docs/get-started/quickstart.mdx
index fee479a2..0c062fee 100644
--- a/docs/docs/get-started/quickstart.mdx
+++ b/docs/docs/get-started/quickstart.mdx
@@ -64,7 +64,7 @@ The script installs OpenRAG dependencies, including Docker or Podman, and then i
    Command completed successfully
    ```
 
-   Your OpenRAG configuration and passwords are stored in an [OpenRAG `.env` file](/reference/configuration) file that is created automatically in your OpenRAG installation directory, which is the directory where you ran the installer script.
+   Your OpenRAG configuration and passwords are stored in an [OpenRAG `.env` file](/reference/configuration) file that is created automatically at `~/.openrag/tui`.
    Container definitions are stored in the `docker-compose` files in the same directory.
 
 7. Under [**Native Services**](/manage-services), click **Start** to start the Docling service.
@@ -96,7 +96,7 @@ You can click a document to view the chunks of the document as they are stored i
 
    For this quickstart, use either the <Icon name="File" aria-hidden="true"/> **File** or <Icon name="Folder" aria-hidden="true"/> **Folder** upload options to load documents from your local machine.
    **Folder** uploads an entire directory.
-   The default directory is the `/openrag-documents` subdirectory in your OpenRAG installation directory.
+   The default directory is `~/.openrag/documents`.
 
    For information about the cloud storage provider options, see [Ingest files with OAuth connectors](/ingestion#oauth-ingestion).
 
@@ -121,7 +121,7 @@ You can click a document to view the chunks of the document as they are stored i
 
 2. For greater insight into the underlying [Langflow flow](/agents) that drives the OpenRAG chat, click **Edit in Langflow** and then click **Proceed** to launch the Langflow visual editor in a new browser window.
 
-   If Langflow requests login information, enter the `LANGFLOW_SUPERUSER` and `LANGFLOW_SUPERUSER_PASSWORD` from the `.env` file in your OpenRAG installation directory.
+   If Langflow requests login information, enter the `LANGFLOW_SUPERUSER` and `LANGFLOW_SUPERUSER_PASSWORD` from the `.env` file at `~/.openrag/tui`.
 
    The **OpenRAG OpenSearch Agent** flow opens in a new browser window.
 
diff --git a/docs/docs/get-started/reinstall.mdx b/docs/docs/get-started/reinstall.mdx
index d120f7cd..4eb42223 100644
--- a/docs/docs/get-started/reinstall.mdx
+++ b/docs/docs/get-started/reinstall.mdx
@@ -31,8 +31,8 @@ If you modified the built-in flows or created custom flows in your OpenRAG Langf
 3. Optional: Remove data that wasn't deleted by the **Factory Reset** operation.
 For a completely fresh installation, delete all of this data.
 
-   * **OpenRAG's `.env` file**: Contains your OpenRAG configuration, including OpenRAG passwords, API keys, OAuth settings, and other [environment variables](/reference/configuration). If you delete this file, OpenRAG automatically generates a new one after you repeat the setup and onboarding process. Alternatively, you can add a prepopulated `.env` file to your OpenRAG installation directory before restarting OpenRAG.
-   * **The contents of the `./openrag-documents` directory**: Contains documents that you uploaded to OpenRAG. Delete these files to prevent documents from being reingested to your knowledge base after restarting OpenRAG. However, you might want to preserve OpenRAG's [default documents](https://github.com/langflow-ai/openrag/tree/main/openrag-documents).
+   * **OpenRAG's `.env` file**: Contains your OpenRAG configuration, including OpenRAG passwords, API keys, OAuth settings, and other [environment variables](/reference/configuration). If you delete this file, OpenRAG automatically generates a new one at `~/.openrag/tui` after you repeat the setup and onboarding process. Alternatively, you can create a prepopulated `.env` file in the expected directory before restarting OpenRAG.
+   * **The `~/.openrag` directory**: The `documents` subdirectory contains documents that you uploaded to OpenRAG. Delete these files to prevent documents from being reingested to your knowledge base after restarting OpenRAG. However, you might want to preserve OpenRAG's [default documents](https://github.com/langflow-ai/openrag/tree/main/openrag-documents).
 
 4. Restart the TUI with `uv run openrag` or `uvx openrag`.
 
@@ -49,13 +49,7 @@ Use these steps to reinstall OpenRAG containers with streamlined `docker compose
 
    <PartialDockerComposeDownAndPrune />
 
-2. Optional: Remove data that wasn't deleted by the previous commands:
-
-   * OpenRAG's `.env` file
-   * The contents of OpenRAG's `config` directory
-   * The contents of the `./openrag-documents` directory
-   * The contents of the `./opensearch-data` directory
-   * The `conversations.json` file
+2. Optional: Remove OpenRAG's `.env` file and the `~/.openrag` directory, which aren't deleted by the previous commands.
 
 3. If you deleted the `.env` file, prepare a new `.env` before redeploying the containers.
 For more information, see [Deploy OpenRAG with self-managed services](/docker).
@@ -78,13 +72,7 @@ If you want to reinstall one container, specify the container name in the comman
 
 <PartialDockerRemoveAndCleanupSteps />
 
-7. Optional: Remove data that wasn't deleted by the previous commands:
-
-   * OpenRAG's `.env` file
-   * The contents of OpenRAG's `config` directory
-   * The contents of the `./openrag-documents` directory
-   * The contents of the `./opensearch-data` directory
-   * The `conversations.json` file
+7. Optional: Remove OpenRAG's `.env` file and the `~/.openrag` directory, which aren't deleted by the previous commands.
 
 8. If you removed all OpenRAG containers, [redeploy OpenRAG](/docker).
 If you removed only one container, redeploy that container with the appropriate `docker run` or `podman run` command.
\ No newline at end of file
diff --git a/docs/docs/get-started/tui.mdx b/docs/docs/get-started/tui.mdx
index 0965478b..619543e3 100644
--- a/docs/docs/get-started/tui.mdx
+++ b/docs/docs/get-started/tui.mdx
@@ -10,7 +10,7 @@ The OpenRAG Terminal User Interface (TUI) provides a simplified and guided exper
 If you install OpenRAG with the [automatic installer script](/install), [`uv`](/install-uv), or [`uvx`](/install-uvx), you use the TUI to manage your OpenRAG deployment.
 The TUI guides you through the initial setup, automatically manages your OpenRAG `.env` and `docker-compose` files, and provides convenient access to [service management](/manage-services) controls.
 
-In contrast, when you [deploy OpenRAG with self-managed services](/docker), you must manually configure OpenRAG by preparing a `.env` file and using Docker or Podman commands to deploy and manage your OpenRAG services.
+In contrast, when you [deploy OpenRAG with self-managed services](/docker), you must manually configure OpenRAG by preparing a `.env` file, and then use Docker or Podman commands to deploy and manage your OpenRAG services.
 
 ## Access the TUI {#access-the-tui}
 
diff --git a/docs/docs/get-started/uninstall.mdx b/docs/docs/get-started/uninstall.mdx
index 3ffd3670..b1fa390c 100644
--- a/docs/docs/get-started/uninstall.mdx
+++ b/docs/docs/get-started/uninstall.mdx
@@ -29,13 +29,7 @@ Use these steps to uninstall a self-managed OpenRAG deployment with streamlined
 
    <PartialDockerComposeDownAndPrune />
 
-2. Remove data that wasn't deleted by the previous commands:
-
-   * OpenRAG's `.env` file
-   * The contents of OpenRAG's `config` directory
-   * The contents of the `./openrag-documents` directory
-   * The contents of the `./opensearch-data` directory
-   * The `conversations.json` file
+2. Remove OpenRAG's `.env` file and the `~/.openrag` directory, which aren't deleted by the previous commands.
 
 3. Stop `docling-serve`:
 
@@ -53,13 +47,7 @@ Use these commands to uninstall a self-managed OpenRAG deployment with discrete
 
 <PartialDockerRemoveAndCleanupSteps />
 
-7. Remove data that wasn't deleted by the previous commands:
-
-   * OpenRAG's `.env` file
-   * The contents of OpenRAG's `config` directory
-   * The contents of the `./openrag-documents` directory
-   * The contents of the `./opensearch-data` directory
-   * The `conversations.json` file
+7. Remove OpenRAG's `.env` file and the `~/.openrag` directory, which aren't deleted by the previous commands.
 
 8. Stop `docling-serve`:
 
diff --git a/docs/docs/get-started/upgrade.mdx b/docs/docs/get-started/upgrade.mdx
index 22808116..e2874db3 100644
--- a/docs/docs/get-started/upgrade.mdx
+++ b/docs/docs/get-started/upgrade.mdx
@@ -114,7 +114,7 @@ The commands to upgrade the package depend on how you installed OpenRAG.
    When you start services after upgrading the Python package, OpenRAG runs `docker compose pull` to get the appropriate container images matching the version specified in your OpenRAG `.env` file. Then, it recreates the containers with the new images using `docker compose up -d --force-recreate`.
 
    :::tip Pin container versions
-   In the `.env` file, the `OPENRAG_VERSION` [environment variable](/reference/configuration#system-settings) is set to `latest` by default, which pulls the `latest` available container images.
+   In the OpenRAG `.env` file, the `OPENRAG_VERSION` [environment variable](/reference/configuration#system-settings) is set to `latest` by default, which pulls the `latest` available container images.
    To pin a specific container image version, you can set `OPENRAG_VERSION` to the desired container image version, such as `OPENRAG_VERSION=0.1.33`.
 
    However, when you upgrade the Python package, OpenRAG automatically attempts to keep the `OPENRAG_VERSION` synchronized with the Python package version.
diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx
index 9a36ebaa..444bab0d 100644
--- a/docs/docs/reference/configuration.mdx
+++ b/docs/docs/reference/configuration.mdx
@@ -5,62 +5,40 @@ slug: /reference/configuration
 
 import PartialDockerComposeUp from '@site/docs/_partial-docker-compose-up.mdx';
 
-OpenRAG recognizes environment variables from the following sources:
+OpenRAG's `.env` file is the primary configuration file for OpenRAG.
+Environment variables in `.env` always take precedence over other sources.
 
-* [Environment variables](#configure-environment-variables): Values set in the `.env` file in the OpenRAG installation directory.
-* [Langflow runtime overrides](#langflow-runtime-overrides): Langflow components can set environment variables at runtime.
-* [Default or fallback values](#default-values-and-fallbacks): These values are default or fallback values if OpenRAG doesn't find a value.
+For deployments managed with the Terminal User Interface (TUI), this file is located at `~/.openrag/tui`, and it can be created automatically during [installation](/install-options).
 
-## Configure environment variables
+For [self-managed deployments](/docker), this file can be located at the root of your OpenRAG project directory or referenced from another location.
 
-Environment variables are set in a `.env` file in the root of your OpenRAG project directory.
+For an example, see [`.env.example` in the OpenRAG repository](https://github.com/langflow-ai/openrag/blob/main/.env.example).
 
-For an example `.env` file, see [`.env.example` in the OpenRAG repository](https://github.com/langflow-ai/openrag/blob/main/.env.example).
+:::tip
+OpenRAG's Docker Compose files are populated automatically using values from the `.env` file, so you don't need to edit the Docker Compose files manually.
+:::
 
-The Docker Compose files are populated with values from your `.env`, so you don't need to edit the Docker Compose files manually.
+If a variable isn't set, OpenRAG uses default or fallback values where available.
+Not all variables have default values, and errors can occur if required variables aren't set.
+Default values can be found in the reference tables on this page and in [`config_manager.py`](https://github.com/langflow-ai/openrag/blob/main/src/config/config_manager.py), [`settings.py`](https://github.com/langflow-ai/openrag/blob/main/src/config/settings.py), and [`logging_config.py`](https://github.com/langflow-ai/openrag/blob/main/src/utils/logging_config.py).
 
-Environment variables always take precedence over other variables.
+You can [temporarily set Langflow variables at runtime](#modify-a-flow-at-runtime).
+However, these temporary overrides don't overlap with most OpenRAG environment variables.
+The only exceptions are flow-level Langflow settings, such as the language model used in a flow.
 
-### Set environment variables {#set-environment-variables}
+## Edit the `.env` file {#set-environment-variables}
 
-Environment variables are either mutable or immutable.
+During [installation](/install-options), an initial `.env` file is created automatically or manually.
+You can edit this file to change OpenRAG configuration settings after installation.
 
-If you edit mutable environment variables, you can apply the changes by stopping and restarting the OpenRAG services after editing the `.env` file:
+Each OpenRAG environment variable is either mutable or immutable.
+This determines the actions you must take to apply changes after editing the `.env` file:
 
-1. [Stop the OpenRAG services](/manage-services).
+* **Mutable environment variables**: You can apply changes to mutable environment variables by [stopping and restarting the OpenRAG services](/manage-services) after editing the `.env` file.
 
-2. Edit your `.env` file.
+* **Immutable environment variables**: You must [redeploy OpenRAG](/reinstall) with your modified `.env` file if you change immutable environment variables.
 
-3. [Restart the OpenRAG services](/manage-services).
-
-If you edit immutable environment variables, you must [redeploy OpenRAG](/reinstall) with your modified `.env` file.
-For example, with self-managed services, do the following:
-
-1. Stop the deployment:
-
-   ```bash title="Docker"
-   docker compose down
-   ```
-
-   ```bash title="Podman"
-   podman compose down
-   ```
-
-2. Edit your `.env` file.
-
-3. Redeploy OpenRAG:
-
-   <PartialDockerComposeUp />
-
-4. Restart the Docling service.
-
-5. Launch the OpenRAG app, and then repeat the [application onboarding process](/install#application-onboarding). The values in your `.env` file are automatically populated.
-
-## Supported environment variables
-
-All OpenRAG configuration can be controlled through environment variables.
-
-### Model provider settings {#model-provider-settings}
+## Model provider settings {#model-provider-settings}
 
 Configure which models and providers OpenRAG uses to generate text and embeddings.
 You only need to provide credentials for the providers you are using in OpenRAG.
@@ -80,7 +58,7 @@ Some of these variables are immutable and can only be changed by redeploying Ope
 | `WATSONX_ENDPOINT` | Not set | Custom provider endpoint for the IBM watsonx.ai model provider. |
 | `WATSONX_PROJECT_ID` | Not set | Project ID for the IBM watsonx.ai model provider. |
 
-### Document processing settings {#document-processing-settings}
+## Document processing settings {#document-processing-settings}
 
 Control how OpenRAG [processes and ingests documents](/ingestion) into your knowledge base.
 
@@ -91,10 +69,10 @@ Control how OpenRAG [processes and ingests documents](/ingestion) into your know
 | `DISABLE_INGEST_WITH_LANGFLOW` | `false` | Disable Langflow ingestion pipeline. |
 | `DOCLING_OCR_ENGINE` | Set by OS | OCR engine for document processing. For macOS, `ocrmac`. For any other OS, `easyocr`. |
 | `OCR_ENABLED` | `false` | Enable OCR for image processing. |
-| `OPENRAG_DOCUMENTS_PATHS` | `./openrag-documents` | Document paths for ingestion. |
+| `OPENRAG_DOCUMENTS_PATHS` | `~/.openrag/documents` | Document paths for ingestion. |
 | `PICTURE_DESCRIPTIONS_ENABLED` | `false` | Enable picture descriptions. |
 
-### Langflow settings {#langflow-settings}
+## Langflow settings {#langflow-settings}
 
 Configure the OpenRAG Langflow server's authentication, contact point, and built-in flow definitions.
 
@@ -120,7 +98,7 @@ For better security, it is recommended to set `LANGFLOW_SUPERUSER_PASSWORD` so t
 | `LANGFLOW_CHAT_FLOW_ID`, `LANGFLOW_INGEST_FLOW_ID`, `NUDGES_FLOW_ID` | Built-in flow IDs | These variables are set automatically to the IDs of the chat, ingestion, and nudges [flows](/agents). The default values are found in [`.env.example`](https://github.com/langflow-ai/openrag/blob/main/.env.example). Only change these values if you want to replace a built-in flow with your own custom flow. The flow JSON must be present in your version of the OpenRAG codebase. For example, if you [deploy self-managed services](/docker), you can add the flow JSON to your local clone of the OpenRAG repository before deploying OpenRAG. |
 | `SYSTEM_PROMPT` | `You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context.` | System prompt instructions for the agent driving the **Chat** flow. |
 
-### OAuth provider settings
+## OAuth provider settings
 
 Configure [OAuth providers](/ingestion#oauth-ingestion) and external service integrations.
 
@@ -131,7 +109,7 @@ Configure [OAuth providers](/ingestion#oauth-ingestion) and external service int
 | `MICROSOFT_GRAPH_OAUTH_CLIENT_ID`<br/>`MICROSOFT_GRAPH_OAUTH_CLIENT_SECRET` | Not set | Enable the [Microsoft Graph OAuth client](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/graph-oauth) integration by providing [Azure application registration credentials for SharePoint and OneDrive](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/app-registration?view=odsp-graph-online). |
 | `WEBHOOK_BASE_URL` | Not set | Base URL for OAuth connector webhook endpoints. If this variable isn't set, a default base URL is used. |
 
-### OpenSearch settings
+## OpenSearch settings
 
 Configure OpenSearch database authentication.
 
@@ -142,7 +120,7 @@ Configure OpenSearch database authentication.
 | `OPENSEARCH_USERNAME` | `admin` | OpenSearch administrator username. |
 | `OPENSEARCH_PASSWORD` | Must be set at start up | Required. OpenSearch administrator password. Must adhere to the [OpenSearch password complexity requirements](https://docs.opensearch.org/latest/security/configuration/demo-configuration/#setting-up-a-custom-admin-password). You must set this directly in the `.env` or in the TUI's [**Basic/Advanced Setup**](/install#setup). |
 
-### System settings
+## System settings
 
 Configure general system components, session management, and logging.
 
@@ -156,23 +134,4 @@ Configure general system components, session management, and logging.
 | `MAX_WORKERS` | `1` | Maximum number of workers for document processing. |
 | `OPENRAG_VERSION` | `latest` | The version of the OpenRAG Docker images to run. For more information, see [Upgrade OpenRAG](/upgrade) |
 | `SERVICE_NAME` | `openrag` | Service name for logging. |
-| `SESSION_SECRET` | Automatically generated | Session management. |
-
-## Langflow runtime overrides
-
-You can modify [flow](/agents) settings at runtime without permanently changing the flow's configuration.
-
-Runtime overrides are implemented through _tweaks_, which are one-time parameter modifications that are passed to specific Langflow components during flow execution.
-
-For more information on tweaks, see the Langflow documentation on [Input schema (tweaks)](https://docs.langflow.org/concepts-publish#input-schema).
-
-## Default values and fallbacks
-
-If a variable isn't set by environment variables or a configuration file, OpenRAG can use a default value if one is defined in the codebase.
-Default values can be found in the OpenRAG repository:
-
-* OpenRAG configuration: [`config_manager.py`](https://github.com/langflow-ai/openrag/blob/main/src/config/config_manager.py)
-
-* System configuration: [`settings.py`](https://github.com/langflow-ai/openrag/blob/main/src/config/settings.py)
-
-* Logging configuration: [`logging_config.py`](https://github.com/langflow-ai/openrag/blob/main/src/utils/logging_config.py)
\ No newline at end of file
+| `SESSION_SECRET` | Automatically generated | Session management. |
\ No newline at end of file
diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx
index 958fa102..0bb7b141 100644
--- a/docs/docs/support/troubleshoot.mdx
+++ b/docs/docs/support/troubleshoot.mdx
@@ -68,7 +68,7 @@ This is likely due to a stale `uv` cache when you [install OpenRAG with `uvx`](/
 
 When you invoke OpenRAG with `uvx openrag`, `uvx` creates a cached, ephemeral environment that doesn't modify your project.
 The location and path of this cache depends on your operating system.
-For example, on macOS, this is typically a user cache directory, such as `/Users/USER_NAME/.cache/uv`.
+For example, on macOS, this is typically a user cache directory, such as `~/.cache/uv`.
 
 This cache can become stale, producing errors like missing dependencies.