docs: Improve command formatting (#535)

why: Standardize shell code blocks to follow documentation guidelines
what:
- Use `console` language tag with `$ ` prefix for shell commands
- Split long pipx install command with `\` line continuations
- Split long jq pipe commands in README.md and docs/cli/status.md
- Add Shell Command Formatting rules to AGENTS.md

Author: tony

AGENTS.md

@@ -401,7 +401,7 @@ what:
 
 When writing documentation (README, CHANGES, docs/), follow these rules for code blocks:
 
-**One command per code block.** This makes commands individually copyable.
+**One command per code block.** This makes commands individually copyable. For sequential commands, either use separate code blocks or chain them with `&&` or `;` and `\` continuations (keeping it one logical command).
 
 **Put explanations outside the code block**, not as comments inside.
 
@@ -429,6 +429,42 @@ $ vcspull search django
 $ vcspull search "name:flask"
 ```
 
+### Shell Command Formatting
+
+These rules apply to shell commands in documentation (README, CHANGES, docs/), **not** to Python doctests.
+
+**Use `console` language tag with `$ ` prefix.** This distinguishes interactive commands from scripts and enables prompt-aware copy in many terminals.
+
+Good:
+
+```console
+$ uv run pytest
+```
+
+Bad:
+
+```bash
+uv run pytest
+```
+
+**Split long commands with `\` for readability.** Each flag or flag+value pair gets its own continuation line, indented. Positional parameters go on the final line.
+
+Good:
+
+```console
+$ pipx install \
+    --suffix=@next \
+    --pip-args '\--pre' \
+    --force \
+    'vcspull'
+```
+
+Bad:
+
+```console
+$ pipx install --suffix=@next --pip-args '\--pre' --force 'vcspull'
+```
+
 **Prefer longform flags** — use `--workspace` not `-w`, `--file` not `-f`.
 
 **Split multi-flag commands** — when a command has 2+ flags/options, place each on its own `\`-continuation line, indented by 4 spaces.

CHANGES

@@ -11,7 +11,11 @@ $ pip install --user --upgrade --pre vcspull
 [pipx](https://pypa.github.io/pipx/docs/):
 
 ```console
-$ pipx install --suffix=@next 'vcspull' --pip-args '\--pre' --force
+$ pipx install \
+    --suffix=@next \
+    --pip-args '\--pre' \
+    --force \
+    'vcspull'
 // Usage: vcspull@next sync [config]
 ```
 
@@ -948,7 +952,7 @@ This release modernizes the vcspull CLI to align with DevOps tool conventions (T
 
 #### Migration Guide (#472)
 
-```bash
+```
 # Old → New
 vcspull import NAME URL              → vcspull add NAME URL
 vcspull import --scan DIR            → vcspull discover DIR
@@ -1157,14 +1161,14 @@ _Maintenance only, no bug fixes or new features_
 
   via ruff v0.3.4, all automated lint fixes, including unsafe and previews were applied:
 
-  ```sh
-  ruff check --select ALL . --fix --unsafe-fixes --preview --show-fixes; ruff format .
+  ```console
+  $ ruff check --select ALL . --fix --unsafe-fixes --preview --show-fixes; ruff format .
   ```
 
   Branches were treated with:
 
-  ```sh
-  git rebase \
+  ```console
+  $ git rebase \
       --strategy-option=theirs \
       --exec 'poetry run ruff check --select ALL . --fix --unsafe-fixes --preview --show-fixes; poetry run ruff format .; git add src tests; git commit --amend --no-edit' \
       origin/master

README.md

@@ -208,7 +208,8 @@ for CI/CD:
 $ vcspull sync --dry-run "*"
 $ vcspull sync --dry-run --show-unchanged "workspace-*"
 $ vcspull sync --dry-run --json "*" | jq '.summary'
-$ vcspull sync --dry-run --ndjson "*" | jq --slurp 'map(select(.type == "summary"))'
+$ vcspull sync --dry-run --ndjson "*" \
+    | jq --slurp 'map(select(.type == "summary"))'
 ```
 
 Dry runs stream a progress line when stdout is a TTY, then print a concise plan

docs/cli/completion.md

@@ -32,26 +32,26 @@ $ uvx shtab
 
 :::{tab} bash
 
-```bash
-shtab --shell=bash -u vcspull.cli.create_parser \
+```console
+$ shtab --shell=bash -u vcspull.cli.create_parser \
   | sudo tee "$BASH_COMPLETION_COMPAT_DIR"/VCSPULL
 ```
 
 :::
 
 :::{tab} zsh
 
-```zsh
-shtab --shell=zsh -u vcspull.cli.create_parser \
+```console
+$ shtab --shell=zsh -u vcspull.cli.create_parser \
   | sudo tee /usr/local/share/zsh/site-functions/_VCSPULL
 ```
 
 :::
 
 :::{tab} tcsh
 
-```zsh
-shtab --shell=tcsh -u vcspull.cli.create_parser \
+```console
+$ shtab --shell=tcsh -u vcspull.cli.create_parser \
   | sudo tee /etc/profile.d/VCSPULL.completion.csh
 ```
 

docs/cli/status.md

@@ -129,7 +129,8 @@ Each status entry includes:
 Filter with [jq] to find missing repositories:
 
 ```console
-$ vcspull status --json | jq '.[] | select(.reason == "status" and .exists == false)'
+$ vcspull status --json \
+    | jq '.[] | select(.reason == "status" and .exists == false)'
 ```
 
 Or extract just the summary:
@@ -160,13 +161,16 @@ $ vcspull status --ndjson | grep '"exists":false' | jq -r '.name'
 Monitor missing repositories:
 
 ```console
-$ vcspull status --json | jq -r '.[] | select(.reason == "status" and .exists == false) | .name'
+$ vcspull status --json \
+    | jq -r '.[] | select(.reason == "status" and .exists == false) | .name'
 ```
 
 Check which repositories need syncing:
 
 ```console
-$ vcspull status --json | jq -r '.[] | select(.reason == "status" and .exists == false) | .name' | xargs vcspull sync
+$ vcspull status --json \
+    | jq -r '.[] | select(.reason == "status" and .exists == false) | .name' \
+    | xargs vcspull sync
 ```
 
 Generate reports: