docs/cli(docs[fmt-import]): add usage docs for new commands

why: surface import and fmt workflows introduced alongside scanner support.

what:

- link new cli pages in command toctrees

- document manual import, --scan options, and fmt usage

- reference new commands from quickstart guidance

Author: tony

docs/api/cli/fmt.md

@@ -0,0 +1,8 @@
+# vcspull fmt - `vcspull.cli.fmt`
+
+```{eval-rst}
+.. automodule:: vcspull.cli.fmt
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/api/cli/import.md

@@ -0,0 +1,8 @@
+# vcspull import - `vcspull.cli._import`
+
+```{eval-rst}
+.. automodule:: vcspull.cli._import
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/api/cli/index.md

@@ -9,6 +9,8 @@
 :maxdepth: 1
 
 sync
+import
+fmt
 ```
 
 ## vcspull CLI - `vcspull.cli`

docs/cli/fmt.md

@@ -0,0 +1,67 @@
+(cli-fmt)=
+
+# vcspull fmt
+
+`vcspull fmt` normalizes configuration files so directory keys and repository
+entries stay consistent. By default the formatter prints the proposed changes to
+stdout. Apply the updates in place with `--write`.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: vcspull.cli
+    :func: create_parser
+    :prog: vcspull
+    :path: fmt
+    :nodescription:
+```
+
+## What gets formatted
+
+The formatter performs three main tasks:
+
+- Expands string-only entries into verbose dictionaries using the `repo` key.
+- Converts legacy `url` keys to `repo` for consistency with the rest of the
+  tooling.
+- Sorts directory keys and repository names alphabetically to minimize diffs.
+
+For example:
+
+```yaml
+~/code/:
+  libvcs: git+https://github.com/vcspull/libvcs.git
+  vcspull:
+    url: git+https://github.com/vcspull/vcspull.git
+```
+
+becomes:
+
+```yaml
+~/code/:
+  libvcs:
+    repo: git+https://github.com/vcspull/libvcs.git
+  vcspull:
+    repo: git+https://github.com/vcspull/vcspull.git
+```
+
+## Writing changes
+
+Run the formatter in dry-run mode first to preview the adjustments, then add
+`--write` (or `-w`) to persist them back to disk:
+
+```console
+$ vcspull fmt --config ~/.vcspull.yaml
+$ vcspull fmt --config ~/.vcspull.yaml --write
+```
+
+Use `--all` to iterate over the default search locations: the current working
+directory, `~/.vcspull.*`, and the XDG configuration directory. Each formatted
+file is reported individually.
+
+```console
+$ vcspull fmt --all --write
+```
+
+Pair the formatter with [`vcspull import`](cli-import) after scanning the file
+system to keep newly added repositories ordered and normalized.

docs/cli/import.md

@@ -0,0 +1,67 @@
+(cli-import)=
+
+# vcspull import
+
+The `vcspull import` command registers existing repositories with your vcspull
+configuration. You can either provide a single repository name and URL or scan
+directories for Git repositories that already live on disk.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: vcspull.cli
+    :func: create_parser
+    :prog: vcspull
+    :path: import
+    :nodescription:
+```
+
+## Manual import
+
+Provide a repository name and remote URL to append an entry to your
+configuration. Use `--path` when you already have a working tree on disk so the
+configured base directory matches its location. Override the inferred base
+directory with `--dir` when you need a specific configuration key.
+
+```console
+$ vcspull import my-lib https://github.com/example/my-lib.git --path ~/code/my-lib
+```
+
+With no `-c/--config` flag vcspull looks for the first YAML configuration file
+under `~/.config/vcspull/` or the current working directory. When none exist a
+new `.vcspull.yaml` is created next to where you run the command.
+
+## Filesystem scanning
+
+`vcspull import --scan` discovers Git repositories that already exist on disk
+and writes them to your configuration. The command prompts before adding each
+repository, showing the inferred name, directory key, and origin URL (when
+available).
+
+```console
+$ vcspull import --scan ~/code --recursive
+? Add ~/code/vcspull (dir: ~/code/)? [y/N]: y
+? Add ~/code/libvcs (dir: ~/code/)? [y/N]: y
+```
+
+- `--recursive`/`-r` searches nested directories.
+- `--base-dir-key` forces all discovered repositories to use the same base
+  directory key, overriding the automatically expanded directory.
+- `--yes`/`-y` accepts every suggestion, which is useful for unattended
+  migrations.
+
+When vcspull detects a Git remote named `origin` it records the remote URL in
+the configuration. Repositories without a remote are still added, allowing you
+to fill the `repo` key later.
+
+## Choosing configuration files
+
+Pass `-c/--config` to import into a specific YAML file:
+
+```console
+$ vcspull import --scan ~/company --recursive --config ~/company/.vcspull.yaml
+```
+
+Use `--all` with the [`vcspull fmt`](cli-fmt) command after a large scan to keep
+configuration entries sorted and normalized.

docs/cli/index.md

@@ -7,6 +7,8 @@
 :maxdepth: 1
 
 sync
+import
+fmt
 ```
 
 ```{toctree}
@@ -31,5 +33,5 @@ completion
     :nodescription:
 
     subparser_name : @replace
-        See :ref:`cli-sync`
+        See :ref:`cli-sync`, :ref:`cli-import`, :ref:`cli-fmt`
 ```

docs/quickstart.md

@@ -111,6 +111,13 @@ YAML? Create a `~/.vcspull.yaml` file:
   "flask": "git+https://github.com/mitsuhiko/flask.git"
 ```
 
+Already have repositories cloned locally? Use
+`vcspull import --scan ~/code --recursive` to detect existing Git checkouts and
+append them to your configuration. See {ref}`cli-import` for more details and
+options such as `--base-dir-key` and `--yes` for unattended runs. After editing
+or importing, run `vcspull fmt --write` (documented in {ref}`cli-fmt`) to
+normalize keys and keep your configuration tidy.
+
 The `git+` in front of the repository URL. Mercurial repositories use
 `hg+` and Subversion will use `svn+`. Repo type and address is
 specified in [pip vcs url][pip vcs url] format.