From ca4a99cf3de45ea6ba5678f87e70705f42aabf62 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 15 Mar 2026 04:50:24 -0500
Subject: [PATCH 1/3] ai(rules[AGENTS]): Add shell command formatting rules for
 docs

why: Standardize shell code blocks for copy-pastability and readability
what:
- Add console language tag + $ prefix rule
- Add line continuation rule for wide multi-flag commands
- Scope to documentation shell examples, not doctests
---
 AGENTS.md | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index a5545994..84506c1e 100644
--- a/AGENTS.md
+++ b/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.

From b6f1feb632a85392ead77d357b071c78a899dded Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 15 Mar 2026 04:50:54 -0500
Subject: [PATCH 2/3] docs(style[shell]): Standardize shell code blocks in docs

why: Improve copy-pastability and readability of shell examples
what:
- Ensure all shell blocks use console tag with $ prefix
- Fix docs/cli/completion.md shtab examples
- Fix CHANGES shell examples
- Convert non-command bash block to plain code block
---
 CHANGES                | 10 +++++-----
 docs/cli/completion.md | 12 ++++++------
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/CHANGES b/CHANGES
index 2c514b49..6a90309a 100644
--- a/CHANGES
+++ b/CHANGES
@@ -948,7 +948,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 +1157,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
diff --git a/docs/cli/completion.md b/docs/cli/completion.md
index bdd23ddb..a8e6d787 100644
--- a/docs/cli/completion.md
+++ b/docs/cli/completion.md
@@ -32,8 +32,8 @@ $ 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
 ```
 
@@ -41,8 +41,8 @@ shtab --shell=bash -u vcspull.cli.create_parser \
 
 :::{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
 ```
 
@@ -50,8 +50,8 @@ shtab --shell=zsh -u vcspull.cli.create_parser \
 
 :::{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
 ```
 

From b711393c66e9db705cd13bffba91ffe9a119cc26 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 15 Mar 2026 05:10:40 -0500
Subject: [PATCH 3/3] docs(style[shell]): Split long commands with line
 continuations

why: Apply the line-splitting rule from Shell Command Formatting guidelines
what:
- Split pipx install command in CHANGES header
- Split long jq pipe commands in README.md and docs/cli/status.md
---
 CHANGES            |  6 +++++-
 README.md          |  3 ++-
 docs/cli/status.md | 10 +++++++---
 3 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/CHANGES b/CHANGES
index 6a90309a..df38b5bf 100644
--- a/CHANGES
+++ b/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]
 ```
 
diff --git a/README.md b/README.md
index fea8acaf..bc21d3f7 100644
--- a/README.md
+++ b/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
diff --git a/docs/cli/status.md b/docs/cli/status.md
index 34d4d161..5e0c9618 100644
--- a/docs/cli/status.md
+++ b/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: