docs: update clone command guidance

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

Author: pixincreate

README.md

@@ -31,7 +31,7 @@ CapSync solves this by creating a single source of truth for your skills and com
 
 **What CapSync Is Not:**
 
-- A skill or command discovery tool. CapSync does not find or download skills/commands from the internet
+- A skill or command discovery tool. CapSync does not search registries or catalogs for skills/commands on your behalf
 - A skill or command installer. You must already have skills/commands in your source directories
 - A skill or command creator. CapSync only syncs what you already have
 
@@ -42,7 +42,7 @@ You need to have skills (and optionally commands) already installed in local dir
 - Optionally, a directory containing your commands (e.g., `~/dev/scripts/commands`)
 - Skills and commands formatted for your AI tools
 
-If you are looking for a tool to discover and install skills from a registry or repository, that is not what CapSync does. That may be a future feature, but for now, CapSync only syncs skills you already possess.
+If you already know which Git repository you want, `capsync clone` can download it into your configured skills source. CapSync still does not browse, rank, or discover skills for you.
 
 ## Installation
 
@@ -308,6 +308,24 @@ Scan system for installed AI coding tools without modifying config.
 
 Create or update symlinks for all enabled tools.
 
+### `capsync clone <repo>`
+
+Clone a remote Git repository into your configured skills source.
+
+Supported inputs:
+
+- `owner/repo`
+- `https://...`
+- `http://...`
+- `git@...`
+
+Options:
+
+- `--branch <name>`: Clone a specific branch instead of auto-detecting the remote default branch
+- `--no-sync`: Skip running `capsync sync` after the clone finishes
+
+If the skills source already exists, CapSync prompts before replacing it. During override, it offers a backup when local changes would otherwise be lost.
+
 ### `capsync add <tool>`
 
 Add a tool to configuration and sync automatically.

documentation/agents.md

@@ -46,7 +46,7 @@ A target tool's skills/commands location. Each destination has:
 A symbolic link. CapSync doesn't copy files—it creates symlinks from destination directories pointing to your source directory.
 
 ### Clone
-The `clone` command fetches a remote GitHub repository into your skills source, enabling CapSync to sync remote skills to local tools.
+The `clone` command fetches a remote Git repository into your skills source, enabling CapSync to sync remote skills to local tools.
 
 ---
 
@@ -136,7 +136,7 @@ Shows:
 
 ### `capsync clone <repo>`
 
-Clone a remote GitHub repository into your skills source.
+Clone a remote Git repository into your skills source.
 
 ```bash
 capsync clone <repo>                 # Clone (auto-detect branch)
@@ -151,11 +151,14 @@ capsync clone <repo> --no-sync       # Clone without syncing
 - If `skills_source` doesn't exist: Clone directly
 - If `skills_source` exists (same repo): Prompt to update or override
 - If `skills_source` exists (different repo): Prompt to override
-- If local has unpushed changes: Warn and offer to backup
+- If `skills_source` exists but is not a git repository: Prompt before overriding
+- If `skills_source` is a git repository without an `origin` remote: Prompt before overriding
+- If override would discard local changes: Warn and offer to back up first
+- If update is selected while the current branch differs from `--branch`: Re-clone the requested branch instead of updating in place
 
 **Branch Detection:**
-- Auto-detects default branch from remote
-- Prefers `main`, falls back to `master`, then alphabetical
+- Auto-detects the remote's default branch from remote HEAD
+- Falls back to fetched branch names only if the remote does not report a default branch
 
 ---
 
@@ -298,7 +301,8 @@ After (with CapSync):
 3. Handle existing source:
    - Same repo → offer update (git pull) or override
    - Different repo → offer override
-   - Local changes → warn and offer backup
+   - Non-git directory or no `origin` remote → require explicit confirmation before override
+   - Local changes during override → warn and offer backup
 4. Clone to `skills_source`
 5. Optionally sync to all enabled tools