docs: run configuration and migration commands in the backend environment (#6425)

* docs: run configuration and migration commands in the backend environment

* docs: preserve runtime paths and extras in backend commands

---------

Co-authored-by: Zhangchenhao-111 <285911435+Zhangchenhao-111@users.noreply.github.com>
Co-authored-by: Willem Jiang <willem.jiang@gmail.com>

README.md

@@ -517,6 +517,9 @@ for the commands for each mode.
 If you prefer running services locally:
 
 Prerequisite: complete the "Configuration" steps above first (`make setup`). `make dev` requires a valid `config.yaml` in the project root. Set `DEER_FLOW_PROJECT_ROOT` to define that root explicitly, or `DEER_FLOW_CONFIG_PATH` to point at a specific config file. Runtime state defaults to `.deer-flow` under the project root and can be moved with `DEER_FLOW_HOME`; skills default to `skills/` under the project root and can be moved with `DEER_FLOW_SKILLS_PATH`. Run `make doctor` to verify your setup before starting.
+
+Configuration checks and agent-storage migrations use the installed backend environment through `uv run --no-sync --project backend` from the repository root. This preserves relative runtime paths and installed optional dependencies; see the [setup checks](backend/docs/SETUP.md#steps) and [agent-storage migration](backend/docs/CONFIGURATION.md#agent-storage).
+
 On Windows, run the local development flow from Git Bash. Native `cmd.exe` and PowerShell shells are not supported for the bash-based service scripts, and WSL is not guaranteed because some scripts rely on Git for Windows utilities such as `cygpath`.
 
 The documented root `make` commands invoke repository `.sh` files through Bash

backend/AGENTS.md

@@ -188,6 +188,11 @@ watcher. Do not replace it with a bare `uvicorn --reload`: agent tasks write
 Python and other runtime files below `DEER_FLOW_HOME`, which would otherwise
 restart the Gateway during an active run.
 
+Configuration checks and operator migration scripts reuse the installed backend
+environment with `uv run --no-sync --project backend` from the repository root.
+`--project` preserves the caller's working directory and relative runtime/config
+selectors; `--no-sync` retains installed extras such as PostgreSQL drivers.
+
 More specific `AGENTS.md` files in backend code directories contain the subsystem sections split from this file. Follow the nearest file in the directory tree.
 
 ## Architecture

backend/docs/CONFIGURATION.md

@@ -601,9 +601,19 @@ agent_storage:
 
 Migrating an existing install from `file` to `db`:
 
+Run from the repository root using the backend's `uv` environment. The importer
+depends on the installed workspace packages; using a system `python` without
+an activated backend environment can fail with `ModuleNotFoundError: deerflow`.
+Complete the [backend installation](../../CONTRIBUTING.md#option-2-local-development)
+first, including the `postgres` extra when applicable. Use the same exported
+configuration and runtime selectors as the running Gateway, such as
+`DEER_FLOW_CONFIG_PATH` and `DEER_FLOW_HOME`. `--project backend` selects the
+environment without changing the working directory, so relative paths keep
+their meaning; `--no-sync` preserves installed extras.
+
 ```bash
-python backend/scripts/migrate_agents_to_db.py            # copy on-disk agents into the db
-python backend/scripts/migrate_agents_to_db.py --dry-run  # preview without writing
+uv run --no-sync --project backend python backend/scripts/migrate_agents_to_db.py --dry-run  # preview without writing
+uv run --no-sync --project backend python backend/scripts/migrate_agents_to_db.py            # copy on-disk agents into the db
 ```
 
 The importer is idempotent (already-present agents are skipped) and leaves the source files untouched, so reverting `agent_storage.backend` to `file` is a clean rollback. Agent *memory* (`memory.json`) is unaffected by this switch.

backend/docs/SETUP.md

@@ -30,10 +30,15 @@ DeerFlow uses a YAML configuration file that should be placed in the **project r
    vim config.yaml  # or your preferred editor
    ```
 
-4. **Verify configuration**:
+4. **Verify configuration in the backend environment**:
+   Complete the [local development installation](../../CONTRIBUTING.md#option-2-local-development),
+   including any extras required by your configuration (such as `postgres`).
+   Run from the repository root. `--project backend` selects the installed
+   backend environment while keeping relative configuration and runtime paths
+   anchored to this directory; `--no-sync` retains its installed extras.
+
    ```bash
-   cd backend
-   python -c "from deerflow.config import get_app_config; print('✓ Config loaded:', get_app_config().models[0].name)"
+   uv run --no-sync --project backend python -c "from deerflow.config import get_app_config; print('✓ Config loaded:', get_app_config().models[0].name)"
    ```
 
 ## Important Notes
@@ -77,8 +82,8 @@ If you skip this step, the image will be automatically pulled on first agent exe
 
 ```bash
 # Check where the backend is looking
-cd deer-flow/backend
-python -c "from deerflow.config.app_config import AppConfig; print(AppConfig.resolve_config_path())"
+cd /path/to/deer-flow
+uv run --no-sync --project backend python -c "from deerflow.config.app_config import AppConfig; print(AppConfig.resolve_config_path())"
 ```
 
 If it can't find the config:
@@ -89,7 +94,7 @@ If it can't find the config:
 ### Permission denied
 
 ```bash
-chmod 600 ../config.yaml  # Protect sensitive configuration
+chmod 600 config.yaml  # Run from the repository root
 ```
 
 ## See Also

backend/scripts/migrate_agents_to_db.py

@@ -15,9 +15,12 @@ Design (mirrors ``scripts/migrate_user_isolation.py``):
 - Non-destructive: the on-disk files are left untouched, so unsetting
   ``agent_storage.backend`` (back to ``file``) is a clean rollback.
 
-Usage::
+Usage (from the repository root)::
 
-    python scripts/migrate_agents_to_db.py [--dry-run]
+    uv run --no-sync --project backend python backend/scripts/migrate_agents_to_db.py [--dry-run]
+
+Use the installed backend environment and the Gateway's exported configuration
+and runtime selectors; relative paths remain anchored to the caller's directory.
 
 Requires ``database.backend`` to be ``sqlite`` or ``postgres`` in config.yaml.
 """

backend/scripts/migrate_user_isolation.py

@@ -1,7 +1,10 @@
 """One-time migration: move legacy thread dirs, memory, agents, skills, and the global USER.md profile into per-user layout.
 
-Usage:
-    PYTHONPATH=. python scripts/migrate_user_isolation.py [--dry-run] [--user-id USER_ID]
+Usage (from the repository root):
+    uv run --no-sync --project backend python backend/scripts/migrate_user_isolation.py [--dry-run] [--user-id USER_ID]
+
+Use the installed backend environment and the Gateway's exported runtime
+selectors; relative paths remain anchored to the caller's directory.
 
 The script is idempotent — re-running it after a successful migration is a no-op.
 """

config.example.yaml

@@ -2676,8 +2676,10 @@ run_events:
 #                   'sqlite' or 'postgres' (rejected at startup on 'memory').
 #
 # Switching an existing install to 'db'? Import the on-disk Custom Agents and
-# managed subagents once with:
-#     python backend/scripts/migrate_agents_to_db.py   # --dry-run to preview
+# managed subagents once from the repository root, with the installed backend
+# environment and the same runtime/configuration selectors as the Gateway:
+#     uv run --no-sync --project backend python backend/scripts/migrate_agents_to_db.py --dry-run
+# Remove --dry-run after reviewing the preview to perform the import.
 # The source files are left in place, so reverting to 'file' is a clean rollback.
 #
 # agent_storage:

deploy/helm/deer-flow/values.yaml

@@ -399,8 +399,10 @@ config: |
 
   # Custom agents and managed subagents default to per-Pod files under the
   # home volume. Switch to the shared database when running more than one
-  # replica (import existing files once with
-  # `python backend/scripts/migrate_agents_to_db.py`):
+  # replica. From the repository root, use the installed backend environment
+  # and the Gateway's runtime/configuration selectors to preview the import:
+  # `uv run --no-sync --project backend python backend/scripts/migrate_agents_to_db.py --dry-run`
+  # Remove --dry-run after reviewing the preview to perform the import:
   # agent_storage:
   #   backend: db