Add basic documentation for persistent configuration (#3467)

README.md

@@ -199,6 +199,52 @@ of `distutils` (but not `sysconfig`)](https://ffy00.github.io/blog/02-python-deb
 While we always recommend the use of virtual environments, uv considers them to be required in
 these non-standard environments.
 
+### Persistent configuration
+
+uv supports persistent configuration at both the project- and user-level.
+
+Specifically, uv will search for a `pyproject.toml` or `uv.toml` file in the current directory, or
+in the nearest parent directory.
+
+If a `pyproject.toml` file is found, uv will read configuration from the `[tool.uv.pip]` table.
+For example, to set a persistent index URL, add the following to a `pyproject.toml`:
+
+```toml
+[tool.uv.pip]
+index-url = "https://test.pypi.org/simple"
+```
+
+(If there is no such table, the `pyproject.toml` file be ignored, and uv will continue searching in
+the directory hierarchy.)
+
+If a `uv.toml` file is found, uv will read from the `[pip]` table. For example:
+
+```toml
+[pip]
+index-url = "https://test.pypi.org/simple"
+```
+
+uv will also discover user-level configuration at `~/.config/uv/uv.toml` (or
+`$XDG_CONFIG_HOME/uv/uv.toml`) on macOS and Linux, or `%APPDATA%\uv\uv.toml` on Windows. User-level
+configuration must use the `uv.toml` format, rather than the `pyproject.toml` format, as a
+`pyproject.toml` is intended to define a Python _project_.
+
+If both project- and user-level configuration are found, the settings will be merged, with the
+project-level configuration taking precedence. Specifically, if a string, number, or boolean is
+present in both tables, the project-level value will be used, and the user-level value will be
+ignored. If an array is present in both tables, the arrays will be concatenated, with the
+project-level settings appearing later in the merged array.
+
+Settings provided via environment variables take precedence over persistent configuration, and
+settings provided via the command line take precedence over both.
+
+uv accepts a `--isolated` command-line argument which, when provided, disables the discovery of any
+persistent configuration.
+
+uv also accepts a `--config-file` command-line argument, which accepts a path to a `uv.toml` to use
+as the configuration file. When provided, this file will be used in place of _any_ discovered
+configuration files (e.g., user-level configuration will be ignored).
+
 ### Git authentication
 
 uv allows packages to be installed from Git and supports the following schemes for authenticating with private