Document flat layout mode in overview and repo-management docs

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: aclark4life

docs/features/repo-management.rst

@@ -248,6 +248,49 @@ Because ``mongo-python-driver`` ends up physically inside each group directory
 (e.g. ``pymongo/mongo-python-driver``), ``dbx install -g pymongo`` and
 ``dbx test mongo-python-driver`` all work without any extra flags.
 
+Flat Layout
+~~~~~~~~~~~
+
+By default dbx uses a two-level directory layout (``base_dir/<group>/<repo>``).
+Setting ``flat = true`` collapses this so all repositories live directly under
+``base_dir``:
+
+.. code-block:: toml
+
+   [repo]
+   base_dir = "~/Developer/mongodb"
+   flat = true
+
+   [repo.groups.pymongo]
+   repos = [
+       "git@github.com:mongodb/mongo-python-driver.git",
+       "git@github.com:mongodb/specifications.git",
+   ]
+
+   [repo.groups.django]
+   repos = [
+       "git@github.com:mongodb-labs/django-mongodb-backend.git",
+   ]
+
+Resulting layout:
+
+.. code-block:: text
+
+   ~/Developer/mongodb/
+   ├── mongo-python-driver/
+   ├── specifications/
+   └── django-mongodb-backend/
+
+In flat mode:
+
+- Group membership is resolved from the config rather than directory structure.
+- ``dbx list`` shows a tree grouped by config group (same visual style as
+  grouped mode).
+- ``dbx clone -g pymongo`` clones directly into ``base_dir`` instead of
+  ``base_dir/pymongo/``.
+- A single shared ``.venv`` is used across all groups.
+- All other commands (``-g``, install, test, etc.) continue to work normally.
+
 **Configuration:**
 
 Repository groups are defined in ``~/.config/dbx-python-cli/config.toml``. The default base directory for cloning is ``~/Developer/dbx-repos``, which can be customized.

docs/introduction/overview.rst

@@ -173,13 +173,46 @@ Typical directory structure after setup:
    │   └── another_project/
    ├── pymongo/                      # Group directory
    │   ├── .venv/                    # Group-level virtual environment
-   │   ├── mongo-python-driver/     # Cloned from global group
+   │   ├── mongo-python-driver/     # Repository
    │   ├── specifications/          # Repository
    │   └── drivers-evergreen-tools/ # Repository
    └── langchain/                    # Another group
        ├── .venv/                    # Separate venv for this group
-       ├── mongo-python-driver/     # Cloned from global group
-       └── langchain-mongodb/       # Repository
+       └── langchain-mongodb/        # Repository
+
+Flat Layout
+~~~~~~~~~~~
+
+Setting ``flat = true`` in ``[repo]`` switches to a flat layout where all repositories
+live directly under ``base_dir`` instead of in per-group subdirectories:
+
+.. code-block:: toml
+
+   [repo]
+   base_dir = "~/Developer/mongodb"
+   flat = true
+
+   [repo.groups.pymongo]
+   repos = [
+       "git@github.com:mongodb/mongo-python-driver.git",
+   ]
+
+   [repo.groups.django]
+   repos = [
+       "git@github.com:mongodb-labs/django-mongodb-backend.git",
+   ]
+
+.. code-block:: text
+
+   ~/Developer/mongodb/              # base_dir (also group root)
+   ├── .venv/                        # Shared venv across all groups
+   ├── mongo-python-driver/          # pymongo group repo
+   └── django-mongodb-backend/       # django group repo
+
+In flat mode ``dbx list`` still shows repos grouped by their config group in a
+tree view, and all group-aware commands (``-g``, install, test) continue to work
+normally — group membership is resolved from the config rather than the directory
+structure.
 
 Design Philosophy
 -----------------