docs(configuration): Overhaul configuration

Author: tony

docs/configuration/index.md

@@ -7,30 +7,51 @@
 Repo type and address is [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986) style URLs.
 You may recognize this from `pip`'s [VCS URL] format.
 
-[VCS URL]: https://pip.pypa.io/en/latest/topics/vcs-support/
+[vcs url]: https://pip.pypa.io/en/latest/topics/vcs-support/
 
-(git-remote-ssh-git)=
+## Config locations
 
-## SSH Git URLs
+You can place the file in one of three places:
 
-For git remotes using SSH authorization such as `git+git@github.com:tony/kaptan.git` use `git+ssh`:
+1. Home: _~/.vcspull.yaml_
+2. [XDG] home directory: `$XDG_CONFIG_HOME/vcspull/`
 
-```console
-git+ssh://git@github.com/tony/kaptan.git
+   Example: _~/.config/vcspull/myrepos.yaml_
+
+   `XDG_CONFIG_HOME` is often _~/.config/vcspull/_, but can vary on platform, to check:
+
+   ```console
+   $ echo $XDG_CONFIG_HOME
+   ```
+
+3. Anywhere (and trigger via `vcspull sync -c ./path/to/file.yaml sync [repo_name]`)
+
+[xdg]: https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
+
+## Schema
+
+```{warning}
+
+This structure is subject to break in upcoming releases.
+```
+
+```yaml
+~/workdir/:
+  repo_name:
+    remotes:
+      origin: git_repo_url
 ```
 
-## Examples
+### Examples
 
 ````{tab} Simple
 
-_~/.vcspull.yaml_:
-
 ```{literalinclude} ../../examples/remotes.yaml
 :language: yaml
 
 ```
 
-Then type:
+To pull _kaptan_:
 
 ```console
 $ vcspull sync kaptan
@@ -55,7 +76,7 @@ config showing off every current feature and inline shortcut available.
 
 **Code scholar**
 
-This `.vcspull.yaml` is used to checkout and sync multiple open source
+This file is used to checkout and sync multiple open source
 configs.
 
 YAML:
@@ -73,3 +94,15 @@ YAML:
 
 generation
 ```
+
+## Caveats
+
+(git-remote-ssh-git)=
+
+### SSH Git URLs
+
+For git remotes using SSH authorization such as `git+git@github.com:tony/kaptan.git` use `git+ssh`:
+
+```console
+git+ssh://git@github.com/tony/kaptan.git
+```