From 1380dfb7f576ac46fd126fa28a7fb77f853fc6d3 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 15 Mar 2026 04:50:27 -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 7e361269..1cd58c40 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -404,7 +404,7 @@ EOF
 
 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.
 
@@ -432,6 +432,42 @@ $ uv run pytest
 $ uv run pytest --cov
 ```
 
+### 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 \
+    'libvcs'
+```
+
+Bad:
+
+```console
+$ pipx install --suffix=@next --pip-args '\--pre' --force 'libvcs'
+```
+
 ## Debugging Tips
 
 When stuck in debugging loops:

From e61436a12951bfed5eec0c7dc2b3b8d971d10e8d Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 15 Mar 2026 04:50:45 -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 README.md installation examples
- Fix CHANGES shell examples
---
 CHANGES   |  8 ++++----
 README.md | 12 ++++++------
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/CHANGES b/CHANGES
index 1470c3da..44824904 100644
--- a/CHANGES
+++ b/CHANGES
@@ -393,14 +393,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/README.md b/README.md
index 0445daf5..aa16a120 100644
--- a/README.md
+++ b/README.md
@@ -26,20 +26,20 @@ It powers [vcspull](https://github.com/vcs-python/vcspull) and simplifies VCS in
 
 ## Installation
 
-```bash
-pip install libvcs
+```console
+$ pip install libvcs
 ```
 
 With [uv](https://docs.astral.sh/uv/):
 
-```bash
-uv add libvcs
+```console
+$ uv add libvcs
 ```
 
 Try it interactively:
 
-```bash
-uvx --with libvcs ipython
+```console
+$ uvx --with libvcs ipython
 ```
 
 Tip: libvcs is pre-1.0. Pin a version range in projects to avoid surprises:

From 1b240ab782265e5d55542f083b028ca6654a6c6b 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 ruff check compound command in CHANGES
---
 CHANGES | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/CHANGES b/CHANGES
index 44824904..23b020e3 100644
--- a/CHANGES
+++ b/CHANGES
@@ -394,7 +394,10 @@ _Maintenance only, no bug fixes, or new features_
   via ruff v0.3.4, all automated lint fixes, including unsafe and previews were applied:
 
   ```console
-  $ ruff check --select ALL . --fix --unsafe-fixes --preview --show-fixes; ruff format .
+  $ ruff check --select ALL . \
+      --fix --unsafe-fixes \
+      --preview --show-fixes; \
+      ruff format .
   ```
 
   Branches were treated with: