From d31ca5412714d899253b740d6997a8920c1df35c Mon Sep 17 00:00:00 2001
From: April M <36110273+aimurphy@users.noreply.github.com>
Date: Thu, 18 Dec 2025 14:38:44 -0800
Subject: [PATCH] sme review

---
 docs/docs/_partial-export-flows.mdx          |  1 +
 docs/docs/_partial-factory-reset-warning.mdx | 10 ++--
 docs/docs/core-components/knowledge.mdx      |  5 +-
 docs/docs/get-started/manage-services.mdx    | 63 ++++++++------------
 docs/docs/get-started/reinstall.mdx          | 49 ++++++++-------
 docs/docs/get-started/uninstall.mdx          |  4 +-
 docs/docs/get-started/upgrade.mdx            | 38 +++++++-----
 7 files changed, 83 insertions(+), 87 deletions(-)
 create mode 100644 docs/docs/_partial-export-flows.mdx

diff --git a/docs/docs/_partial-export-flows.mdx b/docs/docs/_partial-export-flows.mdx
new file mode 100644
index 00000000..bbab64e6
--- /dev/null
+++ b/docs/docs/_partial-export-flows.mdx
@@ -0,0 +1 @@
+1. If you modified the built-in flows or created custom flows in your [OpenRAG Langflow instance](/agents), and you want to preserve those changes, then you must [export your flows](https://docs.langflow.org/concepts-flows-import) before starting this process. Afterwards, you can import your flows or reference the exported flow JSON as needed.
\ No newline at end of file
diff --git a/docs/docs/_partial-factory-reset-warning.mdx b/docs/docs/_partial-factory-reset-warning.mdx
index ab8cf85d..f0a2cb0f 100644
--- a/docs/docs/_partial-factory-reset-warning.mdx
+++ b/docs/docs/_partial-factory-reset-warning.mdx
@@ -1,13 +1,11 @@
 :::warning
-This is a destructive action that does the following:
+This is a destructive operation 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 `~/.openrag/config`, `~/.openrag/flows`, and `~/.openrag/data` directories, including the `conversations.json` file.
+* Destroys all OpenRAG containers, volumes, and local images.
+* Prunes any additional container objects.
+* Deletes the contents of the `~/.openrag` directory, except for OpenRAG's `.env` file and the `/documents` subdirectory.
 
 <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.
 :::
 
 <!--
diff --git a/docs/docs/core-components/knowledge.mdx b/docs/docs/core-components/knowledge.mdx
index f4b80e1b..c478a95a 100644
--- a/docs/docs/core-components/knowledge.mdx
+++ b/docs/docs/core-components/knowledge.mdx
@@ -143,10 +143,11 @@ To change this location, modify the **Documents Paths** variable in either the [
 
 ## Delete knowledge {#delete-knowledge}
 
-To clear your entire knowledge base, delete the contents of `~/.openrag/data`.
+:::warning
 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).
+To clear your entire knowledge base, [reset your OpenRAG containers](/manage-services#reset-containers) or [reinstall OpenRAG](/reinstall).
 
 ## See also
 
diff --git a/docs/docs/get-started/manage-services.mdx b/docs/docs/get-started/manage-services.mdx
index 4cd62875..d81beaee 100644
--- a/docs/docs/get-started/manage-services.mdx
+++ b/docs/docs/get-started/manage-services.mdx
@@ -8,6 +8,7 @@ import TabItem from '@theme/TabItem';
 import PartialDockerComposeUp from '@site/docs/_partial-docker-compose-up.mdx';
 import PartialDockerComposeDownAndPrune from '@site/docs/_partial-docker-compose-down-and-prune.mdx';
 import PartialFactorResetWarning from '@site/docs/_partial-factory-reset-warning.mdx';
+import PartialExportFlows from '@site/docs/_partial-export-flows.mdx';
 
 Service management is an essential part of maintaining your OpenRAG deployment.
 
@@ -120,61 +121,45 @@ See [Upgrade OpenRAG](/upgrade).
 
 ## Reset containers (destructive) {#reset-containers}
 
-Reset your OpenRAG deployment by recreating the containers and removing some related data.
-
-To completely reset your OpenRAG deployment and delete all OpenRAG data, see [Reinstall OpenRAG](/reinstall).
-
-### Export customized flows before resetting containers {#export-customized-flows-before-resetting-containers}
-
-If you modified the built-in flows or created custom flows in your OpenRAG Langflow instance, and you want to preserve those changes, [export your flows](https://docs.langflow.org/concepts-flows-import) before resetting your OpenRAG containers.
-
-### Factory Reset with the TUI
-
 <PartialFactorResetWarning />
 
-1. To destroy and recreate your OpenRAG containers, open the TUI's **Status** menu (<kbd>3</kbd>), and then click **Factory Reset**.
+Use these steps to reset your OpenRAG deployment by recreating the containers and deleting all data in the `~/.openrag` directory _except_ for the `.env` file and the `/documents` subdirectory.
 
-2. Repeat the [setup process](/install#setup) to restart the services and launch the OpenRAG app. Your OpenRAG passwords, OAuth credentials (if previously set), and onboarding configuration are restored from the `.env` file.
+This restores your OpenRAG deployment to a near-initial state while preserving your configuration (in `.env`) and uploaded documents (in `/documents`).
+Your documents are reingested into a fresh OpenSearch index after the reset.
 
-### Rebuild self-managed containers
+To reset your OpenRAG deployment _and_ delete all OpenRAG data, see [Reinstall OpenRAG](/reinstall).
 
-This command destroys and recreates the containers. Data stored exclusively on the containers is lost, such as Langflow flows.
+<Tabs>
+<TabItem value="TUI" label="TUI-managed services" default>
 
-If you want to preserve customized flows, see [Export customized flows before resetting containers](#export-customized-flows-before-resetting-containers).
+<PartialExportFlows />
 
-The `.env` file and the `~/.openrag/documents` directory are preserved.
+2. To destroy and recreate your OpenRAG containers, open the TUI's **Status** menu (<kbd>3</kbd>), and then click **Factory Reset**.
 
-```bash title="Docker"
-docker compose up --build --force-recreate --remove-orphans
-```
+3. Repeat the [setup process](/install#setup) to restart the services and launch the OpenRAG app. Your OpenRAG passwords, OAuth credentials (if previously set), and onboarding configuration are restored from the `.env` file.
 
-```bash title="Podman"
-podman compose up --build --force-recreate --remove-orphans
-```
+</TabItem>
+<TabItem value="env" label="Self-managed services">
 
-### Destroy and recreate self-managed containers
+<PartialExportFlows />
 
-Use separate commands to destroy and recreate the containers if you want to modify the configuration or delete other OpenRAG data before recreating the containers.
+2. Recreate the containers:
 
-:::warning
-These are destructive operations that reset your OpenRAG deployment to an initial state.
-Destroyed containers and deleted data are lost and cannot be recovered after running this operation.
-:::
+   ```bash title="Docker"
+   docker compose up --build --force-recreate --remove-orphans
+   ```
 
-1. Destroy the containers, volumes, and local images, and then remove (prune) any additional container objects:
+   ```bash title="Podman"
+   podman compose up --build --force-recreate --remove-orphans
+   ```
 
-   <PartialDockerComposeDownAndPrune />
+3. Launch the OpenRAG app, and then repeat the [application onboarding process](/docker#application-onboarding).
 
-2. Optional: Remove OpenRAG's `.env` file and the `~/.openrag` directory, which aren't deleted by the previous commands.
+4. If you exported customized flows, [import your flows](https://docs.langflow.org/concepts-flows-import) into Langflow after completing the onboarding process.
 
-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).
-
-4. Recreate the containers:
-
-   <PartialDockerComposeUp />
-
-5. Launch the OpenRAG app, and then repeat the [application onboarding process](/docker#application-onboarding).
+</TabItem>
+</Tabs>
 
 ## See also
 
diff --git a/docs/docs/get-started/reinstall.mdx b/docs/docs/get-started/reinstall.mdx
index 4eb42223..b0ff8d25 100644
--- a/docs/docs/get-started/reinstall.mdx
+++ b/docs/docs/get-started/reinstall.mdx
@@ -8,6 +8,7 @@ import PartialDockerComposeDownAndPrune from '@site/docs/_partial-docker-compose
 import PartialDockerStopAll from '@site/docs/_partial-docker-stop-all.mdx';
 import PartialDockerRemoveAndCleanupSteps from '@site/docs/_partial-docker-remove-and-cleanup-steps.mdx';
 import PartialFactorResetWarning from '@site/docs/_partial-factory-reset-warning.mdx';
+import PartialExportFlows from '@site/docs/_partial-export-flows.mdx';
 
 You can reset your OpenRAG deployment to its initial state by recreating the containers and deleting accessory data, such as the `.env` file and ingested documents.
 
@@ -16,49 +17,48 @@ These are destructive operations that reset your OpenRAG deployment to an initia
 Destroyed containers and deleted data are lost and cannot be recovered after running these operations.
 :::
 
-## Export customized flows before reinstalling
-
-If you modified the built-in flows or created custom flows in your OpenRAG Langflow instance, and you want to preserve those changes, [export your flows](https://docs.langflow.org/concepts-flows-import) before reinstalling OpenRAG.
-
 ## Reinstall TUI-managed containers
 
-1. In the TUI's **Status** menu (<kbd>3</kbd>), click **Factory Reset** to destroy your OpenRAG containers and some related data.
+<PartialExportFlows />
+
+2. In the TUI's **Status** menu (<kbd>3</kbd>), click **Factory Reset** to [reset your OpenRAG containers](/manage-services#reset-containers).
 
    <PartialFactorResetWarning />
 
 2. Exit the TUI with <kbd>q</kbd>.
 
-3. Optional: Remove data that wasn't deleted by the **Factory Reset** operation.
-For a completely fresh installation, delete all of this data.
+3. Optional: Delete or edit [OpenRAG's `.env` file](/reference/configuration), which is stored at `~/.openrag/tui`.
 
-   * **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).
+   This file contains your OpenRAG configuration, including OpenRAG passwords, API keys, OAuth settings, and other environment variables. If you delete this file, the TUI automatically generates a new one after you repeat the setup and onboarding process. If you preserve this file, the TUI can read values from the existing `.env` file during setup and onboarding.
 
-4. Restart the TUI with `uv run openrag` or `uvx openrag`.
+4. Optional: Remove any files from the `~/.openrag/documents` subdirectory that you don't want to reingest after redeploying the containers.
+It is recommended that you preserve OpenRAG's [default documents](https://github.com/langflow-ai/openrag/tree/main/openrag-documents).
 
-5. Repeat the [setup process](/install#setup) to configure OpenRAG and restart all services.
+5. Restart the TUI with `uv run openrag` or `uvx openrag`.
+
+6. Repeat the [setup process](/install#setup) to configure OpenRAG and restart all services.
 Then, launch the OpenRAG app and repeat the [application onboarding process](/install#application-onboarding).
 
-   If OpenRAG detects a `.env` file during setup and onboarding, it automatically populates any OpenRAG passwords, OAuth credentials, and onboarding configuration set in that file.
-
 ## Reinstall self-managed containers with `docker compose` or `podman compose`
 
 Use these steps to reinstall OpenRAG containers with streamlined `docker compose` or `podman compose` commands:
 
-1. Destroy the containers, volumes, and local images, and then remove (prune) any additional container objects:
+<PartialExportFlows />
+
+2. Destroy the containers, volumes, and local images, and then remove (prune) any additional container objects:
 
    <PartialDockerComposeDownAndPrune />
 
-2. Optional: Remove OpenRAG's `.env` file and the `~/.openrag` directory, which aren't deleted by the previous commands.
+3. Optional: Edit OpenRAG's `.env` file if needed.
 
-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).
+4. Optional: Remove any files from the `~/.openrag/documents` subdirectory that you don't want to reingest after redeploying the containers.
+It is recommended that you preserve OpenRAG's [default documents](https://github.com/langflow-ai/openrag/tree/main/openrag-documents).
 
-4. Redeploy OpenRAG:
+5. Redeploy OpenRAG:
 
    <PartialDockerComposeUp />
 
-5. Launch the OpenRAG app, and then repeat the [application onboarding process](/docker#application-onboarding).
+6. Launch the OpenRAG app, and then repeat the [application onboarding process](/docker#application-onboarding).
 
 ## Reinstall self-managed containers with discrete `docker` or `podman` commands
 
@@ -66,13 +66,18 @@ Use these commands to remove and clean up OpenRAG containers with discrete `dock
 
 If you want to reinstall one container, specify the container name in the commands instead of running the commands on all containers.
 
-1. Stop all running containers:
+<PartialExportFlows />
+
+2. Stop all running containers:
 
    <PartialDockerStopAll />
 
 <PartialDockerRemoveAndCleanupSteps />
 
-7. Optional: Remove OpenRAG's `.env` file and the `~/.openrag` directory, which aren't deleted by the previous commands.
+8. Optional: Edit OpenRAG's `.env` file if needed.
 
-8. If you removed all OpenRAG containers, [redeploy OpenRAG](/docker).
+9. Optional: If you removed all containers or specifically the OpenSearch container, then you can remove any files from the `~/.openrag/documents` subdirectory that you don't want to reingest after redeploying the containers.
+It is recommended that you preserve OpenRAG's [default documents](https://github.com/langflow-ai/openrag/tree/main/openrag-documents).
+
+10. 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/uninstall.mdx b/docs/docs/get-started/uninstall.mdx
index b1fa390c..a7865395 100644
--- a/docs/docs/get-started/uninstall.mdx
+++ b/docs/docs/get-started/uninstall.mdx
@@ -29,7 +29,7 @@ Use these steps to uninstall a self-managed OpenRAG deployment with streamlined
 
    <PartialDockerComposeDownAndPrune />
 
-2. Remove OpenRAG's `.env` file and the `~/.openrag` directory, which aren't deleted by the previous commands.
+2. Remove OpenRAG's `.env` file and the `~/.openrag/documents` directory, which aren't deleted by the previous commands.
 
 3. Stop `docling-serve`:
 
@@ -47,7 +47,7 @@ Use these commands to uninstall a self-managed OpenRAG deployment with discrete
 
 <PartialDockerRemoveAndCleanupSteps />
 
-7. Remove OpenRAG's `.env` file and the `~/.openrag` directory, which aren't deleted by the previous commands.
+7. Remove OpenRAG's `.env` file and the `~/.openrag/documents` 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 e2874db3..611c6f6b 100644
--- a/docs/docs/get-started/upgrade.mdx
+++ b/docs/docs/get-started/upgrade.mdx
@@ -5,6 +5,7 @@ slug: /upgrade
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import PartialExportFlows from '@site/docs/_partial-export-flows.mdx';
 
 Use these steps to upgrade your OpenRAG deployment to the latest version or a specific version.
 
@@ -21,12 +22,14 @@ Upgrading the Python package also upgrades Docling by bumping the dependency in
 
 This is a two-part process because upgrading the OpenRAG Python package updates the Terminal User Interface (TUI) and Python code, but the container versions are controlled by environment variables in your [OpenRAG `.env` file](/reference/configuration).
 
-1. To check for updates, open the TUI's **Status** menu (<kbd>3</kbd>), and then click **Upgrade**.
+<PartialExportFlows />
 
-2. If there is an update, stop all OpenRAG services.
+2. To check for updates, open the TUI's **Status** menu (<kbd>3</kbd>), and then click **Upgrade**.
+
+3. If there is an update, stop all OpenRAG services.
 In the **Status** menu, click **Stop Services**.
 
-3. Upgrade the OpenRAG Python package to the latest version from [PyPI](https://pypi.org/project/openrag/).
+4. Upgrade the OpenRAG Python package to the latest version from [PyPI](https://pypi.org/project/openrag/).
 The commands to upgrade the package depend on how you installed OpenRAG.
 
    <Tabs>
@@ -109,7 +112,7 @@ The commands to upgrade the package depend on how you installed OpenRAG.
    </TabItem>
    </Tabs>
 
-4. In the OpenRAG TUI, click **Start All Services**, and then wait while the upgraded containers start.
+5. In the OpenRAG TUI, click **Start All Services**, and then wait while the upgraded containers start.
 
    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`.
 
@@ -124,24 +127,27 @@ The commands to upgrade the package depend on how you installed OpenRAG.
 
    If you get an error that `langflow container already exists` error during upgrade, see [Langflow container already exists during upgrade](/support/troubleshoot#langflow-container-already-exists-during-upgrade).
 
-5. Under [**Native Services**](/manage-services), click **Start** to start the Docling service.
+6. Under [**Native Services**](/manage-services), click **Start** to start the Docling service.
 
-6. When the upgrade process is complete, you can close the **Status** window and continue using OpenRAG.
+7. When the upgrade process is complete, you can close the **Status** window and continue using OpenRAG.
 
 ## Upgrade self-managed containers
 
-To fetch and apply the latest container images while preserving your OpenRAG data, run the commands for your container management tool.
-By default, OpenRAG's `docker-compose` files pull the latest container images.
+<PartialExportFlows />
 
-```bash title="Docker"
-docker compose pull
-docker compose up -d --force-recreate
-```
+2. Fetch and apply the latest container images while preserving your OpenRAG data:
 
-```bash title="Podman"
-podman compose pull
-podman compose up -d --force-recreate
-```
+   ```bash title="Docker"
+   docker compose pull
+   docker compose up -d --force-recreate
+   ```
+
+   ```bash title="Podman"
+   podman compose pull
+   podman compose up -d --force-recreate
+   ```
+
+   By default, OpenRAG's `docker-compose` files pull the latest container images.
 
 ## See also