docs(cli): reflect duplicate-aware defaults succinctly

why: User-facing docs and README still describe the pre-merge behavior for add,
discover, and fmt; guidance should mention the new defaults without drowning out
other tips.

what:
- note that fmt merges duplicate workspace roots unless --no-merge is supplied
- explain path-based adds, confirmation flags, and duplicate handling in
  docs/cli/add.md and the README bullet list
- mention discover's default merge behavior with a concise pointer to
  --no-merge

Author: tony

README.md

@@ -104,6 +104,10 @@ $ vcspull add my-lib https://github.com/example/my-lib.git --path ~/code/my-lib
   `-w ~/projects/libs`.
 - Pass `-f/--file` to add to an alternate YAML file.
 - Use `--dry-run` to preview changes before writing.
+- Point at an existing checkout (`vcspull add ~/projects/example`) to infer the
+  name and remote; add `--yes` to skip the confirmation prompt.
+- Append `--no-merge` if you prefer to review duplicate workspace roots
+  yourself instead of having vcspull merge them automatically.
 - Follow with `vcspull sync my-lib` to clone or update the working tree after registration.
 
 ### Discover local checkouts and add en masse
@@ -116,8 +120,9 @@ $ vcspull discover ~/code --recursive
 ```
 
 The scan shows each repository before import unless you opt into `--yes`. Add
-`-w ~/code/` to pin the resulting workspace root or `-f` to
-write somewhere other than the default `~/.vcspull.yaml`.
+`-w ~/code/` to pin the resulting workspace root or `-f` to write somewhere other
+than the default `~/.vcspull.yaml`. Duplicate workspace roots are merged by
+default; include `--no-merge` to keep them separate while you review the log.
 
 ### Inspect configured repositories
 
@@ -148,15 +153,16 @@ command for automation workflows.
 
 ### Normalize configuration files
 
-After importing or editing by hand, run the formatter to tidy up keys and keep
-entries sorted:
+After importing or editing by hand, run the formatter to tidy up keys, merge
+duplicate workspace sections, and keep entries sorted:
 
 ```console
 $ vcspull fmt -f ~/.vcspull.yaml --write
 ```
 
 Use `vcspull fmt --all --write` to format every YAML file that vcspull can
-discover under the standard config locations.
+discover under the standard config locations. Add `--no-merge` if you only want
+duplicate roots reported, not rewritten.
 
 ## Sync your repos
 

docs/cli/add.md

@@ -63,6 +63,11 @@ The `--path` flag is useful when:
 - Using non-standard directory layouts
 - The repository name doesn't match the desired directory name
 
+You can also point `vcspull add` at an existing checkout. Supplying a path such
+as `vcspull add ~/projects/example` infers the repository name, inspects its
+`origin` remote, and prompts before writing. Add `--yes` when you need to skip
+the confirmation in scripts.
+
 ## Choosing configuration files
 
 By default, vcspull looks for the first YAML configuration file in:
@@ -142,14 +147,10 @@ $ vcspull add tooling https://github.com/company/tooling.git \
 
 ## Handling duplicates
 
-If a repository with the same name already exists in the workspace, vcspull will warn you:
-
-```console
-$ vcspull add flask https://github.com/pallets/flask.git -w ~/code/
-WARNING: Repository 'flask' already exists in workspace '~/code/'.
-```
-
-The existing entry is preserved and not overwritten.
+vcspull merges duplicate workspace sections by default so existing repositories
+stay intact. When conflicts appear, the command logs what it kept. Prefer to
+resolve duplicates yourself? Pass `--no-merge` to leave every section untouched
+while still surfacing warnings.
 
 ## After adding repositories
 

docs/cli/discover.md

@@ -45,6 +45,10 @@ Scan complete: 2 repositories added, 0 skipped
 ```
 
 The command prompts for each repository before adding it to your configuration.
+When a matching workspace section already exists, vcspull merges the new entry
+into it so previously tracked repositories stay intact. Prefer to review
+duplicates yourself? Add `--no-merge` to keep every section untouched while
+still seeing a warning.
 
 ## Recursive scanning
 

docs/cli/fmt.md

@@ -6,6 +6,11 @@
 entries stay consistent. By default the formatter prints the proposed changes to
 stdout. Apply the updates in place with `--write`.
 
+When duplicate workspace roots are encountered, the formatter merges them into a
+single section so repositories are never dropped. Prefer to review duplicates
+without rewriting them? Pass `--no-merge` to leave the original sections in
+place while still showing a warning.
+
 ## Command
 
 ```{eval-rst}
@@ -19,12 +24,14 @@ stdout. Apply the updates in place with `--write`.
 
 ## What gets formatted
 
-The formatter performs three main tasks:
+The formatter performs four 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.
+- Consolidates duplicate workspace roots into a single merged section while
+  logging any conflicts.
 
 For example: