From 19c40920fadaf506581910a079776fe7913bf079 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 04:34:17 +0000
Subject: [PATCH 01/18] chore: upgrade tbd to v0.2.2

Run `tbd setup --auto` with get-tbd@0.2.2 to refresh the project's tbd
integration:

- Migrate .tbd/config.yml format f03 -> f04 (adds sync.storage:
  git-common-dir-v1, refreshes docs_cache entries)
- Add .tbd/.gitattributes to protect ID mappings from merge deletion
- Refresh portable Agent Skill (.agents/skills/tbd/SKILL.md)
- Refresh AGENTS.md tbd integration block (format=f04)
- Install Codex surface hooks (.codex/)

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 .agents/skills/tbd/SKILL.md    | 255 +++++++++++++++++++++++++++++++++
 .codex/ensure-gh-cli.sh        | 123 ++++++++++++++++
 .codex/hooks.json              |  47 ++++++
 .codex/tbd-closing-reminder.sh |  15 ++
 .codex/tbd-session.sh          |  27 ++++
 .tbd/.gitattributes            |   2 +
 .tbd/config.yml                |   7 +-
 AGENTS.md                      |  16 +++
 8 files changed, 489 insertions(+), 3 deletions(-)
 create mode 100644 .agents/skills/tbd/SKILL.md
 create mode 100755 .codex/ensure-gh-cli.sh
 create mode 100644 .codex/hooks.json
 create mode 100755 .codex/tbd-closing-reminder.sh
 create mode 100755 .codex/tbd-session.sh
 create mode 100644 .tbd/.gitattributes

diff --git a/.agents/skills/tbd/SKILL.md b/.agents/skills/tbd/SKILL.md
new file mode 100644
index 0000000..07a1672
--- /dev/null
+++ b/.agents/skills/tbd/SKILL.md
@@ -0,0 +1,255 @@
+---
+allowed-tools: Bash(tbd:*), Read, Write
+description: |-
+  Git-native issue tracking (beads), coding guidelines, knowledge injection, and spec-driven planning for AI agents. Drop-in replacement for bd/Beads with simpler architecture.
+  Use for: tracking issues/beads with dependencies, creating bugs/features/tasks, planning specs, implementing features from specs, code reviews, committing code, creating PRs, loading coding guidelines (TypeScript, Python, TDD, golden testing, Convex, monorepo patterns), code cleanup, research briefs, architecture docs, agent handoffs, and checking out third-party library source code.
+  Invoke when user mentions: tbd, beads, bd, shortcuts, issues, bugs, tasks, features, epics, todo, tracking, specs, planning, implementation, validation, guidelines, templates, commit, PR, pull request, code review, testing, TDD, test-driven, golden testing, snapshot testing, TypeScript, Python, Convex, monorepo, cleanup, dead code, refactor, handoff, research, architecture, labels, search, checkout library, source code review, or any workflow shortcut.
+name: tbd
+---
+<!-- DO NOT EDIT: Generated by tbd setup (format=f04).
+Run 'tbd setup' to update.
+-->
+
+**`tbd` helps humans and agents ship code with greater speed, quality, and discipline.**
+
+1. **Beads**: Git-native issue tracking (tasks, bugs, features).
+   Never lose work across sessions.
+   Drop-in replacement for `bd`.
+2. **Spec-Driven Workflows**: Plan features → break into beads → implement
+   systematically.
+3. **Knowledge Injection**: 17+ engineering guidelines (TypeScript, Python, TDD,
+   testing, Convex, monorepos) available on demand.
+4. **Shortcuts**: Reusable instruction templates for common workflows (code review,
+   commits, PRs, cleanup, handoffs).
+
+## Installation
+
+```bash
+npm install -g get-tbd@latest
+tbd setup --auto --prefix=<name>   # Fresh project (--prefix is REQUIRED: 2-8 alphabetic chars recommended. ALWAYS ASK THE USER FOR THE PREFIX; do not guess it)
+tbd setup --auto                   # Existing tbd project (prefix already set)
+tbd setup --from-beads             # Migration from .beads/ if `bd` has been used
+```
+
+## Routine Commands
+
+```bash
+tbd --help    # Command reference
+tbd status    # Status
+tbd doctor    # If there are problems
+
+tbd setup --auto   # Run any time to refresh setup
+tbd prime      # Restore full context on tbd after compaction
+```
+
+## CRITICAL: You Operate tbd — The User Doesn’t
+
+**You are the tbd operator:** Users talk naturally; you translate their requests to tbd
+actions. DO NOT tell users to run tbd commands.
+That’s your job.
+
+- **WRONG**: “Run `tbd create` to track this bug”
+
+- **RIGHT**: *(you run `tbd create` yourself and tell the user it’s tracked)*
+
+**Welcoming a user:** When users ask “what is tbd?”
+or want help → run `tbd shortcut welcome-user`
+
+## User Request → Agent Action
+
+| User Says | You (the Agent) Run |
+| --- | --- |
+| **Issues/Beads** |  |
+| “There’s a bug where …” | `tbd create "..." --type=bug` |
+| “Create a task/feature for …” | `tbd create "..." --type=task` or `--type=feature` |
+| “Let’s work on issues/beads” | `tbd ready` |
+| “Show me issue X” | `tbd show <id>` |
+| “Close this issue” | `tbd close <id>` |
+| “Search issues for X” | `tbd search "X"` |
+| “Add label X to issue” | `tbd label add <id> <label>` |
+| “What issues are stale?” | `tbd stale` |
+| **Planning & Specs** |  |
+| “Plan a new feature” / “Create a spec” | `tbd shortcut new-plan-spec` |
+| “Break spec into beads” | `tbd shortcut plan-implementation-with-beads` |
+| “Implement these beads” | `tbd shortcut implement-beads` |
+| **Code Review & Commits** |  |
+| “Review this code” / “Code review” | `tbd shortcut review-code` |
+| “Review this PR” | `tbd shortcut review-github-pr` |
+| “Commit this” / “Use the commit shortcut” | `tbd shortcut code-review-and-commit` |
+| “Create a PR” / “File a PR” | `tbd shortcut create-or-update-pr-simple` |
+| “Merge main into my branch” | `tbd shortcut merge-upstream` |
+| **Guidelines & Knowledge** |  |
+| “Use TypeScript best practices” | `tbd guidelines typescript-rules` |
+| “Use Python best practices” | `tbd guidelines python-rules` |
+| “Build a TypeScript CLI” | `tbd guidelines typescript-cli-tool-rules` |
+| “Improve monorepo setup” | `tbd guidelines pnpm-monorepo-patterns` or `bun-monorepo-patterns` |
+| “Add golden/e2e testing” | `tbd guidelines golden-testing-guidelines` |
+| “Use TDD” / “Test-driven development” | `tbd guidelines general-tdd-guidelines` |
+| “Convex best practices” | `tbd guidelines convex-rules` |
+| **Documentation** |  |
+| “Research this topic” | `tbd shortcut new-research-brief` |
+| “Document architecture” | `tbd shortcut new-architecture-doc` |
+| **Cleanup & Maintenance** |  |
+| “Clean up this code” / “Remove dead code” | `tbd shortcut code-cleanup-all` |
+| “Fix repository problems” | `tbd doctor --fix` |
+| **Sessions & Handoffs** |  |
+| “Hand off to another agent” | `tbd shortcut agent-handoff` |
+| “Check out this library’s source” | `tbd shortcut checkout-third-party-repo` |
+| *(your choice whenever appropriate)* | `tbd list`, `tbd dep add`, `tbd close`, `tbd sync`, etc. |
+
+**Note:** Never gitignore `.tbd/workspaces/` — the outbox must be committed to your
+working branch. See `tbd guidelines tbd-sync-troubleshooting` for details.
+
+## CRITICAL: Session Closing Protocol
+
+**Before saying “done”, you MUST complete this checklist:**
+
+```
+[ ] 1. git add + git commit
+[ ] 2. git push
+[ ] 3. gh pr checks <PR> --watch 2>&1 (IMPORTANT: WAIT for final summary, do NOT tell user it is done until you confirm it passes CI!)
+[ ] 4. tbd close/update <id> for all beads worked on
+[ ] 5. tbd sync
+[ ] 6. CONFIRM CI passed (if failed: fix, run tests, re-push, restart from step 3)
+```
+
+**Work is not done until pushed, CI passes, and tbd is synced.**
+
+## Bead Tracking Rules
+
+- Track all task work not done immediately as beads (discovered work, TODOs,
+  multi-session work)
+- When in doubt, create a bead
+- Check `tbd ready` when not given specific directions
+- Always close/update beads and run `tbd sync` at session end
+
+## Commands
+
+### Finding Work
+
+| Command | Purpose |
+| --- | --- |
+| `tbd ready` | Beads ready to work (no blockers) |
+| `tbd list --status open` | All open beads |
+| `tbd list --status in_progress` | Your active work |
+| `tbd show <id>` | Bead details with dependencies |
+
+### Creating & Updating
+
+| Command | Purpose |
+| --- | --- |
+| `tbd create "title" --type=bug --priority=1` | New bead; run `tbd create --help` for all types and priorities (P0-P4, not “high/medium/low”) |
+| `tbd update <id> --status in_progress` | Claim work |
+| `tbd close <id> [--reason "..."]` | Mark complete |
+
+### Dependencies & Sync
+
+| Command | Purpose |
+| --- | --- |
+| `tbd dep add <bead> <depends-on>` | Add dependency |
+| `tbd blocked` | Show blocked beads |
+| `tbd sync` | Sync with git remote (run at session end) |
+| `tbd stats` | Project statistics |
+| `tbd doctor` | Check for problems |
+| `tbd doctor --fix` | Auto-fix repository problems |
+
+### Labels & Search
+
+| Command | Purpose |
+| --- | --- |
+| `tbd search <query>` | Search issues by text |
+| `tbd label add <id> <label>` | Add label to issue |
+| `tbd label remove <id> <label>` | Remove label from issue |
+| `tbd label list` | List all labels in use |
+| `tbd stale` | List issues not updated recently |
+
+### Documentation
+
+| Command | Purpose |
+| --- | --- |
+| `tbd shortcut <name>` | Run a shortcut |
+| `tbd shortcut --list` | List shortcuts |
+| `tbd guidelines <name>` | Load coding guidelines |
+| `tbd guidelines --list` | List guidelines |
+| `tbd template <name>` | Output a template |
+
+## Quick Reference
+
+- **Priority**: P0=critical, P1=high, P2=medium (default), P3=low, P4=backlog
+- **Types**: issues default to `task`; run `tbd create --help` for the valid types
+- **Status**: open, in_progress, closed
+- **JSON output**: Add `--json` to any command
+
+<!-- BEGIN SHORTCUT DIRECTORY -->
+## Available Shortcuts
+
+Run `tbd shortcut <name>` to use any of these shortcuts:
+
+| Name | Description |
+| --- | --- |
+| agent-handoff | Generate a concise handoff prompt for another coding agent to continue work |
+| checkout-third-party-repo | Get source code for libraries and third-party repos using git. Essential for reliable source code review. Prefer this to web searches or fetching of web pages from github.com as it is far more effective (github.com blocks web scraping from main website). |
+| code-cleanup-all | Full cleanup cycle including duplicate removal, dead code, and code quality improvements |
+| code-cleanup-docstrings | Review and add concise docstrings to major functions and types |
+| code-cleanup-tests | Review and remove tests that do not add meaningful coverage |
+| code-review-and-commit | Run pre-commit checks, review changes, and commit code |
+| coding-spike | Prototype to validate a spec through hands-on implementation |
+| create-or-update-pr-simple | Create or update a pull request with a concise summary |
+| create-or-update-pr-with-validation-plan | Create or update a pull request with a detailed test/validation plan |
+| implement-beads | Implement beads from a spec, following TDD and project rules |
+| merge-upstream | Merge origin/main into current branch with conflict resolution |
+| new-architecture-doc | Create an architecture document for a system or component design |
+| new-guideline | Create a new coding guideline document for tbd |
+| new-plan-spec | Create a new feature planning specification document |
+| new-qa-playbook | Create a QA test playbook for manual validation workflows |
+| new-research-brief | Create a research document for investigating a topic or technology |
+| new-shortcut | Create a new shortcut (reusable instruction template) for tbd |
+| new-validation-plan | Create a validation/test plan showing what’s tested and what remains |
+| plan-implementation-with-beads | Create implementation beads from a feature planning spec |
+| precommit-process | Full pre-commit checklist including spec sync, code review, and testing |
+| review-code | Comprehensive code review for uncommitted changes, branch work, or GitHub PRs |
+| review-code-python | Python-focused code review (language-specific rules only) |
+| review-code-typescript | TypeScript-focused code review (language-specific rules only) |
+| review-github-pr | Review a GitHub pull request with follow-up actions (comment, fix, CI check) |
+| revise-all-architecture-docs | Comprehensive revision of all current architecture documents |
+| revise-architecture-doc | Update an architecture document to reflect current codebase state |
+| setup-github-cli | Ensure GitHub CLI (gh) is installed and working |
+| sync-failure-recovery | Handle tbd sync failures by saving to workspace and recovering later |
+| update-specs-status | Review active specs and sync their status with tbd issues |
+| welcome-user | Welcome message for users after tbd installation or setup |
+
+## Available Guidelines
+
+Run `tbd guidelines <name>` to apply any of these guidelines:
+
+| Name | Description |
+| --- | --- |
+| backward-compatibility-rules | Guidelines for maintaining backward compatibility across code, APIs, file formats, and database schemas |
+| bun-monorepo-patterns | Modern patterns for Bun-based TypeScript monorepo architecture |
+| cli-agent-skill-patterns | How to write skills and agent-integrated CLIs that work across Claude Code, Codex, and the broader coding-agent ecosystem—a simple baseline plus references for advanced, multi-subcommand tools |
+| commit-conventions | Conventional Commits format with extensions for agentic workflows |
+| common-doc-guidelines | Common cross-project standards for writing and organizing docs, code comments, and text files—how to organize, structure, write, and format documents, plus the guideline footer convention. Downstream of github.com/jlevy/practical-prose. Use whenever writing or editing any documentation, README, guideline, or design doc. |
+| convex-limits-best-practices | Comprehensive reference for Convex platform limits, workarounds, and performance best practices |
+| convex-rules | Guidelines and best practices for building Convex projects, including database schema design, queries, mutations, and real-world examples |
+| electron-app-development-patterns | Guidelines for Electron development ecosystems including npm, pnpm, and Bun, with security baselines and framework comparisons |
+| error-handling-rules | Rules for handling errors, failures, and exceptional conditions |
+| general-coding-rules | Rules for constants, magic numbers, and general coding practices |
+| general-comment-rules | Language-agnostic rules for writing clean, maintainable comments |
+| general-eng-assistant-rules | Rules for AI assistants acting as senior engineers, including objectivity and communication guidelines |
+| general-tdd-guidelines | Test-Driven Development methodology and best practices |
+| general-testing-rules | Rules for writing minimal, effective tests with maximum coverage |
+| golden-testing-guidelines | Guidelines for implementing golden/snapshot testing for complex systems |
+| pnpm-monorepo-patterns | Modern patterns for pnpm-based TypeScript monorepo architecture |
+| python-cli-patterns | Modern patterns for Python CLI application architecture |
+| python-modern-guidelines | Guidelines for modern Python projects using uv, with a few more opinionated practices |
+| python-rules | General Python coding rules and best practices |
+| release-notes-guidelines | Guidelines for writing clear, accurate release notes |
+| supply-chain-hardening | Strongly recommended for EVERY repo—apply it if a repo has not been hardened yet. Cross-ecosystem policy for installing dependencies safely (the 14-day cool-off, disabled install scripts, lockfile discipline, untrusted-repo handling). Use whenever a user mentions hardening, security, supply chain, or setting up a new repo; before adding/upgrading dependencies; when auditing for compromised packages; or when reviewing install/build/run commands across npm/pnpm, PyPI, Cargo, or Go. |
+| tbd-sync-troubleshooting | Common issues and solutions for tbd sync and workspace operations |
+| typescript-cli-tool-rules | Rules for building CLI tools with Commander.js, picocolors, and TypeScript |
+| typescript-code-coverage | Best practices for code coverage in TypeScript with Vitest and v8 provider |
+| typescript-rules | TypeScript coding rules and best practices |
+| typescript-sorting-patterns | Deterministic sorting patterns and comparison chains for TypeScript |
+| typescript-yaml-handling-rules | Best practices for parsing and serializing YAML in TypeScript |
+
+<!-- END SHORTCUT DIRECTORY -->
diff --git a/.codex/ensure-gh-cli.sh b/.codex/ensure-gh-cli.sh
new file mode 100755
index 0000000..2de7f99
--- /dev/null
+++ b/.codex/ensure-gh-cli.sh
@@ -0,0 +1,123 @@
+#!/bin/bash
+# Automated GitHub CLI setup for Claude Code sessions
+# This script runs on SessionStart to ensure gh CLI is available and authenticated
+#
+# Supply-chain policy (see SUPPLY-CHAIN-SECURITY.md): the gh version is PINNED to
+# a release at least 14 days old, and every download is verified against a pinned
+# SHA-256 checksum. Do NOT change this to fetch "latest" from the API at runtime;
+# that bypasses the cool-off window. To bump the pin, pick a release that is >=14
+# days old and copy its checksums from:
+#   https://github.com/cli/cli/releases/download/v<VERSION>/gh_<VERSION>_checksums.txt
+
+set -euo pipefail
+
+# Add common binary locations to PATH
+export PATH="$HOME/.local/bin:$HOME/bin:/usr/local/bin:$PATH"
+
+# Pinned gh release (>=14 days old per supply-chain cool-off) and its checksums.
+GH_VERSION="2.92.0"
+
+# SHA-256 checksums from gh_2.92.0_checksums.txt, keyed by asset suffix.
+checksum_for() {
+    case "$1" in
+        linux_amd64.tar.gz) echo "b57848131bdf0c229cd35e1f2a51aa718199858b2e728410b37e89a428943ec4" ;;
+        linux_arm64.tar.gz) echo "c2248526dd0160c08d3fccca2332c3c1a07c15a78b23978e77735f1b5a18cfee" ;;
+        macOS_amd64.zip)    echo "ae9bb327ab0d91071bdada79f8f14034a2a0f19b0e001835a782eafa519d2af0" ;;
+        macOS_arm64.zip)    echo "b11c54f6bd7d15ed6590475079e5b2fcf36f45d3991a80041b29c9d0cc1f1d07" ;;
+        *) echo "" ;;
+    esac
+}
+
+# Check if gh is already installed
+if command -v gh &> /dev/null; then
+    echo "[gh] CLI found at $(which gh)"
+else
+    echo "[gh] CLI not found, installing pinned v${GH_VERSION}..."
+
+    # Detect platform
+    OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+    ARCH=$(uname -m)
+    [ "$ARCH" = "x86_64" ] && ARCH="amd64"
+    [ "$ARCH" = "aarch64" ] && ARCH="arm64"
+
+    # Build the asset suffix and archive type per platform.
+    if [ "$OS" = "darwin" ]; then
+        PLATFORM="macOS_${ARCH}.zip"
+        ARCHIVE_EXT="zip"
+        EXTRACT_DIR="/tmp/gh_${GH_VERSION}_macOS_${ARCH}"
+    else
+        PLATFORM="${OS}_${ARCH}.tar.gz"
+        ARCHIVE_EXT="tar.gz"
+        EXTRACT_DIR="/tmp/gh_${GH_VERSION}_${OS}_${ARCH}"
+    fi
+
+    echo "[gh] Detected platform: ${PLATFORM}"
+
+    EXPECTED=$(checksum_for "$PLATFORM")
+    if [ -z "$EXPECTED" ]; then
+        echo "[gh] ERROR: no pinned checksum for platform ${PLATFORM}; refusing to install"
+        echo "[gh] Add the checksum from gh_${GH_VERSION}_checksums.txt to this script"
+        exit 1
+    fi
+
+    ASSET="gh_${GH_VERSION}_${PLATFORM}"
+    DOWNLOAD_URL="https://github.com/cli/cli/releases/download/v${GH_VERSION}/${ASSET}"
+
+    echo "[gh] Downloading from ${DOWNLOAD_URL}..."
+    curl -fsSL -o "/tmp/${ASSET}" "$DOWNLOAD_URL"
+
+    # Verify the download against the pinned checksum before extracting.
+    if command -v sha256sum &> /dev/null; then
+        ACTUAL=$(sha256sum "/tmp/${ASSET}" | awk '{print $1}')
+    else
+        ACTUAL=$(shasum -a 256 "/tmp/${ASSET}" | awk '{print $1}')
+    fi
+    if [ "$ACTUAL" != "$EXPECTED" ]; then
+        echo "[gh] ERROR: checksum mismatch for ${ASSET}"
+        echo "[gh]   expected ${EXPECTED}"
+        echo "[gh]   actual   ${ACTUAL}"
+        rm -f "/tmp/${ASSET}"
+        exit 1
+    fi
+    echo "[gh] Checksum verified for ${ASSET}"
+
+    # Extract based on archive type
+    if [ "$ARCHIVE_EXT" = "zip" ]; then
+        unzip -q "/tmp/${ASSET}" -d /tmp
+    else
+        tar -xzf "/tmp/${ASSET}" -C /tmp
+    fi
+
+    # Install to ~/.local/bin (works in cloud and local)
+    mkdir -p ~/.local/bin
+    cp "${EXTRACT_DIR}/bin/gh" ~/.local/bin/gh
+    chmod +x ~/.local/bin/gh
+
+    # Clean up
+    rm -rf "${EXTRACT_DIR}" "/tmp/${ASSET}"
+
+    echo "[gh] Installed to ~/.local/bin/gh"
+fi
+
+# Verify gh is now in PATH
+if ! command -v gh &> /dev/null; then
+    echo "[gh] ERROR: gh CLI still not found in PATH after installation"
+    echo "[gh] Ensure ~/.local/bin is in your PATH"
+    exit 1
+fi
+
+# Check authentication status
+if [ -n "${GH_TOKEN:-}" ]; then
+    # GH_TOKEN is set, verify it works
+    if gh auth status &> /dev/null; then
+        echo "[gh] Authenticated successfully"
+    else
+        echo "[gh] WARNING: GH_TOKEN is set but authentication check failed"
+        echo "[gh] Token may be invalid or expired"
+    fi
+else
+    echo "[gh] NOTE: GH_TOKEN not set - some operations may require authentication"
+    echo "[gh] See: docs/general/agent-setup/github-cli-setup.md"
+fi
+
+exit 0
diff --git a/.codex/hooks.json b/.codex/hooks.json
new file mode 100644
index 0000000..050c6f6
--- /dev/null
+++ b/.codex/hooks.json
@@ -0,0 +1,47 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .codex/tbd-session.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .codex/ensure-gh-cli.sh",
+            "timeout": 120
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .codex/tbd-session.sh --brief"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .codex/tbd-closing-reminder.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.codex/tbd-closing-reminder.sh b/.codex/tbd-closing-reminder.sh
new file mode 100755
index 0000000..a6056b0
--- /dev/null
+++ b/.codex/tbd-closing-reminder.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+# Remind about close protocol after git push
+# Installed by: tbd setup claude
+
+input=$(cat)
+command=$(echo "$input" | jq -r '.tool_input.command // empty')
+
+# Check if this is a git push command and .tbd exists
+if [[ "$command" == git\ push* ]] || [[ "$command" == *"&& git push"* ]] || [[ "$command" == *"; git push"* ]]; then
+  if [ -d ".tbd" ]; then
+    tbd closing
+  fi
+fi
+
+exit 0
diff --git a/.codex/tbd-session.sh b/.codex/tbd-session.sh
new file mode 100755
index 0000000..9dbfa30
--- /dev/null
+++ b/.codex/tbd-session.sh
@@ -0,0 +1,27 @@
+#!/bin/bash
+# Ensure the tbd CLI is available and run `tbd prime`.
+# Installed by: tbd setup --auto. Runs on SessionStart and PreCompact.
+#
+# Local-first, then a VERSION-PINNED zero-install fallback. Pinning is both a
+# supply-chain control (an unpinned runner re-resolves to latest on every run
+# and bypasses any cool-off) and a consistency control (every teammate and agent
+# runs the same tbd version).
+
+# Prefer common local bin locations.
+export PATH="$HOME/.local/bin:$HOME/bin:/usr/local/bin:$PATH"
+
+# Local-first: use tbd if it is already on PATH.
+if command -v tbd &> /dev/null; then
+    tbd prime "$@"
+    exit $?
+fi
+
+# Pinned zero-install fallback. Never use an unpinned runner here.
+if command -v npx &> /dev/null; then
+    npx --yes get-tbd@0.2.2 prime "$@"
+    exit $?
+fi
+
+echo "[tbd] tbd CLI not found and npx is unavailable."
+echo "[tbd] Install it with: npm install -g get-tbd@0.2.2"
+exit 1
diff --git a/.tbd/.gitattributes b/.tbd/.gitattributes
new file mode 100644
index 0000000..f263981
--- /dev/null
+++ b/.tbd/.gitattributes
@@ -0,0 +1,2 @@
+# Protect ID mappings from merge deletion (always keep all rows)
+**/mappings/ids.yml merge=union
diff --git a/.tbd/config.yml b/.tbd/config.yml
index bb8334e..08b6ad5 100644
--- a/.tbd/config.yml
+++ b/.tbd/config.yml
@@ -1,10 +1,11 @@
-tbd_format: f03
+tbd_format: f04
 tbd_version: 0.1.22
 display:
   id_prefix: rpy
 sync:
   branch: tbd-sync
   remote: origin
+  storage: git-common-dir-v1
 settings:
   auto_sync: false
   doc_auto_sync_hours: 24
@@ -64,6 +65,7 @@ docs_cache:
     guidelines/bun-monorepo-patterns.md: internal:guidelines/bun-monorepo-patterns.md
     guidelines/cli-agent-skill-patterns.md: internal:guidelines/cli-agent-skill-patterns.md
     guidelines/commit-conventions.md: internal:guidelines/commit-conventions.md
+    guidelines/common-doc-guidelines.md: internal:guidelines/common-doc-guidelines.md
     guidelines/convex-limits-best-practices.md: internal:guidelines/convex-limits-best-practices.md
     guidelines/convex-rules.md: internal:guidelines/convex-rules.md
     guidelines/electron-app-development-patterns.md: internal:guidelines/electron-app-development-patterns.md
@@ -71,7 +73,6 @@ docs_cache:
     guidelines/general-coding-rules.md: internal:guidelines/general-coding-rules.md
     guidelines/general-comment-rules.md: internal:guidelines/general-comment-rules.md
     guidelines/general-eng-assistant-rules.md: internal:guidelines/general-eng-assistant-rules.md
-    guidelines/general-style-rules.md: internal:guidelines/general-style-rules.md
     guidelines/general-tdd-guidelines.md: internal:guidelines/general-tdd-guidelines.md
     guidelines/general-testing-rules.md: internal:guidelines/general-testing-rules.md
     guidelines/golden-testing-guidelines.md: internal:guidelines/golden-testing-guidelines.md
@@ -80,13 +81,13 @@ docs_cache:
     guidelines/python-modern-guidelines.md: internal:guidelines/python-modern-guidelines.md
     guidelines/python-rules.md: internal:guidelines/python-rules.md
     guidelines/release-notes-guidelines.md: internal:guidelines/release-notes-guidelines.md
+    guidelines/supply-chain-hardening.md: internal:guidelines/supply-chain-hardening.md
     guidelines/tbd-sync-troubleshooting.md: internal:guidelines/tbd-sync-troubleshooting.md
     guidelines/typescript-cli-tool-rules.md: internal:guidelines/typescript-cli-tool-rules.md
     guidelines/typescript-code-coverage.md: internal:guidelines/typescript-code-coverage.md
     guidelines/typescript-rules.md: internal:guidelines/typescript-rules.md
     guidelines/typescript-sorting-patterns.md: internal:guidelines/typescript-sorting-patterns.md
     guidelines/typescript-yaml-handling-rules.md: internal:guidelines/typescript-yaml-handling-rules.md
-    guidelines/writing-style-guidelines.md: internal:guidelines/writing-style-guidelines.md
     templates/architecture-doc.md: internal:templates/architecture-doc.md
     templates/plan-spec.md: internal:templates/plan-spec.md
     templates/qa-playbook.md: internal:templates/qa-playbook.md
diff --git a/AGENTS.md b/AGENTS.md
index edcc70e..5268e68 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,2 +1,18 @@
 IMPORTANT: You MUST read ./docs/development.md and ./docs/docs-overview.md for project documentation.
 (This project uses Speculate project structure.)
+
+
+<!-- BEGIN TBD INTEGRATION format=f04 surface=agents-md -->
+## tbd
+
+This repository uses **tbd** for git-native issue tracking (beads), spec-driven
+planning, and on-demand engineering guidelines.
+As the agent, you operate tbd on the user’s behalf — translate their requests into tbd
+actions rather than telling them to run commands.
+
+- Run `tbd prime` to load current project state and the full tbd workflow.
+- Run `tbd skill` for the complete reusable tbd skill instructions.
+- Run `tbd shortcut --list` and `tbd guidelines --list` for on-demand resources.
+- Track all work as beads: `tbd create`, `tbd ready`, `tbd close`, and `tbd sync`.
+
+<!-- END TBD INTEGRATION -->

From 25d9f5bf8b155840638bfd0f235a268ec21af01b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 05:11:50 +0000
Subject: [PATCH 02/18] feat: install repren skill to portable + Claude
 surfaces with pinned uvx
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Align repren's agent-skill installation with the cli-agent-skill-patterns
guideline. repren is a general-purpose utility with no per-project config,
so it stays a dual-scope (project or global) skill invoked via a pinned
zero-install uvx runner — no need to add it as a project dependency.

Changes:
- install_skill now writes both the portable cross-agent surface
  (.agents/skills/repren/) and the Claude Code mirror (.claude/skills/repren/),
  under $HOME (global) or a project root (--agent-base). --agent-base still
  accepts a legacy .claude/.agents path (its parent is used as the root).
- SKILL.md is now a template: {{REPREN_VERSION}} is rendered to the installed
  public version at install time, replacing the unpinned `uvx repren@latest`
  with a pinned `uvx repren@<version>` fallback (supply-chain hygiene). Examples
  are local-first (`repren ...`) with the pinned uvx runner documented as the
  no-install fallback. Local PEP 440 "+..." segments are dropped from the pin.
- Updated docstring, README, CLI help, and fallback messages accordingly.
- Tests: cover both surfaces, version pinning, and absence of @latest; golden
  A6 made version-independent.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 README.md                                     |  24 ++-
 repren/claude_skill.py                        | 154 ++++++++++++------
 repren/repren.py                              |  42 +++--
 repren/skills/SKILL.md                        |  48 +++---
 tests/pytests.py                              |  49 +++++-
 tests/tryscript/advanced-options.tryscript.md |  28 +++-
 6 files changed, 233 insertions(+), 112 deletions(-)

diff --git a/README.md b/README.md
index b2ed402..33f4057 100644
--- a/README.md
+++ b/README.md
@@ -183,11 +183,16 @@ script somewhere convenient and make it executable.
 
 repren is ideal for use by AI coding agents (Claude Code, Codex, etc.)
 since it is powerful, simple to use, and self-documenting.
-Just tell agents to run `uvx repren@latest --help` and they have everything they need,
-including the ability to install it as a skill.
+Just tell agents to run `repren --help` (or, with no install, `uvx repren@latest --help`)
+and they have everything they need, including the ability to install it as a skill.
 Agents can use `--format=json` for machine-parseable output.
 
-repren includes a built-in skill for Claude Code or other agents.
+repren includes a built-in skill for coding agents. Installing it writes the skill to
+both the portable cross-agent location (`.agents/skills/repren/`, used by Codex, pi, and
+others) and the Claude Code mirror (`.claude/skills/repren/`). repren is a general-purpose
+utility with no per-project config, so the skill invokes it via a pinned zero-install
+runner (`uvx repren@<version>`) and there is no need to add repren as a project
+dependency.
 
 **Install:**
 
@@ -195,15 +200,16 @@ repren includes a built-in skill for Claude Code or other agents.
 # Install globally (available in all projects):
 uvx repren --install-skill
 
-# Or install for current project only (shareable via git):
-uvx repren --install-skill --agent-base=./.claude
+# Or install for the current project only (shareable via git):
+uvx repren --install-skill --agent-base=.
 ```
 
-Re-run to update an existing installation.
+Re-run to update an existing installation. The skill pins the repren version it was
+installed from.
 
-**Manual install:** Run `uvx repren --skill` and save to
-`~/.claude/skills/repren/SKILL.md` (global) or `.claude/skills/repren/SKILL.md`
-(project).
+**Manual install:** Run `uvx repren --skill` and save the output to
+`.agents/skills/repren/SKILL.md` (and/or `.claude/skills/repren/SKILL.md`), under `~`
+for a global install or the project root for a project install.
 
 **Learn more:** [Claude Code docs](https://claude.ai/code) and
 [Skills repository](https://github.com/anthropics/skills).
diff --git a/repren/claude_skill.py b/repren/claude_skill.py
index e0db7a3..6c82517 100644
--- a/repren/claude_skill.py
+++ b/repren/claude_skill.py
@@ -1,19 +1,53 @@
 """
-Claude Code skill installation for repren.
+Agent skill installation for repren.
 
-This module provides functionality to install the repren skill for Claude Code,
-making it available either globally across all projects or within a specific project.
+This module installs the repren skill for coding agents. The skill is written to
+both the portable cross-agent location (`.agents/skills/repren/`) and the Claude Code
+mirror (`.claude/skills/repren/`), either globally (under ``$HOME``) or within a
+specific project.
+
+The skill text in ``skills/SKILL.md`` is a template: the ``{{REPREN_VERSION}}``
+placeholder is replaced with the installed repren version so the skill's pinned
+zero-install fallback (``uvx repren@<version>``) always matches what produced it.
 """
 
 import sys
 from pathlib import Path
 
+# Placeholder in skills/SKILL.md replaced with the installed repren version at render time.
+VERSION_PLACEHOLDER = "{{REPREN_VERSION}}"
+
+
+def _pinned_version() -> str:
+    """Return the installed repren version suitable for a ``uvx repren@<version>`` pin.
+
+    Any PEP 440 local-version segment (after ``+``) is dropped, since local versions are
+    never available from a package index and so could not be installed by ``uvx``.
+    """
+    import importlib.metadata
+
+    try:
+        version = importlib.metadata.version("repren")
+    except importlib.metadata.PackageNotFoundError:
+        version = "0.0.0.dev"
+    return version.split("+", 1)[0]
+
+
+def _render_skill(template: str) -> str:
+    """Substitute the version placeholder in the skill template.
+
+    The installed repren version is injected so the skill's pinned
+    ``uvx repren@<version>`` fallback matches the package that produced it.
+    """
+    return template.replace(VERSION_PLACEHOLDER, _pinned_version())
+
 
 def get_skill_content() -> str:
-    """Read SKILL.md from package data.
+    """Read SKILL.md from package data and render it for the installed version.
 
     Returns:
-        The content of the SKILL.md file as a string.
+        The rendered SKILL.md content, with ``{{REPREN_VERSION}}`` replaced by the
+        installed repren version.
 
     Raises:
         ImportError: If package resources cannot be accessed.
@@ -24,48 +58,65 @@ def get_skill_content() -> str:
         from importlib.resources import files
 
         skill_file = files("repren").joinpath("skills/SKILL.md")
-        return skill_file.read_text(encoding="utf-8")
+        template = skill_file.read_text(encoding="utf-8")
     except (ImportError, AttributeError):
         # Fallback for older Python versions
         try:
             import pkg_resources  # type: ignore[import-not-found]  # pyright: ignore[reportMissingImports]
 
-            return pkg_resources.resource_string("repren", "skills/SKILL.md").decode("utf-8")
+            template = pkg_resources.resource_string("repren", "skills/SKILL.md").decode("utf-8")
         except Exception as e:
             raise ImportError(
                 f"Could not load skill from package data: {e}\n"
                 "Ensure repren is installed as a package, not run as a standalone script."
             ) from e
 
+    return _render_skill(template)
 
-def install_skill(agent_base: str | None = None) -> None:
-    """Install repren skill for Claude Code.
+
+def _resolve_root(agent_base: str | None) -> tuple[Path, str]:
+    """Resolve the root directory the skill surfaces are installed under.
+
+    The skill is always written to two surfaces beneath the returned root:
+    ``<root>/.agents/skills/repren/`` (portable, cross-agent) and
+    ``<root>/.claude/skills/repren/`` (Claude Code mirror).
 
     Args:
-        agent_base: The agent's configuration directory where skills are stored.
-            The skill will be installed to {agent_base}/skills/repren/SKILL.md
-            - None (default): Install globally to ~/.claude/skills/repren
-            - './.claude': Install to current project's .claude/skills/repren
-            - Any path: Install to that agent base directory
-
-    The skill will be installed as SKILL.md in the appropriate directory,
-    making it automatically available to Claude Code.
+        agent_base: None for a global install (under ``$HOME``). Otherwise the project
+            root, or — for backward compatibility — a ``.claude``/``.agents`` directory
+            whose parent is taken as the project root.
+
+    Returns:
+        A ``(root, scope_description)`` tuple.
     """
-    # Determine installation directory
     if agent_base is None:
-        # Default: global install to ~/.claude
-        base_dir = Path.home() / ".claude"
-        location_desc = "globally"
-        location_path = "~/.claude/skills/repren"
-    else:
-        # User-specified agent base directory
-        base_dir = Path(agent_base).resolve()
-        location_desc = f"to {base_dir}"
-        location_path = str(base_dir / "skills" / "repren")
-
-    skill_dir = base_dir / "skills" / "repren"
-
-    # Load skill content from package data
+        return Path.home(), "globally (under ~)"
+
+    resolved = Path(agent_base).resolve()
+    # Backward compatibility: callers historically passed the `.claude` dir itself
+    # (e.g. `--agent-base ./.claude`). Treat such a path as "the project is its parent".
+    if resolved.name in (".agents", ".claude"):
+        resolved = resolved.parent
+    return resolved, f"to project {resolved}"
+
+
+def install_skill(agent_base: str | None = None) -> None:
+    """Install the repren skill for coding agents.
+
+    Writes the skill to both the portable cross-agent surface and the Claude Code
+    mirror, under the resolved root:
+
+    - ``<root>/.agents/skills/repren/SKILL.md`` (portable: Codex, pi, and others)
+    - ``<root>/.claude/skills/repren/SKILL.md`` (Claude Code)
+
+    Args:
+        agent_base: None (default) installs globally under ``$HOME``. Pass a project
+            root (or a ``.claude``/``.agents`` directory inside it) for a project-local
+            install that can be committed and shared with your team.
+    """
+    root, scope_desc = _resolve_root(agent_base)
+
+    # Load and render skill content from package data
     try:
         skill_content = get_skill_content()
     except (ImportError, FileNotFoundError) as e:
@@ -74,32 +125,39 @@ def install_skill(agent_base: str | None = None) -> None:
         print("Install with: uv tool install repren", file=sys.stderr)
         sys.exit(1)
 
-    # Create directory and install
-    try:
-        skill_dir.mkdir(parents=True, exist_ok=True)
-        skill_file = skill_dir / "SKILL.md"
+    # Two surfaces: portable canonical + Claude Code mirror.
+    targets = [
+        ("portable", root / ".agents" / "skills" / "repren" / "SKILL.md"),
+        ("Claude Code", root / ".claude" / "skills" / "repren" / "SKILL.md"),
+    ]
 
-        skill_file.write_text(skill_content, encoding="utf-8")
+    try:
+        written: list[Path] = []
+        for _label, skill_file in targets:
+            skill_file.parent.mkdir(parents=True, exist_ok=True)
+            skill_file.write_text(skill_content, encoding="utf-8")
+            written.append(skill_file)
 
         print("\n" + "=" * 70)
-        print(f"✓ Repren skill installed {location_desc}")
+        print(f"✓ Repren skill installed {scope_desc}")
         print("=" * 70)
-        print(f"\nLocation: {skill_file}")
-        print(f"          ({location_path})")
-        print("\nClaude Code will now automatically use repren for refactoring tasks.")
-        print(f"To uninstall, remove this directory: {skill_dir}")
+        print("\nLocations:")
+        for skill_file in written:
+            print(f"  {skill_file}")
+        print("\nCoding agents will now use repren for refactoring tasks.")
+        print("To uninstall, remove the repren/ directories above.")
 
         # Show tip for project installs (when not using default global location)
         if agent_base is not None:
             print("\n" + "-" * 70)
-            print("Tip: Commit .claude/skills/ to share this skill with your team.")
+            print("Tip: Commit .agents/skills/ and .claude/skills/ to share this with your team.")
             print("-" * 70)
 
         print()  # Blank line for clean output
 
     except PermissionError as e:
         print(f"\n✗ Permission denied: {e}", file=sys.stderr)
-        print(f"\nCould not write to {skill_dir}", file=sys.stderr)
+        print(f"\nCould not write under {root}", file=sys.stderr)
         print("Check directory permissions and try again.", file=sys.stderr)
         sys.exit(1)
     except OSError as e:
@@ -117,13 +175,13 @@ def main() -> None:
     import argparse
 
     parser = argparse.ArgumentParser(
-        description="Install repren Claude Code skill",
+        description="Install repren agent skill",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
-  %(prog)s                        # Install globally (~/.claude/skills)
-  %(prog)s --agent-base ./.claude # Install in current project (./.claude/skills)
-  %(prog)s --agent-base /path     # Install to /path/skills
+  %(prog)s                        # Install globally (under ~)
+  %(prog)s --agent-base .         # Install in current project
+  %(prog)s --agent-base ./.claude # Install in current project (legacy form)
         """,
     )
 
@@ -131,7 +189,7 @@ def main() -> None:
         "--agent-base",
         dest="agent_base",
         metavar="DIR",
-        help="agent config directory (defaults to ~/.claude)",
+        help="project root for a project-local install (defaults to a global install under ~)",
     )
 
     args = parser.parse_args()
diff --git a/repren/repren.py b/repren/repren.py
index e479f53..a27d5f2 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -170,11 +170,16 @@
 
 repren is ideal for use by AI coding agents (Claude Code, Codex, etc.)
 since it is powerful, simple to use, and self-documenting.
-Just tell agents to run `uvx repren@latest --help` and they have everything they need,
-including the ability to install it as a skill.
+Just tell agents to run `repren --help` (or, with no install, `uvx repren@latest --help`)
+and they have everything they need, including the ability to install it as a skill.
 Agents can use `--format=json` for machine-parseable output.
 
-repren includes a built-in skill for Claude Code or other agents.
+repren includes a built-in skill for coding agents. Installing it writes the skill to
+both the portable cross-agent location (`.agents/skills/repren/`, used by Codex, pi, and
+others) and the Claude Code mirror (`.claude/skills/repren/`). repren is a general-purpose
+utility with no per-project config, so the skill invokes it via a pinned zero-install
+runner (`uvx repren@<version>`) and there is no need to add repren as a project
+dependency.
 
 **Install:**
 
@@ -182,15 +187,16 @@
 # Install globally (available in all projects):
 uvx repren --install-skill
 
-# Or install for current project only (shareable via git):
-uvx repren --install-skill --agent-base=./.claude
+# Or install for the current project only (shareable via git):
+uvx repren --install-skill --agent-base=.
 ```
 
-Re-run to update an existing installation.
+Re-run to update an existing installation. The skill pins the repren version it was
+installed from.
 
-**Manual install:** Run `uvx repren --skill` and save to
-`~/.claude/skills/repren/SKILL.md` (global) or `.claude/skills/repren/SKILL.md`
-(project).
+**Manual install:** Run `uvx repren --skill` and save the output to
+`.agents/skills/repren/SKILL.md` (and/or `.claude/skills/repren/SKILL.md`), under `~`
+for a global install or the project root for a project install.
 
 **Learn more:** [Claude Code docs](https://claude.ai/code) and
 [Skills repository](https://github.com/anthropics/skills).
@@ -1330,13 +1336,13 @@ def error(self, message: str) -> NoReturn:
     )
     parser.add_argument(
         "--install-skill",
-        help="install Claude Code skill for repren (by default globally to ~/.claude/skills/repren)",
+        help="install repren agent skill to .agents/ and .claude/ skills dirs (global by default)",
         dest="install_claude_skill",
         action="store_true",
     )
     parser.add_argument(
         "--agent-base",
-        help="agent config directory for skills (e.g., './.claude' for project, defaults to ~/.claude)",
+        help="project root for a project-local skill install (e.g. '.'; defaults to a global install under ~)",
         dest="agent_base",
         metavar="DIR",
     )
@@ -1370,24 +1376,24 @@ def error(self, message: str) -> NoReturn:
         try:
             from .claude_skill import install_skill
 
-            # Install to specified agent base or ~/.claude by default
+            # Install globally (under ~) or, with --agent-base, to a project root.
             install_skill(agent_base=options.agent_base)
             sys.exit(0)
         except ImportError:
             # Fallback if running as standalone script
             print(
-                "Error: Claude skill installation requires full package installation.",
+                "Error: skill installation requires full package installation.",
                 file=sys.stderr,
             )
             print("Install with: uv tool install repren", file=sys.stderr)
             print("", file=sys.stderr)
             print(
-                "Alternative: Download SKILL.md from the repository and install manually:",
+                "Alternative: print the skill and save it manually:",
                 file=sys.stderr,
             )
-            print("  mkdir -p ~/.claude/skills/repren", file=sys.stderr)
+            print("  mkdir -p .agents/skills/repren", file=sys.stderr)
             print(
-                "  curl -o ~/.claude/skills/repren/SKILL.md https://raw.githubusercontent.com/jlevy/repren/master/repren/skills/SKILL.md",
+                "  uvx repren --skill > .agents/skills/repren/SKILL.md",
                 file=sys.stderr,
             )
             sys.exit(1)
@@ -1406,11 +1412,11 @@ def error(self, message: str) -> NoReturn:
             print("Install with: uv tool install repren", file=sys.stderr)
             print("", file=sys.stderr)
             print(
-                "Alternative: Download SKILL.md directly from the repository:",
+                "Alternative: run the skill printer from a packaged install:",
                 file=sys.stderr,
             )
             print(
-                "  curl https://raw.githubusercontent.com/jlevy/repren/master/repren/skills/SKILL.md",
+                "  uvx repren --skill",
                 file=sys.stderr,
             )
             sys.exit(1)
diff --git a/repren/skills/SKILL.md b/repren/skills/SKILL.md
index 78c47ab..821096c 100644
--- a/repren/skills/SKILL.md
+++ b/repren/skills/SKILL.md
@@ -1,12 +1,16 @@
 ---
 name: repren
 description: Performs simultaneous multi-pattern search-and-replace, file/directory renaming, and case-preserving refactoring across codebases. Use for bulk refactoring, global find-and-replace, or when user mentions repren, multi-file rename, or pattern-based transformations.
-allowed-tools: Bash(repren:*), Bash(uvx repren@latest:*), Read, Write
+allowed-tools: Bash(repren:*), Bash(uvx repren@{{REPREN_VERSION}}:*), Read, Write
 ---
 # Repren - Multi-Pattern Search and Replace
 
-> **Full documentation: Run `uvx repren@latest --docs` for all options, flags, and
-> advanced usage.**
+> **Invocation:** The examples below call `repren` directly, which assumes it is on your
+> `PATH` (e.g. installed via `uv tool install repren`). If `repren` is not installed,
+> replace `repren` with the pinned zero-install runner `uvx repren@{{REPREN_VERSION}}` in
+> every command — it needs no prior install and pins a known version.
+>
+> **Full documentation:** Run `repren --docs` for all options, flags, and advanced usage.
 
 Multi-pattern search/replace tool for bulk refactoring with simultaneous replacements,
 file/directory renaming, and case-preserving transformations.
@@ -15,12 +19,12 @@ file/directory renaming, and case-preserving transformations.
 
 **Always start with dry-run** to preview changes:
 ```bash
-uvx repren@latest --from='old_name' --to='new_name' --full --dry-run src/
+repren --from='old_name' --to='new_name' --full --dry-run src/
 ```
 
 Then execute if output looks correct:
 ```bash
-uvx repren@latest --from='old_name' --to='new_name' --full src/
+repren --from='old_name' --to='new_name' --full src/
 ```
 
 ## When to Use Repren
@@ -51,7 +55,7 @@ CONSTANT_OLD	CONSTANT_NEW
 
 Apply all patterns at once:
 ```bash
-uvx repren@latest --patterns=patterns.txt --full src/
+repren --patterns=patterns.txt --full src/
 ```
 
 Repren handles overlapping patterns intelligently: you can swap names (foo↔bar) in a
@@ -61,7 +65,7 @@ single pass.
 
 Handle all case variants automatically:
 ```bash
-uvx repren@latest --from='my_var' --to='my_function' --preserve-case --full src/
+repren --from='my_var' --to='my_function' --preserve-case --full src/
 ```
 
 Transforms: `my_var`→`my_function`, `myVar`→`myFunction`, `MyVar`→`MyFunction`,
@@ -73,7 +77,7 @@ With `--full`, in addition to searching and replacing content, repren will renam
 and directories matching the patterns.
 
 ```bash
-uvx repren@latest --from='old_module' --to='new_module' --full src/
+repren --from='old_module' --to='new_module' --full src/
 ```
 
 Renames files and directories, creating parent directories as needed. Files never
@@ -83,7 +87,7 @@ clobber: numeric suffixes are added if conflicts arise.
 
 Use full Python regex syntax with backreferences:
 ```bash
-uvx repren@latest --from='figure ([0-9]+)' --to='Figure \1' --full docs/
+repren --from='figure ([0-9]+)' --to='Figure \1' --full docs/
 ```
 
 Pattern file example:
@@ -103,7 +107,7 @@ truncated on errors.
 
 **Always preview changes first:**
 ```bash
-uvx repren@latest --dry-run --patterns=patterns.txt --full mydir/
+repren --dry-run --patterns=patterns.txt --full mydir/
 ```
 
 Shows exactly what would change without modifying files.
@@ -112,14 +116,14 @@ Shows exactly what would change without modifying files.
 
 Restore from backups if needed:
 ```bash
-uvx repren@latest --undo --from='old' --to='new' --full src/
+repren --undo --from='old' --to='new' --full src/
 ```
 
 ### Clean Backups
 
 Remove backups when satisfied:
 ```bash
-uvx repren@latest --clean-backups src/
+repren --clean-backups src/
 ```
 
 ## Common Workflows
@@ -128,64 +132,64 @@ uvx repren@latest --clean-backups src/
 
 1. Preview changes:
 ```bash
-uvx repren@latest --from='OldName' --to='NewName' --preserve-case --word-breaks --full --dry-run src/
+repren --from='OldName' --to='NewName' --preserve-case --word-breaks --full --dry-run src/
 ```
 
 2. Execute if output looks correct:
 ```bash
-uvx repren@latest --from='OldName' --to='NewName' --preserve-case --word-breaks --full src/
+repren --from='OldName' --to='NewName' --preserve-case --word-breaks --full src/
 ```
 
 3. Review changes, test, then clean backups:
 ```bash
-uvx repren@latest --clean-backups src/
+repren --clean-backups src/
 ```
 
 ### Filtering Files
 
 Include only specific file types:
 ```bash
-uvx repren@latest --patterns=patterns.txt --include='.*\.(py|pyi)$' --full src/
+repren --patterns=patterns.txt --include='.*\.(py|pyi)$' --full src/
 ```
 
 Exclude directories:
 ```bash
-uvx repren@latest --patterns=patterns.txt --exclude='tests|node_modules|__pycache__' --full src/
+repren --patterns=patterns.txt --exclude='tests|node_modules|__pycache__' --full src/
 ```
 
 ### Word Boundaries
 
 Match only at word boundaries (safer for variable names):
 ```bash
-uvx repren@latest --from='var' --to='variable' --word-breaks --full src/
+repren --from='var' --to='variable' --word-breaks --full src/
 ```
 
 ### Literal Patterns
 
 Treat patterns as literal strings (not regex):
 ```bash
-uvx repren@latest --from='file.txt' --to='data.txt' --literal --full docs/
+repren --from='file.txt' --to='data.txt' --literal --full docs/
 ```
 
 ### Multi-Line Patterns
 
 Process entire files at once for patterns spanning lines:
 ```bash
-uvx repren@latest --patterns=patterns.txt --at-once --full src/
+repren --patterns=patterns.txt --at-once --full src/
 ```
 
 ## Machine-Readable Output
 
 Use JSON format for programmatic processing:
 ```bash
-uvx repren@latest --format=json --from='old' --to='new' --full src/
+repren --format=json --from='old' --to='new' --full src/
 ```
 
 Returns structured data about all changes made.
 
 ## Key Flags
 
-Most important flags (run `uvx repren@latest --docs` for complete list):
+Most important flags (run `repren --docs` for complete list):
 
 | Flag | Purpose |
 | --- | --- |
diff --git a/tests/pytests.py b/tests/pytests.py
index 1d16960..35a1bd6 100644
--- a/tests/pytests.py
+++ b/tests/pytests.py
@@ -520,6 +520,22 @@ def test_skill_content_has_required_sections(self):
         # Should mention key features
         assert "pattern" in content.lower() or "replace" in content.lower()
 
+    def test_skill_content_pins_version_no_latest(self):
+        """Rendered skill should pin the installed version, not use an unpinned @latest."""
+        from repren.claude_skill import VERSION_PLACEHOLDER, get_skill_content
+        from repren.repren import VERSION
+
+        content = get_skill_content()
+
+        # Placeholder must be rendered away.
+        assert VERSION_PLACEHOLDER not in content
+        # Unpinned runner must not appear (supply-chain hygiene).
+        assert "repren@latest" not in content
+        # The pinned zero-install fallback must reference the installed public version
+        # (any PEP 440 local "+..." segment is dropped, since it is not installable).
+        pinned_version = VERSION.split("+", 1)[0]
+        assert f"uvx repren@{pinned_version}" in content
+
 
 class TestClaudeSkillInstallation:
     """Tests for Claude skill installation."""
@@ -538,28 +554,45 @@ def test_install_skill_global_creates_file(self):
             try:
                 install_skill()  # Default is global (uses HOME)
 
-                skill_file = Path(tmpdir) / ".claude" / "skills" / "repren" / "SKILL.md"
-                assert skill_file.exists()
-                content = skill_file.read_text()
+                # Both surfaces are written: portable and the Claude Code mirror.
+                claude_file = Path(tmpdir) / ".claude" / "skills" / "repren" / "SKILL.md"
+                agents_file = Path(tmpdir) / ".agents" / "skills" / "repren" / "SKILL.md"
+                assert claude_file.exists()
+                assert agents_file.exists()
+                content = claude_file.read_text()
                 assert "repren" in content.lower()
+                assert content == agents_file.read_text()
             finally:
                 if old_home:
                     os.environ["HOME"] = old_home
 
     def test_install_skill_project_creates_file(self):
-        """install_skill with agent_base should create file in specified location."""
+        """install_skill with agent_base should create both surfaces under the project root."""
         from repren.claude_skill import install_skill
 
         with tempfile.TemporaryDirectory() as tmpdir:
-            # agent_base IS the .claude directory itself
+            # Legacy form: agent_base is the .claude directory itself; its parent
+            # (the project root) anchors both surfaces.
             agent_base = Path(tmpdir) / ".claude"
             install_skill(agent_base=str(agent_base))
 
-            skill_file = agent_base / "skills" / "repren" / "SKILL.md"
-            assert skill_file.exists()
-            content = skill_file.read_text()
+            claude_file = Path(tmpdir) / ".claude" / "skills" / "repren" / "SKILL.md"
+            agents_file = Path(tmpdir) / ".agents" / "skills" / "repren" / "SKILL.md"
+            assert claude_file.exists()
+            assert agents_file.exists()
+            content = claude_file.read_text()
             assert "repren" in content.lower()
 
+    def test_install_skill_project_root_creates_file(self):
+        """install_skill with a plain project root should create both surfaces under it."""
+        from repren.claude_skill import install_skill
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            install_skill(agent_base=tmpdir)
+
+            assert (Path(tmpdir) / ".agents" / "skills" / "repren" / "SKILL.md").exists()
+            assert (Path(tmpdir) / ".claude" / "skills" / "repren" / "SKILL.md").exists()
+
     def test_install_skill_content_matches_package(self):
         """Installed skill content should match package content."""
         from repren.claude_skill import get_skill_content, install_skill
diff --git a/tests/tryscript/advanced-options.tryscript.md b/tests/tryscript/advanced-options.tryscript.md
index 8ed1432..4f77e07 100644
--- a/tests/tryscript/advanced-options.tryscript.md
+++ b/tests/tryscript/advanced-options.tryscript.md
@@ -83,27 +83,41 @@ usage: repren [-h] [--version] [--docs] [--from FROM_PAT] [--to TO_PAT] [-p PAT_
 ? 0
 ```
 
-## A6: `--install-skill` with `--agent-base` writes expected project-local artifacts
+## A6: `--install-skill` with `--agent-base` writes both skill surfaces project-locally
 
 ```console
 $ mkdir -p agentrepo && repren --install-skill --agent-base ./agentrepo/.claude >/dev/null
 ```
 
+The skill is written to both the portable cross-agent location and the Claude mirror:
+
 ```console
-$ find agentrepo/.claude -maxdepth 3 -type f | sort
+$ find agentrepo -type f -name SKILL.md | sort
+agentrepo/.agents/skills/repren/SKILL.md
 agentrepo/.claude/skills/repren/SKILL.md
 ? 0
 ```
 
+Frontmatter (stable top lines, version-independent):
+
 ```console
-$ sed -n '1,8p' agentrepo/.claude/skills/repren/SKILL.md
+$ sed -n '1,3p' agentrepo/.claude/skills/repren/SKILL.md
 ---
 name: repren
 description: Performs simultaneous multi-pattern search-and-replace, file/directory renaming, and case-preserving refactoring across codebases. Use for bulk refactoring, global find-and-replace, or when user mentions repren, multi-file rename, or pattern-based transformations.
-allowed-tools: Bash(repren:*), Bash(uvx repren@latest:*), Read, Write
----
-# Repren - Multi-Pattern Search and Replace
+? 0
+```
+
+The skill uses a pinned zero-install runner, never an unpinned `@latest`:
 
-> **Full documentation: Run `uvx repren@latest --docs` for all options, flags, and
+```console
+$ grep -q 'repren@latest' agentrepo/.claude/skills/repren/SKILL.md && echo found || echo none
+none
+? 0
+```
+
+```console
+$ grep -Eq 'uvx repren@[0-9]' agentrepo/.claude/skills/repren/SKILL.md && echo pinned
+pinned
 ? 0
 ```

From 2db3902616600044e48ba1fcab34d32c46fefc3f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 05:27:23 +0000
Subject: [PATCH 03/18] feat!: resolve skill install scope with
 --project/--global (git config-style)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

BREAKING CHANGE: replace `--install-skill --agent-base DIR` with explicit
`--project` / `--global` scope flags, following the cli-agent-skill-patterns
§6.6.2 model for dual-scope tools. repren carries no per-project config, so it
is a dual-scope skill (project or global), and scope is now resolved like
`git config`: implicit when unambiguous, a hard error when not.

- New flags on --install-skill: --project, --global, --dir DIR, --no-repo-check.
- Inside a git repo, scope is implicitly --project. In an ambiguous location
  (home dir, filesystem root, or outside any repo) repren refuses before writing
  and names the flag to pass, instead of silently writing global agent surfaces.
- --project always refuses $HOME (that is what --global is for); the resolved
  target is printed before writing so a wrong scope can be cancelled.
- Both surfaces (.agents/skills/repren/ and .claude/skills/repren/) are still
  written under the resolved root.
- claude_skill exposes resolve_install_target() + SkillScopeError for testing;
  install_skill() now takes project/global_install/dir/no_repo_check.

Migration: `--install-skill` (old global default) -> `--install-skill --global`;
`--install-skill --agent-base=./.claude` -> `--install-skill --project` (run from
the repo) or `--install-skill --project --dir PATH`. To be noted in release notes.

Updated docstring, README, CLI help, tests (scope-resolution unit tests + golden
A6/A7), and the golden coverage gate.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 README.md                                     |  16 +-
 repren/claude_skill.py                        | 220 ++++++++++++++----
 repren/repren.py                              |  71 ++++--
 scripts/check-golden-coverage.sh              |   3 +-
 tests/pytests.py                              | 162 +++++++++----
 tests/tryscript/advanced-options.tryscript.md |  23 +-
 tests/tryscript/help-errors.tryscript.md      |   6 +-
 7 files changed, 381 insertions(+), 120 deletions(-)

diff --git a/README.md b/README.md
index 33f4057..3d12080 100644
--- a/README.md
+++ b/README.md
@@ -194,16 +194,24 @@ utility with no per-project config, so the skill invokes it via a pinned zero-in
 runner (`uvx repren@<version>`) and there is no need to add repren as a project
 dependency.
 
+repren is a dual-scope skill: install it into a single project or globally for your
+user. Scope is resolved like `git config` — implicit when unambiguous, an error when
+not — so a stray `--install-skill` never silently rewrites your global agent surfaces.
+
 **Install:**
 
 ```bash
-# Install globally (available in all projects):
-uvx repren --install-skill
+# Install into the current project (run from the repo; shareable via git):
+uvx repren --install-skill --project
 
-# Or install for the current project only (shareable via git):
-uvx repren --install-skill --agent-base=.
+# Install globally (available in all projects):
+uvx repren --install-skill --global
 ```
 
+Inside a git repo, `--project` is implied, so `uvx repren --install-skill` installs into
+the project. Outside a repo (or in your home directory) the scope is ambiguous and you
+must pass `--project` (optionally with `--dir DIR` or `--no-repo-check`) or `--global`.
+
 Re-run to update an existing installation. The skill pins the repren version it was
 installed from.
 
diff --git a/repren/claude_skill.py b/repren/claude_skill.py
index 6c82517..ff7784c 100644
--- a/repren/claude_skill.py
+++ b/repren/claude_skill.py
@@ -3,8 +3,12 @@
 
 This module installs the repren skill for coding agents. The skill is written to
 both the portable cross-agent location (`.agents/skills/repren/`) and the Claude Code
-mirror (`.claude/skills/repren/`), either globally (under ``$HOME``) or within a
-specific project.
+mirror (`.claude/skills/repren/`).
+
+repren is a general-purpose utility with no per-project configuration, so it is a
+dual-scope skill: it can be installed into a single project or globally for the user.
+Scope is resolved `git config`-style — implicit when unambiguous, a hard error when not
+(see `resolve_install_target`).
 
 The skill text in ``skills/SKILL.md`` is a template: the ``{{REPREN_VERSION}}``
 placeholder is replaced with the installed repren version so the skill's pinned
@@ -12,11 +16,22 @@
 """
 
 import sys
+from dataclasses import dataclass
 from pathlib import Path
 
 # Placeholder in skills/SKILL.md replaced with the installed repren version at render time.
 VERSION_PLACEHOLDER = "{{REPREN_VERSION}}"
 
+# Surfaces the skill is written to, beneath the resolved install root.
+SKILL_SURFACES: list[tuple[str, str]] = [
+    ("portable", ".agents"),  # cross-agent: Codex, Gemini CLI, pi, others
+    ("claude", ".claude"),  # Claude Code mirror
+]
+
+
+class SkillScopeError(Exception):
+    """Raised when the skill install scope cannot be resolved unambiguously."""
+
 
 def _pinned_version() -> str:
     """Return the installed repren version suitable for a ``uvx repren@<version>`` pin.
@@ -74,49 +89,132 @@ def get_skill_content() -> str:
     return _render_skill(template)
 
 
-def _resolve_root(agent_base: str | None) -> tuple[Path, str]:
-    """Resolve the root directory the skill surfaces are installed under.
+@dataclass
+class InstallTarget:
+    """A resolved skill install location.
 
-    The skill is always written to two surfaces beneath the returned root:
-    ``<root>/.agents/skills/repren/`` (portable, cross-agent) and
-    ``<root>/.claude/skills/repren/`` (Claude Code mirror).
+    Attributes:
+        root: The directory the skill surfaces are written beneath.
+        mode: Either ``"project"`` or ``"global"``.
+    """
 
-    Args:
-        agent_base: None for a global install (under ``$HOME``). Otherwise the project
-            root, or — for backward compatibility — a ``.claude``/``.agents`` directory
-            whose parent is taken as the project root.
+    root: Path
+    mode: str
 
-    Returns:
-        A ``(root, scope_description)`` tuple.
-    """
-    if agent_base is None:
-        return Path.home(), "globally (under ~)"
 
-    resolved = Path(agent_base).resolve()
-    # Backward compatibility: callers historically passed the `.claude` dir itself
-    # (e.g. `--agent-base ./.claude`). Treat such a path as "the project is its parent".
-    if resolved.name in (".agents", ".claude"):
-        resolved = resolved.parent
-    return resolved, f"to project {resolved}"
+def _in_git_repo(path: Path) -> bool:
+    """Return True if ``path`` is inside a git repository (a ``.git`` exists at or above)."""
+    for candidate in (path, *path.parents):
+        if (candidate / ".git").exists():
+            return True
+    return False
+
 
+def resolve_install_target(
+    *,
+    project: bool = False,
+    global_install: bool = False,
+    dir: str | None = None,
+    no_repo_check: bool = False,
+    cwd: Path | None = None,
+    home: Path | None = None,
+) -> InstallTarget:
+    """Resolve where to install the skill, copying the ``git config`` scope model.
 
-def install_skill(agent_base: str | None = None) -> None:
-    """Install the repren skill for coding agents.
+    Scope is implicit when unambiguous and a hard error when not, so that
+    ``cd ~ && repren --install-skill`` never silently rewrites the user's global agent
+    surfaces.
+
+    Args:
+        project: Force a project-local install.
+        global_install: Force a user-global install under ``$HOME``.
+        dir: Explicit project root (implies project mode); mutually exclusive with
+            ``global_install``.
+        no_repo_check: Allow a project install when ``cwd`` is not inside a git repo.
+        cwd: Override the current directory (for testing).
+        home: Override the home directory (for testing).
 
-    Writes the skill to both the portable cross-agent surface and the Claude Code
-    mirror, under the resolved root:
+    Returns:
+        The resolved :class:`InstallTarget`.
 
-    - ``<root>/.agents/skills/repren/SKILL.md`` (portable: Codex, pi, and others)
+    Raises:
+        SkillScopeError: If the scope is ambiguous or the request is contradictory.
+    """
+    cwd = (cwd or Path.cwd()).resolve()
+    home = (home or Path.home()).resolve()
+
+    if project and global_install:
+        raise SkillScopeError("--project and --global are mutually exclusive.")
+    if global_install and dir is not None:
+        raise SkillScopeError("--global and --dir are mutually exclusive.")
+
+    # Resolve the scope mode.
+    if global_install:
+        mode = "global"
+    elif project or dir is not None:
+        mode = "project"
+    else:
+        # Implicit scope (the git config rule): resolve before writing anything.
+        if cwd == home or cwd == Path(cwd.anchor):
+            raise SkillScopeError(f"ambiguous install scope in {cwd}: pass --project or --global.")
+        if _in_git_repo(cwd):
+            mode = "project"
+        else:
+            raise SkillScopeError(
+                f"{cwd} is not inside a git repository: pass "
+                "--project --no-repo-check to install here anyway, or --global."
+            )
+
+    if mode == "global":
+        return InstallTarget(root=home, mode="global")
+
+    # Project mode.
+    root = Path(dir).resolve() if dir is not None else cwd
+    if root == home:
+        # --project --dir ~ is always refused; that is exactly what --global is for.
+        raise SkillScopeError(
+            f"--project: refusing to install into {root} (home directory). "
+            "That would write to your global agent surfaces. Use --global instead."
+        )
+    if dir is None and not no_repo_check and not _in_git_repo(root):
+        raise SkillScopeError(
+            f"--project: {root} is not inside a git repository. "
+            "Pass --no-repo-check to install here anyway, or --global."
+        )
+    return InstallTarget(root=root, mode="project")
+
+
+def install_skill(
+    *,
+    project: bool = False,
+    global_install: bool = False,
+    dir: str | None = None,
+    no_repo_check: bool = False,
+) -> None:
+    """Resolve the install scope and write the repren skill to both surfaces.
+
+    Writes the skill under the resolved root:
+
+    - ``<root>/.agents/skills/repren/SKILL.md`` (portable: Codex, Gemini, pi, others)
     - ``<root>/.claude/skills/repren/SKILL.md`` (Claude Code)
 
     Args:
-        agent_base: None (default) installs globally under ``$HOME``. Pass a project
-            root (or a ``.claude``/``.agents`` directory inside it) for a project-local
-            install that can be committed and shared with your team.
+        project: Force a project-local install.
+        global_install: Force a user-global install under ``$HOME``.
+        dir: Explicit project root (implies project mode).
+        no_repo_check: Allow a project install outside a git repository.
+
+    Raises:
+        SkillScopeError: If the scope cannot be resolved unambiguously.
     """
-    root, scope_desc = _resolve_root(agent_base)
+    target = resolve_install_target(
+        project=project,
+        global_install=global_install,
+        dir=dir,
+        no_repo_check=no_repo_check,
+    )
 
-    # Load and render skill content from package data
+    # Load and render skill content from package data.
     try:
         skill_content = get_skill_content()
     except (ImportError, FileNotFoundError) as e:
@@ -125,21 +223,25 @@ def install_skill(agent_base: str | None = None) -> None:
         print("Install with: uv tool install repren", file=sys.stderr)
         sys.exit(1)
 
-    # Two surfaces: portable canonical + Claude Code mirror.
+    surface_names = ", ".join(name for name, _ in SKILL_SURFACES)
     targets = [
-        ("portable", root / ".agents" / "skills" / "repren" / "SKILL.md"),
-        ("Claude Code", root / ".claude" / "skills" / "repren" / "SKILL.md"),
+        (name, target.root / parent / "skills" / "repren" / "SKILL.md")
+        for name, parent in SKILL_SURFACES
     ]
 
+    # Print the resolved target before writing, so the user can ctrl-c if it is wrong.
+    print(f"\nInstalling repren skill ({target.mode} mode) into: {target.root}")
+    print(f"  surfaces: {surface_names}")
+
     try:
         written: list[Path] = []
-        for _label, skill_file in targets:
+        for _name, skill_file in targets:
             skill_file.parent.mkdir(parents=True, exist_ok=True)
             skill_file.write_text(skill_content, encoding="utf-8")
             written.append(skill_file)
 
         print("\n" + "=" * 70)
-        print(f"✓ Repren skill installed {scope_desc}")
+        print(f"✓ Repren skill installed ({target.mode} mode)")
         print("=" * 70)
         print("\nLocations:")
         for skill_file in written:
@@ -147,8 +249,7 @@ def install_skill(agent_base: str | None = None) -> None:
         print("\nCoding agents will now use repren for refactoring tasks.")
         print("To uninstall, remove the repren/ directories above.")
 
-        # Show tip for project installs (when not using default global location)
-        if agent_base is not None:
+        if target.mode == "project":
             print("\n" + "-" * 70)
             print("Tip: Commit .agents/skills/ and .claude/skills/ to share this with your team.")
             print("-" * 70)
@@ -157,7 +258,7 @@ def install_skill(agent_base: str | None = None) -> None:
 
     except PermissionError as e:
         print(f"\n✗ Permission denied: {e}", file=sys.stderr)
-        print(f"\nCould not write under {root}", file=sys.stderr)
+        print(f"\nCould not write under {target.root}", file=sys.stderr)
         print("Check directory permissions and try again.", file=sys.stderr)
         sys.exit(1)
     except OSError as e:
@@ -169,8 +270,9 @@ def main() -> None:
     """Command-line interface for skill installation.
 
     Can be run directly for testing:
-        python -m repren.claude_skill
-        python -m repren.claude_skill --agent-base ./.claude
+        python -m repren.claude_skill --project
+        python -m repren.claude_skill --global
+        python -m repren.claude_skill --project --dir /path/to/repo
     """
     import argparse
 
@@ -178,23 +280,41 @@ def main() -> None:
         description="Install repren agent skill",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
+Scope is resolved like `git config`: implicit when unambiguous, an error when not.
+
 Examples:
-  %(prog)s                        # Install globally (under ~)
-  %(prog)s --agent-base .         # Install in current project
-  %(prog)s --agent-base ./.claude # Install in current project (legacy form)
+  %(prog)s --project              # Install into the current project
+  %(prog)s --global               # Install globally (under ~)
+  %(prog)s --project --dir REPO   # Install into a specific project root
         """,
     )
 
+    parser.add_argument("--project", action="store_true", help="install into the current project")
     parser.add_argument(
-        "--agent-base",
-        dest="agent_base",
-        metavar="DIR",
-        help="project root for a project-local install (defaults to a global install under ~)",
+        "--global",
+        dest="global_install",
+        action="store_true",
+        help="install globally under ~",
+    )
+    parser.add_argument("--dir", metavar="DIR", help="explicit project root (implies --project)")
+    parser.add_argument(
+        "--no-repo-check",
+        dest="no_repo_check",
+        action="store_true",
+        help="allow --project outside a git repository",
     )
 
     args = parser.parse_args()
 
-    install_skill(agent_base=args.agent_base)
+    try:
+        install_skill(
+            project=args.project,
+            global_install=args.global_install,
+            dir=args.dir,
+            no_repo_check=args.no_repo_check,
+        )
+    except SkillScopeError as e:
+        parser.error(str(e))
 
 
 if __name__ == "__main__":
diff --git a/repren/repren.py b/repren/repren.py
index a27d5f2..e94de04 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -181,16 +181,24 @@
 runner (`uvx repren@<version>`) and there is no need to add repren as a project
 dependency.
 
+repren is a dual-scope skill: install it into a single project or globally for your
+user. Scope is resolved like `git config` — implicit when unambiguous, an error when
+not — so a stray `--install-skill` never silently rewrites your global agent surfaces.
+
 **Install:**
 
 ```bash
-# Install globally (available in all projects):
-uvx repren --install-skill
+# Install into the current project (run from the repo; shareable via git):
+uvx repren --install-skill --project
 
-# Or install for the current project only (shareable via git):
-uvx repren --install-skill --agent-base=.
+# Install globally (available in all projects):
+uvx repren --install-skill --global
 ```
 
+Inside a git repo, `--project` is implied, so `uvx repren --install-skill` installs into
+the project. Outside a repo (or in your home directory) the scope is ambiguous and you
+must pass `--project` (optionally with `--dir DIR` or `--no-repo-check`) or `--global`.
+
 Re-run to update an existing installation. The skill pins the repren version it was
 installed from.
 
@@ -1336,16 +1344,34 @@ def error(self, message: str) -> NoReturn:
     )
     parser.add_argument(
         "--install-skill",
-        help="install repren agent skill to .agents/ and .claude/ skills dirs (global by default)",
+        help="install repren agent skill (.agents/ and .claude/ skill dirs); see --project/--global",
         dest="install_claude_skill",
         action="store_true",
     )
     parser.add_argument(
-        "--agent-base",
-        help="project root for a project-local skill install (e.g. '.'; defaults to a global install under ~)",
-        dest="agent_base",
+        "--project",
+        help="with --install-skill: install into the current project",
+        dest="skill_project",
+        action="store_true",
+    )
+    parser.add_argument(
+        "--global",
+        help="with --install-skill: install globally under ~",
+        dest="skill_global",
+        action="store_true",
+    )
+    parser.add_argument(
+        "--dir",
+        help="with --install-skill: explicit project root (implies --project)",
+        dest="skill_dir",
         metavar="DIR",
     )
+    parser.add_argument(
+        "--no-repo-check",
+        help="with --install-skill --project: allow installing outside a git repo",
+        dest="skill_no_repo_check",
+        action="store_true",
+    )
     parser.add_argument(
         "--skill",
         help="print coding agent skill instructions (SKILL.md content)",
@@ -1371,14 +1397,20 @@ def error(self, message: str) -> NoReturn:
 
     options = parser.parse_args()
 
-    # Handle Claude skill installation (early exit)
+    # The skill scope flags only apply to --install-skill.
+    skill_scope_requested = (
+        options.skill_project
+        or options.skill_global
+        or options.skill_dir is not None
+        or options.skill_no_repo_check
+    )
+    if skill_scope_requested and not options.install_claude_skill:
+        parser.error("--project/--global/--dir/--no-repo-check require --install-skill")
+
+    # Handle skill installation (early exit)
     if options.install_claude_skill:
         try:
-            from .claude_skill import install_skill
-
-            # Install globally (under ~) or, with --agent-base, to a project root.
-            install_skill(agent_base=options.agent_base)
-            sys.exit(0)
+            from .claude_skill import SkillScopeError, install_skill
         except ImportError:
             # Fallback if running as standalone script
             print(
@@ -1398,6 +1430,17 @@ def error(self, message: str) -> NoReturn:
             )
             sys.exit(1)
 
+        try:
+            install_skill(
+                project=options.skill_project,
+                global_install=options.skill_global,
+                dir=options.skill_dir,
+                no_repo_check=options.skill_no_repo_check,
+            )
+            sys.exit(0)
+        except SkillScopeError as e:
+            parser.error(str(e))
+
     # Handle skill instructions output (early exit)
     if options.skill_instructions:
         try:
diff --git a/scripts/check-golden-coverage.sh b/scripts/check-golden-coverage.sh
index 69ea822..51fdcd1 100755
--- a/scripts/check-golden-coverage.sh
+++ b/scripts/check-golden-coverage.sh
@@ -94,7 +94,8 @@ check_pattern "clean backups" "--clean-backups"
 check_pattern "backup suffix" "--backup-suffix"
 check_pattern "json mode" "--format json"
 check_pattern "install skill" "--install-skill"
-check_pattern "agent base" "--agent-base"
+check_pattern "skill project scope" "--project"
+check_pattern "skill dir" "--dir"
 
 echo ""
 FILE_COUNT=$(find "$TESTS_DIR" -name "*.tryscript.md" | wc -l | tr -d ' ')
diff --git a/tests/pytests.py b/tests/pytests.py
index 35a1bd6..2b8f02a 100644
--- a/tests/pytests.py
+++ b/tests/pytests.py
@@ -537,24 +537,89 @@ def test_skill_content_pins_version_no_latest(self):
         assert f"uvx repren@{pinned_version}" in content
 
 
+class TestClaudeSkillScopeResolution:
+    """Tests for the git-config-style install scope resolution."""
+
+    def test_explicit_global(self):
+        from repren.claude_skill import resolve_install_target
+
+        home = Path("/home/someone")
+        target = resolve_install_target(global_install=True, home=home, cwd=Path("/tmp/x"))
+        assert target.mode == "global"
+        assert target.root == home
+
+    def test_explicit_project_with_dir(self):
+        from repren.claude_skill import resolve_install_target
+
+        target = resolve_install_target(dir="/tmp/repo", home=Path("/home/someone"))
+        assert target.mode == "project"
+        assert target.root == Path("/tmp/repo").resolve()
+
+    def test_implicit_project_inside_repo(self, tmp_path):
+        """Inside a git repo, scope is implicitly project."""
+        from repren.claude_skill import resolve_install_target
+
+        (tmp_path / ".git").mkdir()
+        target = resolve_install_target(cwd=tmp_path, home=Path("/home/someone"))
+        assert target.mode == "project"
+        assert target.root == tmp_path
+
+    def test_ambiguous_outside_repo_errors(self, tmp_path):
+        from repren.claude_skill import SkillScopeError, resolve_install_target
+
+        with pytest.raises(SkillScopeError, match="not inside a git repository"):
+            resolve_install_target(cwd=tmp_path, home=Path("/home/someone"))
+
+    def test_project_no_repo_check_allows_non_repo(self, tmp_path):
+        from repren.claude_skill import resolve_install_target
+
+        target = resolve_install_target(
+            project=True, no_repo_check=True, cwd=tmp_path, home=Path("/home/someone")
+        )
+        assert target.mode == "project"
+        assert target.root == tmp_path
+
+    def test_home_is_refused_in_project_mode(self, tmp_path):
+        from repren.claude_skill import SkillScopeError, resolve_install_target
+
+        with pytest.raises(SkillScopeError, match="home directory"):
+            resolve_install_target(dir=str(tmp_path), home=tmp_path)
+
+    def test_cwd_home_is_ambiguous(self, tmp_path):
+        from repren.claude_skill import SkillScopeError, resolve_install_target
+
+        with pytest.raises(SkillScopeError, match="ambiguous"):
+            resolve_install_target(cwd=tmp_path, home=tmp_path)
+
+    def test_project_and_global_mutually_exclusive(self):
+        from repren.claude_skill import SkillScopeError, resolve_install_target
+
+        with pytest.raises(SkillScopeError, match="mutually exclusive"):
+            resolve_install_target(project=True, global_install=True)
+
+    def test_global_and_dir_mutually_exclusive(self):
+        from repren.claude_skill import SkillScopeError, resolve_install_target
+
+        with pytest.raises(SkillScopeError, match="mutually exclusive"):
+            resolve_install_target(global_install=True, dir="/tmp/x")
+
+
 class TestClaudeSkillInstallation:
     """Tests for Claude skill installation."""
 
-    def test_install_skill_global_creates_file(self):
-        """install_skill with global scope should create file in ~/.claude/skills."""
+    def test_install_skill_global_creates_both_surfaces(self):
+        """A global install writes both surfaces under $HOME."""
         from repren.claude_skill import install_skill
 
         with tempfile.TemporaryDirectory() as tmpdir:
-            # Mock HOME to use temp directory
             import os
 
             old_home = os.environ.get("HOME")
             os.environ["HOME"] = tmpdir
 
             try:
-                install_skill()  # Default is global (uses HOME)
+                install_skill(global_install=True)
 
-                # Both surfaces are written: portable and the Claude Code mirror.
                 claude_file = Path(tmpdir) / ".claude" / "skills" / "repren" / "SKILL.md"
                 agents_file = Path(tmpdir) / ".agents" / "skills" / "repren" / "SKILL.md"
                 assert claude_file.exists()
@@ -566,29 +631,12 @@ def test_install_skill_global_creates_file(self):
                 if old_home:
                     os.environ["HOME"] = old_home
 
-    def test_install_skill_project_creates_file(self):
-        """install_skill with agent_base should create both surfaces under the project root."""
+    def test_install_skill_project_dir_creates_both_surfaces(self):
+        """A project install with --dir writes both surfaces under that root."""
         from repren.claude_skill import install_skill
 
         with tempfile.TemporaryDirectory() as tmpdir:
-            # Legacy form: agent_base is the .claude directory itself; its parent
-            # (the project root) anchors both surfaces.
-            agent_base = Path(tmpdir) / ".claude"
-            install_skill(agent_base=str(agent_base))
-
-            claude_file = Path(tmpdir) / ".claude" / "skills" / "repren" / "SKILL.md"
-            agents_file = Path(tmpdir) / ".agents" / "skills" / "repren" / "SKILL.md"
-            assert claude_file.exists()
-            assert agents_file.exists()
-            content = claude_file.read_text()
-            assert "repren" in content.lower()
-
-    def test_install_skill_project_root_creates_file(self):
-        """install_skill with a plain project root should create both surfaces under it."""
-        from repren.claude_skill import install_skill
-
-        with tempfile.TemporaryDirectory() as tmpdir:
-            install_skill(agent_base=tmpdir)
+            install_skill(dir=tmpdir)
 
             assert (Path(tmpdir) / ".agents" / "skills" / "repren" / "SKILL.md").exists()
             assert (Path(tmpdir) / ".claude" / "skills" / "repren" / "SKILL.md").exists()
@@ -598,22 +646,13 @@ def test_install_skill_content_matches_package(self):
         from repren.claude_skill import get_skill_content, install_skill
 
         with tempfile.TemporaryDirectory() as tmpdir:
-            import os
+            install_skill(dir=tmpdir)
 
-            old_home = os.environ.get("HOME")
-            os.environ["HOME"] = tmpdir
+            skill_file = Path(tmpdir) / ".claude" / "skills" / "repren" / "SKILL.md"
+            installed_content = skill_file.read_text()
+            package_content = get_skill_content()
 
-            try:
-                install_skill()  # Default is global (uses HOME)
-
-                skill_file = Path(tmpdir) / ".claude" / "skills" / "repren" / "SKILL.md"
-                installed_content = skill_file.read_text()
-                package_content = get_skill_content()
-
-                assert installed_content == package_content
-            finally:
-                if old_home:
-                    os.environ["HOME"] = old_home
+            assert installed_content == package_content
 
 
 class TestClaudeSkillCLI:
@@ -632,26 +671,55 @@ def test_skill_instructions_prints_content(self):
         # Should have markdown content
         assert "#" in result.stdout
 
-    def test_install_skill_with_agent_base(self):
-        """--install-skill with --agent-base should work."""
+    def test_install_skill_project_dir(self):
+        """--install-skill --project --dir DIR should write both surfaces under DIR."""
         with tempfile.TemporaryDirectory() as tmpdir:
-            # agent_base IS the .claude directory itself
-            agent_base = Path(tmpdir) / ".claude"
             result = subprocess.run(
                 [
                     "uv",
                     "run",
                     "repren",
                     "--install-skill",
-                    f"--agent-base={agent_base}",
+                    "--project",
+                    f"--dir={tmpdir}",
                 ],
                 capture_output=True,
                 text=True,
             )
 
-            assert result.returncode == 0
-            skill_file = agent_base / "skills" / "repren" / "SKILL.md"
-            assert skill_file.exists()
+            assert result.returncode == 0, result.stderr
+            assert (Path(tmpdir) / ".agents" / "skills" / "repren" / "SKILL.md").exists()
+            assert (Path(tmpdir) / ".claude" / "skills" / "repren" / "SKILL.md").exists()
+
+    def test_install_skill_global(self):
+        """--install-skill --global should write both surfaces under $HOME."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            import os
+
+            env = dict(os.environ, HOME=tmpdir)
+            result = subprocess.run(
+                ["uv", "run", "repren", "--install-skill", "--global"],
+                capture_output=True,
+                text=True,
+                env=env,
+            )
+
+            assert result.returncode == 0, result.stderr
+            assert (Path(tmpdir) / ".agents" / "skills" / "repren" / "SKILL.md").exists()
+            assert (Path(tmpdir) / ".claude" / "skills" / "repren" / "SKILL.md").exists()
+
+    def test_install_skill_ambiguous_scope_errors(self):
+        """--install-skill outside a git repo with no scope flag is a hard error."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = subprocess.run(
+                ["uv", "run", "repren", "--install-skill"],
+                capture_output=True,
+                text=True,
+                cwd=tmpdir,
+            )
+
+            assert result.returncode != 0
+            assert "git repository" in result.stderr or "ambiguous" in result.stderr
 
 
 # --- multi_replace tests ---
diff --git a/tests/tryscript/advanced-options.tryscript.md b/tests/tryscript/advanced-options.tryscript.md
index 4f77e07..f3be751 100644
--- a/tests/tryscript/advanced-options.tryscript.md
+++ b/tests/tryscript/advanced-options.tryscript.md
@@ -83,10 +83,10 @@ usage: repren [-h] [--version] [--docs] [--from FROM_PAT] [--to TO_PAT] [-p PAT_
 ? 0
 ```
 
-## A6: `--install-skill` with `--agent-base` writes both skill surfaces project-locally
+## A6: `--install-skill --project --dir` writes both skill surfaces project-locally
 
 ```console
-$ mkdir -p agentrepo && repren --install-skill --agent-base ./agentrepo/.claude >/dev/null
+$ mkdir -p agentrepo && repren --install-skill --project --dir ./agentrepo >/dev/null
 ```
 
 The skill is written to both the portable cross-agent location and the Claude mirror:
@@ -121,3 +121,22 @@ $ grep -Eq 'uvx repren@[0-9]' agentrepo/.claude/skills/repren/SKILL.md && echo p
 pinned
 ? 0
 ```
+
+## A7: `--install-skill --global` installs under `$HOME`; ambiguous scope is refused
+
+A global install writes both surfaces under the user's home directory:
+
+```console
+$ mkdir -p fakehome && HOME="$(pwd)/fakehome" repren --install-skill --global >/dev/null && find fakehome -type f -name SKILL.md | sort
+fakehome/.agents/skills/repren/SKILL.md
+fakehome/.claude/skills/repren/SKILL.md
+? 0
+```
+
+In an ambiguous location (the home directory itself), repren refuses rather than guessing:
+
+```console
+$ HOME="$(pwd)/fakehome" repren --install-skill --dir ./fakehome 2>&1 | grep -o 'home directory'
+home directory
+? 0
+```
diff --git a/tests/tryscript/help-errors.tryscript.md b/tests/tryscript/help-errors.tryscript.md
index 2f9c13e..d5d740e 100644
--- a/tests/tryscript/help-errors.tryscript.md
+++ b/tests/tryscript/help-errors.tryscript.md
@@ -86,7 +86,8 @@ usage: repren [-h] [--version] [--docs] [--from FROM_PAT] [--to TO_PAT] [-p PAT_
               [--include INCLUDE_PAT] [--exclude EXCLUDE_PAT] [--at-once] [-t]
               [--walk-only] [-n] [-q] [--format {text,json}]
               [--backup-suffix BACKUP_SUFFIX] [--undo] [--clean-backups]
-              [--install-skill] [--agent-base DIR] [--skill]
+              [--install-skill] [--project] [--global] [--dir DIR] [--no-repo-check]
+              [--skill]
               [root_paths ...]
 repren: error: must specify --patterns or both --from and --to
 
@@ -104,7 +105,8 @@ usage: repren [-h] [--version] [--docs] [--from FROM_PAT] [--to TO_PAT] [-p PAT_
               [--include INCLUDE_PAT] [--exclude EXCLUDE_PAT] [--at-once] [-t]
               [--walk-only] [-n] [-q] [--format {text,json}]
               [--backup-suffix BACKUP_SUFFIX] [--undo] [--clean-backups]
-              [--install-skill] [--agent-base DIR] [--skill]
+              [--install-skill] [--project] [--global] [--dir DIR] [--no-repo-check]
+              [--skill]
               [root_paths ...]
 repren: error: --backup-suffix must start with '.'
 

From 00a87bc36d054b94ed7d54a1fe9fc5b4ae4563cd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 05:56:20 +0000
Subject: [PATCH 04/18] docs: surface skill install in --help and lead the
 README with it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Make skill installation instantly discoverable, so an agent pointed at
`uvx repren@<version> --help` can install repren as a skill with no other docs.

- Add an IMPORTANT skill-install callout to `repren --help` and `--docs`
  (the §6.5 "discoverable help" practice): names the exact `--install-skill`
  commands for project and global scope.
- README now leads with a one-line instruction anyone can hand to their agent
  ("Run `uvx repren@2.1.0 --help` and follow the instructions to install repren
  as a skill"), and the Agent Use section is reorganized to lead with that
  one-liner, then explain how it works.
- Drop the last unpinned `@latest` from the docs in favor of a pinned
  `uvx repren@<version>`.
- Golden test H5 locks in that `--help` shows the install instructions.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 README.md                                | 74 ++++++++++++++----------
 repren/repren.py                         | 30 ++++++++--
 tests/tryscript/help-errors.tryscript.md | 14 +++++
 3 files changed, 83 insertions(+), 35 deletions(-)

diff --git a/README.md b/README.md
index 3d12080..4da5c59 100644
--- a/README.md
+++ b/README.md
@@ -5,11 +5,13 @@
 * * *
 
 > [!TIP]
-> ✨✨ **NEW:** [v2.0.0](https://github.com/jlevy/repren/releases/tag/2.0.0) is out,
-> refreshed for agent use!
-> It’s self-documenting and has a self-installable skill.
-> 
-> Just tell Claude Code: *install repren as a skill, try uvx repren@latest --help*
+> ✨✨ **Using a coding agent?** Just tell Claude Code, Codex, Gemini, or any agent:
+>
+> > Run `uvx repren@2.1.0 --help` and follow the instructions to install repren as a skill.
+>
+> That’s the whole setup. The agent reads repren’s self-documenting `--help`, installs
+> the skill, and from then on reaches for repren automatically on bulk refactors and
+> renames. See [Agent Use](#agent-use) for details.
 
 * * *
 
@@ -181,43 +183,53 @@ script somewhere convenient and make it executable.
 
 ## Agent Use
 
-repren is ideal for use by AI coding agents (Claude Code, Codex, etc.)
-since it is powerful, simple to use, and self-documenting.
-Just tell agents to run `repren --help` (or, with no install, `uvx repren@latest --help`)
-and they have everything they need, including the ability to install it as a skill.
-Agents can use `--format=json` for machine-parseable output.
+**The one thing to know:** point your agent at repren’s self-documenting help and let it
+install itself —
 
-repren includes a built-in skill for coding agents. Installing it writes the skill to
-both the portable cross-agent location (`.agents/skills/repren/`, used by Codex, pi, and
-others) and the Claude Code mirror (`.claude/skills/repren/`). repren is a general-purpose
-utility with no per-project config, so the skill invokes it via a pinned zero-install
-runner (`uvx repren@<version>`) and there is no need to add repren as a project
-dependency.
+> Run `uvx repren@2.1.0 --help` and follow the instructions to install repren as a skill.
 
-repren is a dual-scope skill: install it into a single project or globally for your
-user. Scope is resolved like `git config` — implicit when unambiguous, an error when
-not — so a stray `--install-skill` never silently rewrites your global agent surfaces.
+repren’s `--help` ends with the exact install commands, so the agent can take it from
+there. (`uvx` runs repren with no prior install; pin a version you trust.)
 
-**Install:**
+**Install the skill yourself** (the same thing the agent does):
 
 ```bash
 # Install into the current project (run from the repo; shareable via git):
-uvx repren --install-skill --project
+uvx repren@2.1.0 --install-skill --project
 
-# Install globally (available in all projects):
-uvx repren --install-skill --global
+# Or install globally, for every project:
+uvx repren@2.1.0 --install-skill --global
 ```
 
-Inside a git repo, `--project` is implied, so `uvx repren --install-skill` installs into
-the project. Outside a repo (or in your home directory) the scope is ambiguous and you
-must pass `--project` (optionally with `--dir DIR` or `--no-repo-check`) or `--global`.
+Re-run any time to update an existing install.
 
-Re-run to update an existing installation. The skill pins the repren version it was
-installed from.
+### How it works
 
-**Manual install:** Run `uvx repren --skill` and save the output to
-`.agents/skills/repren/SKILL.md` (and/or `.claude/skills/repren/SKILL.md`), under `~`
-for a global install or the project root for a project install.
+repren is **self-documenting**: `repren --help` and `repren --docs` are the source of
+truth for every flag, and `--format=json` gives agents machine-parseable output. The
+skill is just a thin pointer to those commands, so it never drifts out of date.
+
+Installing the skill writes one `SKILL.md` to **both** discovery locations, so every
+agent finds it:
+
+- `.agents/skills/repren/` — the portable, cross-agent location (Codex, Gemini, pi, …)
+- `.claude/skills/repren/` — the Claude Code mirror
+
+repren is a general-purpose utility with no per-project config, so the skill invokes it
+through a **pinned zero-install runner** (`uvx repren@<version>`) — there’s no need to add
+repren as a project dependency, and each installed skill pins the version it came from.
+
+**Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
+not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
+
+- Inside a git repo, `--project` is implied (so `uvx repren --install-skill` just works).
+- In an ambiguous spot (your home directory, or outside any repo) repren refuses and
+  tells you to pass `--project` (optionally with `--dir DIR` or `--no-repo-check`) or
+  `--global`.
+
+**Manual install:** run `uvx repren --skill` and save the output to
+`.agents/skills/repren/SKILL.md` (and/or `.claude/skills/repren/SKILL.md`), under `~` for
+a global install or the project root for a project install.
 
 **Learn more:** [Claude Code docs](https://claude.ai/code) and
 [Skills repository](https://github.com/anthropics/skills).
diff --git a/repren/repren.py b/repren/repren.py
index e94de04..f112f94 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -170,8 +170,9 @@
 
 repren is ideal for use by AI coding agents (Claude Code, Codex, etc.)
 since it is powerful, simple to use, and self-documenting.
-Just tell agents to run `repren --help` (or, with no install, `uvx repren@latest --help`)
-and they have everything they need, including the ability to install it as a skill.
+Just tell agents to run `repren --help` (or, with no install, `uvx repren@<version> --help`,
+pinning a version you trust) and they have everything they need, including the ability to
+install it as a skill.
 Agents can use `--format=json` for machine-parseable output.
 
 repren includes a built-in skill for coding agents. Installing it writes the skill to
@@ -490,6 +491,14 @@ def _get_version() -> str:
 Run `repren --help` for usage.
 Run `repren --docs` for full docs."""
 
+# Prominent callout shown in `--help` so agents and humans immediately discover that
+# repren can install itself as an agent skill. Keep this short and actionable (§6.5).
+SKILL_HINT: str = """\
+IMPORTANT — Use repren as an agent skill (Claude Code, Codex, Gemini, and others):
+  Install into your project:  repren --install-skill            (run inside the repo)
+  Install for all projects:   repren --install-skill --global
+Once installed, your coding agent uses repren automatically for refactoring tasks."""
+
 # Terminal width handling.
 DEFAULT_WIDTH: int = 88
 MIN_WIDTH: int = 40
@@ -579,6 +588,13 @@ def _format_hint(color: bool = True) -> str:
     return DOCS_HINT
 
 
+def _format_skill_hint(color: bool = True) -> str:
+    """Format the SKILL_HINT with optional ANSI colors."""
+    if color and _markdown_available:
+        return f"{_ansi_yellow}{SKILL_HINT}{_ansi_reset}"
+    return SKILL_HINT
+
+
 @dataclass
 class _Tally:
     files: int = 0
@@ -1382,8 +1398,10 @@ def error(self, message: str) -> NoReturn:
 
     # Handle --help early (show basic usage)
     if "-h" in sys.argv or "--help" in sys.argv:
+        use_color = sys.stdout.isatty()
         parser.print_help()
-        print(f"\n{_format_hint(color=sys.stdout.isatty())}\n")
+        print(f"\n{_format_skill_hint(color=use_color)}\n")
+        print(f"{_format_hint(color=use_color)}\n")
         sys.exit(0)
 
     # Handle --docs early (show full documentation)
@@ -1391,7 +1409,11 @@ def error(self, message: str) -> NoReturn:
         doc_text = __doc__ or ""
         use_color = sys.stdout.isatty()
         full_docs = _render_markdown(doc_text, color=use_color) if _markdown_available else doc_text
-        parser.epilog = full_docs + f"\n{_format_hint(color=use_color)}\n"
+        parser.epilog = (
+            full_docs
+            + f"\n{_format_skill_hint(color=use_color)}\n"
+            + f"\n{_format_hint(color=use_color)}\n"
+        )
         parser.print_help()
         sys.exit(0)
 
diff --git a/tests/tryscript/help-errors.tryscript.md b/tests/tryscript/help-errors.tryscript.md
index d5d740e..64d9b9c 100644
--- a/tests/tryscript/help-errors.tryscript.md
+++ b/tests/tryscript/help-errors.tryscript.md
@@ -77,6 +77,20 @@ description: Performs simultaneous multi-pattern search-and-replace, file/direct
 ? 0
 ```
 
+## H5: `--help` surfaces the skill-install instructions
+
+```console
+$ repren --help | grep -F "Use repren as an agent skill"
+IMPORTANT — Use repren as an agent skill (Claude Code, Codex, Gemini, and others):
+? 0
+```
+
+```console
+$ repren --help | grep -F -- "repren --install-skill --global"
+  Install for all projects:   repren --install-skill --global
+? 0
+```
+
 ## E1: Missing patterns is an error
 
 ```console

From cf246c5c728431f69c748e8f7ed85f2d442c6341 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 06:38:18 +0000
Subject: [PATCH 05/18] docs: auto-pin doc versions; lead with zero-deps +
 supply-chain notes

Make the pinned repren version in the docs maintainable, and prominently note
repren's zero runtime dependencies as a security/simplicity advantage.

Version generation (so version strings are never hand-edited):
- gendocs.py now substitutes a {{REPREN_VERSION}} placeholder in the manual and
  normalizes the hand-written README header, pinning docs to a single resolved
  version: REPREN_DOCS_VERSION env override -> installed clean-release version ->
  DEFAULT_DOC_VERSION fallback. Idempotent across runs.

Content (docs/repren-docs.md is the source of truth, synced into the docstring
and README by gendocs):
- Lead the intro and Agent Use with the agent one-liner
  ("Run `uvx repren@<version> --help` and follow the instructions to install ...").
- Prominently document ZERO runtime dependencies (vs dev-only tooling), adapting
  the supply-chain notes from jlevy/strif: no transitive tree to audit/compromise,
  single file you can review.
- Add a pinning/supply-chain note: examples pin an explicit version rather than
  @latest (uv applies no cool-off by default); document UV_EXCLUDE_NEWER as the
  opt-in "always-latest but cooled" alternative.
- Refresh install commands to the --project/--global scope flags.

Tests: cover get_doc_version (env override, dev fallback), _is_clean_release,
render_version, header-pin idempotency, and that generated docs contain no raw
placeholder.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 README.md           |  63 ++++++++++++++++++++----
 devtools/gendocs.py |  68 ++++++++++++++++++++++++--
 docs/repren-docs.md | 106 +++++++++++++++++++++++++++++++---------
 repren/repren.py    | 115 +++++++++++++++++++++++++++++++-------------
 tests/pytests.py    |  57 ++++++++++++++++++++++
 5 files changed, 339 insertions(+), 70 deletions(-)

diff --git a/README.md b/README.md
index 4da5c59..1aa74ab 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,13 @@
 > the skill, and from then on reaches for repren automatically on bulk refactors and
 > renames. See [Agent Use](#agent-use) for details.
 
+> [!TIP]
+> 🔒 **Zero dependencies.** repren has **zero runtime dependencies** — just Python and a
+> single file. Amid the rise of supply-chain attacks on package ecosystems, that means
+> there’s no transitive dependency tree to audit or be compromised: the only code `uvx
+> repren@2.1.0` ever fetches and runs is repren itself, and you (or your agent) can review
+> its security before trusting it.
+
 * * *
 
 ## Rename Anything
@@ -20,9 +27,27 @@
 `repren` is a powerful CLI string replacement and file renaming tool for use by agents
 or humans for almost any search-and-replace or renaming task.
 
-It is small, self-contained, self-documenting, and works on Python 3.10-3.14 with zero
-dependencies. Essentially, it is a general-purpose, brute-force text file refactoring
-tool.
+It is small, self-contained, self-documenting, and works on Python 3.10-3.14 with
+**zero runtime dependencies**. Essentially, it is a general-purpose, brute-force text
+file refactoring tool.
+
+**Using a coding agent?** This is the whole setup — tell Claude Code, Codex, Gemini, or
+any agent:
+
+> Run `uvx repren@2.1.0 --help` and follow the instructions to install repren
+> as a skill.
+
+repren’s `--help` ends with the exact install commands, so the agent reads them and takes
+it from there. After that it reaches for repren automatically on bulk refactors and
+renames. (See [Agent Use](#agent-use).)
+
+**Zero dependencies, by design.** Given the rise of supply-chain attacks on package
+ecosystems, it’s worth noting that repren has **zero runtime dependencies** — installing
+it (or running `uvx repren@<version>`) pulls in nothing but repren itself and the Python
+standard library. There is no transitive dependency tree to audit or to be compromised,
+so it is simpler and safer to adopt than most tools. It’s also a single file you can read
+end to end (or have your agent review) before you trust it. The dev-only tooling used to
+build and test repren (pytest, ruff, etc.) is never installed when you use it.
 
 For example, repren could rename occurrences of certain names in a set of source files,
 while simultaneously renaming the files and directories according to the same pattern
@@ -166,30 +191,48 @@ Here’s how repren compares:
 
 ## Installation
 
-No dependencies except Python 3.10+. It’s easiest to install with
+repren has **zero runtime dependencies** (just Python 3.10+), so installing it never adds
+a transitive dependency tree to your environment. It’s easiest to install with
 [uv](https://docs.astral.sh/uv/):
 
 ```bash
-# Install as a tool:
+# Install as a tool (pin a version you trust):
 uv tool install repren
 
-# Or run directly without installing:
-uvx repren --help
+# Or run directly without installing, pinned to a known version:
+uvx repren@2.1.0 --help
 ```
 
 Or, since it’s just one file, you can copy the
 [repren.py](https://raw.githubusercontent.com/jlevy/repren/master/repren/repren.py)
 script somewhere convenient and make it executable.
 
+**A note on pinning (supply-chain hygiene).** The examples here pin an explicit version
+(`repren@2.1.0`) rather than `@latest`. An unpinned `uvx repren@latest` re-resolves
+to the newest release every run and executes it immediately — the pattern supply-chain
+guidance warns against, since uv applies no release “cool-off” by default. If you prefer
+to always track the latest release but still want a safety delay, opt into uv’s cool-off,
+which excludes very recent uploads:
+
+```bash
+# Only resolve versions at least 14 days old, then run latest-within-that-window:
+UV_EXCLUDE_NEWER="14 days" uvx repren@latest --help
+```
+
+repren’s zero-dependency design keeps this risk small either way: the only code fetched
+and run is repren itself.
+
 ## Agent Use
 
 **The one thing to know:** point your agent at repren’s self-documenting help and let it
 install itself —
 
-> Run `uvx repren@2.1.0 --help` and follow the instructions to install repren as a skill.
+> Run `uvx repren@2.1.0 --help` and follow the instructions to install repren
+> as a skill.
 
 repren’s `--help` ends with the exact install commands, so the agent can take it from
-there. (`uvx` runs repren with no prior install; pin a version you trust.)
+there. (`uvx` runs repren with no prior install; the example pins a version, which is
+safer than `@latest` — see the note under [Installation](#installation).)
 
 **Install the skill yourself** (the same thing the agent does):
 
@@ -218,6 +261,8 @@ agent finds it:
 repren is a general-purpose utility with no per-project config, so the skill invokes it
 through a **pinned zero-install runner** (`uvx repren@<version>`) — there’s no need to add
 repren as a project dependency, and each installed skill pins the version it came from.
+Combined with repren’s zero runtime dependencies, the code an agent ever fetches and runs
+is just repren itself.
 
 **Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
 not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
diff --git a/devtools/gendocs.py b/devtools/gendocs.py
index d3be05b..05950f6 100644
--- a/devtools/gendocs.py
+++ b/devtools/gendocs.py
@@ -5,12 +5,58 @@
 The manual is the single source of truth. This script:
 1. Updates the docstring in repren/repren.py
 2. Updates the documentation section in README.md
+
+The manual may use the ``{{REPREN_VERSION}}`` placeholder anywhere it shows a pinned
+``uvx repren@<version>`` invocation; this script substitutes the current version so the
+docs stay pinned (supply-chain hygiene) without anyone hand-editing version strings. The
+version is resolved from, in order: ``REPREN_DOCS_VERSION`` (release automation), the
+installed package version when it is a clean release, then ``DEFAULT_DOC_VERSION``.
 """
 
+import importlib.metadata
+import os
 import re
 import sys
 from pathlib import Path
 
+# Placeholder used in the manual for the pinned repren version (matches claude_skill).
+VERSION_PLACEHOLDER = "{{REPREN_VERSION}}"
+
+# Fallback shown in docs when no released package version is resolvable (e.g. an editable
+# dev checkout). Set to the version currently being prepared; release builds override it
+# automatically with the real package version, so this rarely needs touching.
+DEFAULT_DOC_VERSION = "2.1.0"
+
+
+def _is_clean_release(version: str) -> bool:
+    """True for a published release version (no dev/pre-release or local segment)."""
+    return bool(re.fullmatch(r"\d+\.\d+(?:\.\d+)?", version))
+
+
+def get_doc_version() -> str:
+    """Resolve the version to pin in generated docs.
+
+    Order: ``REPREN_DOCS_VERSION`` env override → installed package version (only if it is
+    a clean release) → ``DEFAULT_DOC_VERSION``.
+    """
+    override = os.environ.get("REPREN_DOCS_VERSION")
+    if override:
+        return override.lstrip("v")
+
+    try:
+        version = importlib.metadata.version("repren")
+        if _is_clean_release(version):
+            return version
+    except importlib.metadata.PackageNotFoundError:
+        pass
+
+    return DEFAULT_DOC_VERSION
+
+
+def render_version(text: str, version: str) -> str:
+    """Substitute the version placeholder in manual text."""
+    return text.replace(VERSION_PLACEHOLDER, version)
+
 
 def read_manual(repo_root: Path) -> str:
     """Read the manual content."""
@@ -46,7 +92,13 @@ def update_repren_py(repo_root: Path, manual: str) -> bool:
     return True
 
 
-def update_readme(repo_root: Path, manual: str) -> bool:
+# Pinned-version invocations in the hand-written README header (e.g. the agent
+# quick-start), normalized to the current version on each run so the header stays in sync
+# without manual edits. Scoped to the header only, which never mentions `@latest`.
+_HEADER_PIN_RE = re.compile(r"uvx repren@[A-Za-z0-9][A-Za-z0-9._-]*")
+
+
+def update_readme(repo_root: Path, manual: str, version: str) -> bool:
     """Update the documentation section in README.md."""
     readme_path = repo_root / "README.md"
     content = readme_path.read_text()
@@ -64,11 +116,13 @@ def update_readme(repo_root: Path, manual: str) -> bool:
         print("ERROR: Could not find documentation section in README.md", file=sys.stderr)
         return False
 
+    # The hand-written header is not regenerated from the manual, so normalize any
+    # `uvx repren@<version>` pins in it to the current version (idempotent).
+    header = _HEADER_PIN_RE.sub(f"uvx repren@{version}", content[: match.start()])
+
     # Build new content using string concatenation (not re.sub) to avoid
     # backreference issues with \1, \2, etc. in the manual
-    new_content = (
-        content[: match.start()] + match.group(1) + manual + match.group(3) + content[match.end() :]
-    )
+    new_content = header + match.group(1) + manual + match.group(3) + content[match.end() :]
 
     if new_content != content:
         readme_path.write_text(new_content)
@@ -85,9 +139,13 @@ def main() -> int:
     print("Reading manual from docs/repren-docs.md...")
     manual = read_manual(repo_root)
 
+    version = get_doc_version()
+    print(f"Pinning docs to repren version: {version}")
+    manual = render_version(manual, version)
+
     success = True
     success = update_repren_py(repo_root, manual) and success
-    success = update_readme(repo_root, manual) and success
+    success = update_readme(repo_root, manual, version) and success
 
     return 0 if success else 1
 
diff --git a/docs/repren-docs.md b/docs/repren-docs.md
index 926c21a..e875f79 100644
--- a/docs/repren-docs.md
+++ b/docs/repren-docs.md
@@ -3,9 +3,27 @@
 `repren` is a powerful CLI string replacement and file renaming tool for use by agents
 or humans for almost any search-and-replace or renaming task.
 
-It is small, self-contained, self-documenting, and works on Python 3.10-3.14 with zero
-dependencies. Essentially, it is a general-purpose, brute-force text file refactoring
-tool.
+It is small, self-contained, self-documenting, and works on Python 3.10-3.14 with
+**zero runtime dependencies**. Essentially, it is a general-purpose, brute-force text
+file refactoring tool.
+
+**Using a coding agent?** This is the whole setup — tell Claude Code, Codex, Gemini, or
+any agent:
+
+> Run `uvx repren@{{REPREN_VERSION}} --help` and follow the instructions to install repren
+> as a skill.
+
+repren’s `--help` ends with the exact install commands, so the agent reads them and takes
+it from there. After that it reaches for repren automatically on bulk refactors and
+renames. (See [Agent Use](#agent-use).)
+
+**Zero dependencies, by design.** Given the rise of supply-chain attacks on package
+ecosystems, it’s worth noting that repren has **zero runtime dependencies** — installing
+it (or running `uvx repren@<version>`) pulls in nothing but repren itself and the Python
+standard library. There is no transitive dependency tree to audit or to be compromised,
+so it is simpler and safer to adopt than most tools. It’s also a single file you can read
+end to end (or have your agent review) before you trust it. The dev-only tooling used to
+build and test repren (pytest, ruff, etc.) is never installed when you use it.
 
 For example, repren could rename occurrences of certain names in a set of source files,
 while simultaneously renaming the files and directories according to the same pattern
@@ -149,46 +167,90 @@ Here’s how repren compares:
 
 ## Installation
 
-No dependencies except Python 3.10+. It’s easiest to install with
+repren has **zero runtime dependencies** (just Python 3.10+), so installing it never adds
+a transitive dependency tree to your environment. It’s easiest to install with
 [uv](https://docs.astral.sh/uv/):
 
 ```bash
-# Install as a tool:
+# Install as a tool (pin a version you trust):
 uv tool install repren
 
-# Or run directly without installing:
-uvx repren --help
+# Or run directly without installing, pinned to a known version:
+uvx repren@{{REPREN_VERSION}} --help
 ```
 
 Or, since it’s just one file, you can copy the
 [repren.py](https://raw.githubusercontent.com/jlevy/repren/master/repren/repren.py)
 script somewhere convenient and make it executable.
 
+**A note on pinning (supply-chain hygiene).** The examples here pin an explicit version
+(`repren@{{REPREN_VERSION}}`) rather than `@latest`. An unpinned `uvx repren@latest` re-resolves
+to the newest release every run and executes it immediately — the pattern supply-chain
+guidance warns against, since uv applies no release “cool-off” by default. If you prefer
+to always track the latest release but still want a safety delay, opt into uv’s cool-off,
+which excludes very recent uploads:
+
+```bash
+# Only resolve versions at least 14 days old, then run latest-within-that-window:
+UV_EXCLUDE_NEWER="14 days" uvx repren@latest --help
+```
+
+repren’s zero-dependency design keeps this risk small either way: the only code fetched
+and run is repren itself.
+
 ## Agent Use
 
-repren is ideal for use by AI coding agents (Claude Code, Codex, etc.)
-since it is powerful, simple to use, and self-documenting.
-Just tell agents to run `uvx repren@latest --help` and they have everything they need,
-including the ability to install it as a skill.
-Agents can use `--format=json` for machine-parseable output.
+**The one thing to know:** point your agent at repren’s self-documenting help and let it
+install itself —
 
-repren includes a built-in skill for Claude Code or other agents.
+> Run `uvx repren@{{REPREN_VERSION}} --help` and follow the instructions to install repren
+> as a skill.
 
-**Install:**
+repren’s `--help` ends with the exact install commands, so the agent can take it from
+there. (`uvx` runs repren with no prior install; the example pins a version, which is
+safer than `@latest` — see the note under [Installation](#installation).)
+
+**Install the skill yourself** (the same thing the agent does):
 
 ```bash
-# Install globally (available in all projects):
-uvx repren --install-skill
+# Install into the current project (run from the repo; shareable via git):
+uvx repren@{{REPREN_VERSION}} --install-skill --project
 
-# Or install for current project only (shareable via git):
-uvx repren --install-skill --agent-base=./.claude
+# Or install globally, for every project:
+uvx repren@{{REPREN_VERSION}} --install-skill --global
 ```
 
-Re-run to update an existing installation.
+Re-run any time to update an existing install.
+
+### How it works
+
+repren is **self-documenting**: `repren --help` and `repren --docs` are the source of
+truth for every flag, and `--format=json` gives agents machine-parseable output. The
+skill is just a thin pointer to those commands, so it never drifts out of date.
+
+Installing the skill writes one `SKILL.md` to **both** discovery locations, so every
+agent finds it:
+
+- `.agents/skills/repren/` — the portable, cross-agent location (Codex, Gemini, pi, …)
+- `.claude/skills/repren/` — the Claude Code mirror
+
+repren is a general-purpose utility with no per-project config, so the skill invokes it
+through a **pinned zero-install runner** (`uvx repren@<version>`) — there’s no need to add
+repren as a project dependency, and each installed skill pins the version it came from.
+Combined with repren’s zero runtime dependencies, the code an agent ever fetches and runs
+is just repren itself.
+
+**Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
+not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
+
+- Inside a git repo, `--project` is implied (so `uvx repren --install-skill` just works).
+- In an ambiguous spot (your home directory, or outside any repo) repren refuses and
+  tells you to pass `--project` (optionally with `--dir DIR` or `--no-repo-check`) or
+  `--global`.
 
-**Manual install:** Run `uvx repren --skill` and save to
-`~/.claude/skills/repren/SKILL.md` (global) or `.claude/skills/repren/SKILL.md`
-(project).
+**Manual install:** run `uvx repren --skill` and save the output to
+`.agents/skills/repren/SKILL.md` (and/or `.claude/skills/repren/SKILL.md`), under `~` for
+a global install or the project root for a project install.
 
 **Learn more:** [Claude Code docs](https://claude.ai/code) and
 [Skills repository](https://github.com/anthropics/skills).
diff --git a/repren/repren.py b/repren/repren.py
index f112f94..874de7a 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -5,9 +5,27 @@
 `repren` is a powerful CLI string replacement and file renaming tool for use by agents
 or humans for almost any search-and-replace or renaming task.
 
-It is small, self-contained, self-documenting, and works on Python 3.10-3.14 with zero
-dependencies. Essentially, it is a general-purpose, brute-force text file refactoring
-tool.
+It is small, self-contained, self-documenting, and works on Python 3.10-3.14 with
+**zero runtime dependencies**. Essentially, it is a general-purpose, brute-force text
+file refactoring tool.
+
+**Using a coding agent?** This is the whole setup — tell Claude Code, Codex, Gemini, or
+any agent:
+
+> Run `uvx repren@2.1.0 --help` and follow the instructions to install repren
+> as a skill.
+
+repren’s `--help` ends with the exact install commands, so the agent reads them and takes
+it from there. After that it reaches for repren automatically on bulk refactors and
+renames. (See [Agent Use](#agent-use).)
+
+**Zero dependencies, by design.** Given the rise of supply-chain attacks on package
+ecosystems, it’s worth noting that repren has **zero runtime dependencies** — installing
+it (or running `uvx repren@<version>`) pulls in nothing but repren itself and the Python
+standard library. There is no transitive dependency tree to audit or to be compromised,
+so it is simpler and safer to adopt than most tools. It’s also a single file you can read
+end to end (or have your agent review) before you trust it. The dev-only tooling used to
+build and test repren (pytest, ruff, etc.) is never installed when you use it.
 
 For example, repren could rename occurrences of certain names in a set of source files,
 while simultaneously renaming the files and directories according to the same pattern
@@ -151,61 +169,90 @@
 
 ## Installation
 
-No dependencies except Python 3.10+. It’s easiest to install with
+repren has **zero runtime dependencies** (just Python 3.10+), so installing it never adds
+a transitive dependency tree to your environment. It’s easiest to install with
 [uv](https://docs.astral.sh/uv/):
 
 ```bash
-# Install as a tool:
+# Install as a tool (pin a version you trust):
 uv tool install repren
 
-# Or run directly without installing:
-uvx repren --help
+# Or run directly without installing, pinned to a known version:
+uvx repren@2.1.0 --help
 ```
 
 Or, since it’s just one file, you can copy the
 [repren.py](https://raw.githubusercontent.com/jlevy/repren/master/repren/repren.py)
 script somewhere convenient and make it executable.
 
+**A note on pinning (supply-chain hygiene).** The examples here pin an explicit version
+(`repren@2.1.0`) rather than `@latest`. An unpinned `uvx repren@latest` re-resolves
+to the newest release every run and executes it immediately — the pattern supply-chain
+guidance warns against, since uv applies no release “cool-off” by default. If you prefer
+to always track the latest release but still want a safety delay, opt into uv’s cool-off,
+which excludes very recent uploads:
+
+```bash
+# Only resolve versions at least 14 days old, then run latest-within-that-window:
+UV_EXCLUDE_NEWER="14 days" uvx repren@latest --help
+```
+
+repren’s zero-dependency design keeps this risk small either way: the only code fetched
+and run is repren itself.
+
 ## Agent Use
 
-repren is ideal for use by AI coding agents (Claude Code, Codex, etc.)
-since it is powerful, simple to use, and self-documenting.
-Just tell agents to run `repren --help` (or, with no install, `uvx repren@<version> --help`,
-pinning a version you trust) and they have everything they need, including the ability to
-install it as a skill.
-Agents can use `--format=json` for machine-parseable output.
+**The one thing to know:** point your agent at repren’s self-documenting help and let it
+install itself —
 
-repren includes a built-in skill for coding agents. Installing it writes the skill to
-both the portable cross-agent location (`.agents/skills/repren/`, used by Codex, pi, and
-others) and the Claude Code mirror (`.claude/skills/repren/`). repren is a general-purpose
-utility with no per-project config, so the skill invokes it via a pinned zero-install
-runner (`uvx repren@<version>`) and there is no need to add repren as a project
-dependency.
+> Run `uvx repren@2.1.0 --help` and follow the instructions to install repren
+> as a skill.
 
-repren is a dual-scope skill: install it into a single project or globally for your
-user. Scope is resolved like `git config` — implicit when unambiguous, an error when
-not — so a stray `--install-skill` never silently rewrites your global agent surfaces.
+repren’s `--help` ends with the exact install commands, so the agent can take it from
+there. (`uvx` runs repren with no prior install; the example pins a version, which is
+safer than `@latest` — see the note under [Installation](#installation).)
 
-**Install:**
+**Install the skill yourself** (the same thing the agent does):
 
 ```bash
 # Install into the current project (run from the repo; shareable via git):
-uvx repren --install-skill --project
+uvx repren@2.1.0 --install-skill --project
 
-# Install globally (available in all projects):
-uvx repren --install-skill --global
+# Or install globally, for every project:
+uvx repren@2.1.0 --install-skill --global
 ```
 
-Inside a git repo, `--project` is implied, so `uvx repren --install-skill` installs into
-the project. Outside a repo (or in your home directory) the scope is ambiguous and you
-must pass `--project` (optionally with `--dir DIR` or `--no-repo-check`) or `--global`.
+Re-run any time to update an existing install.
+
+### How it works
+
+repren is **self-documenting**: `repren --help` and `repren --docs` are the source of
+truth for every flag, and `--format=json` gives agents machine-parseable output. The
+skill is just a thin pointer to those commands, so it never drifts out of date.
+
+Installing the skill writes one `SKILL.md` to **both** discovery locations, so every
+agent finds it:
+
+- `.agents/skills/repren/` — the portable, cross-agent location (Codex, Gemini, pi, …)
+- `.claude/skills/repren/` — the Claude Code mirror
+
+repren is a general-purpose utility with no per-project config, so the skill invokes it
+through a **pinned zero-install runner** (`uvx repren@<version>`) — there’s no need to add
+repren as a project dependency, and each installed skill pins the version it came from.
+Combined with repren’s zero runtime dependencies, the code an agent ever fetches and runs
+is just repren itself.
+
+**Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
+not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
 
-Re-run to update an existing installation. The skill pins the repren version it was
-installed from.
+- Inside a git repo, `--project` is implied (so `uvx repren --install-skill` just works).
+- In an ambiguous spot (your home directory, or outside any repo) repren refuses and
+  tells you to pass `--project` (optionally with `--dir DIR` or `--no-repo-check`) or
+  `--global`.
 
-**Manual install:** Run `uvx repren --skill` and save the output to
-`.agents/skills/repren/SKILL.md` (and/or `.claude/skills/repren/SKILL.md`), under `~`
-for a global install or the project root for a project install.
+**Manual install:** run `uvx repren --skill` and save the output to
+`.agents/skills/repren/SKILL.md` (and/or `.claude/skills/repren/SKILL.md`), under `~` for
+a global install or the project root for a project install.
 
 **Learn more:** [Claude Code docs](https://claude.ai/code) and
 [Skills repository](https://github.com/anthropics/skills).
diff --git a/tests/pytests.py b/tests/pytests.py
index 2b8f02a..4f3bba1 100644
--- a/tests/pytests.py
+++ b/tests/pytests.py
@@ -494,6 +494,63 @@ def test_clean_backups_conflicts_with_patterns(self):
 # --- Claude Skill tests ---
 
 
+def _load_gendocs():
+    """Load the devtools/gendocs.py module by path (it is not an installed package)."""
+    import importlib.util
+
+    gendocs_path = Path(__file__).parent.parent / "devtools" / "gendocs.py"
+    spec = importlib.util.spec_from_file_location("gendocs", gendocs_path)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class TestGendocsVersionPinning:
+    """Tests for the docs version-pinning mechanism in devtools/gendocs.py."""
+
+    def test_env_override_wins(self, monkeypatch):
+        gendocs = _load_gendocs()
+        monkeypatch.setenv("REPREN_DOCS_VERSION", "v9.9.9")
+        # Leading "v" is stripped.
+        assert gendocs.get_doc_version() == "9.9.9"
+
+    def test_dev_version_falls_back_to_default(self, monkeypatch):
+        gendocs = _load_gendocs()
+        monkeypatch.delenv("REPREN_DOCS_VERSION", raising=False)
+        # The editable checkout reports a dev version, so the default is used.
+        assert gendocs.get_doc_version() == gendocs.DEFAULT_DOC_VERSION
+
+    def test_is_clean_release(self):
+        gendocs = _load_gendocs()
+        assert gendocs._is_clean_release("2.1.0")
+        assert gendocs._is_clean_release("2.1")
+        assert not gendocs._is_clean_release("2.1.0.dev3")
+        assert not gendocs._is_clean_release("2.1.0+gabc")
+        assert not gendocs._is_clean_release("latest")
+
+    def test_render_version_substitutes_placeholder(self):
+        gendocs = _load_gendocs()
+        rendered = gendocs.render_version("run uvx repren@{{REPREN_VERSION}} --help", "2.1.0")
+        assert rendered == "run uvx repren@2.1.0 --help"
+        assert "{{REPREN_VERSION}}" not in rendered
+
+    def test_header_pin_regex_is_idempotent(self):
+        gendocs = _load_gendocs()
+        once = gendocs._HEADER_PIN_RE.sub("uvx repren@2.1.0", "see uvx repren@1.0.0 --help")
+        twice = gendocs._HEADER_PIN_RE.sub("uvx repren@2.1.0", once)
+        assert once == "see uvx repren@2.1.0 --help"
+        assert once == twice
+
+    def test_generated_docs_have_no_placeholder(self):
+        """The committed generated docs must not contain the raw version placeholder."""
+        repo_root = Path(__file__).parent.parent
+        readme = (repo_root / "README.md").read_text()
+        repren_py = (repo_root / "repren" / "repren.py").read_text()
+        assert "{{REPREN_VERSION}}" not in readme
+        assert "{{REPREN_VERSION}}" not in repren_py
+
+
 class TestClaudeSkillContent:
     """Tests for Claude skill content loading."""
 

From 98ba7105f7896c94ef77dee3d58fcdb72753c7b5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 06:41:56 +0000
Subject: [PATCH 06/18] docs: use uvx repren@latest in human docs; keep skill
 runner pinned
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per project decision: the README/manual install instructions use the simpler
`uvx repren@latest`, leaning on repren's zero runtime dependencies (no transitive
attack surface) plus a documented cool-off option for safety. This aligns with the
guidelines, which pin the *skill's* runner but allow human prose to use @latest.

- Human-facing docs (README header, intro, Installation, Agent Use) now use
  `uvx repren@latest`.
- Reframe the supply-chain note around @latest: zero deps keep the risk small;
  document `UV_EXCLUDE_NEWER` cool-off and an explicit pin as opt-in hardening.
- Clarify that the installed SKILL.md still pins the exact version it was generated
  from (reproducible agent invocations) even though the human quick-start uses
  @latest — this pinning is handled at install time in claude_skill.py.
- Revert the now-unneeded version-injection in gendocs.py (no placeholder in human
  docs) and its tests.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 README.md           | 55 ++++++++++++++++++------------------
 devtools/gendocs.py | 68 ++++-----------------------------------------
 docs/repren-docs.md | 51 +++++++++++++++++-----------------
 repren/repren.py    | 51 +++++++++++++++++-----------------
 tests/pytests.py    | 57 -------------------------------------
 5 files changed, 82 insertions(+), 200 deletions(-)

diff --git a/README.md b/README.md
index 1aa74ab..3dc5b92 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
 > [!TIP]
 > ✨✨ **Using a coding agent?** Just tell Claude Code, Codex, Gemini, or any agent:
 >
-> > Run `uvx repren@2.1.0 --help` and follow the instructions to install repren as a skill.
+> > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 >
 > That’s the whole setup. The agent reads repren’s self-documenting `--help`, installs
 > the skill, and from then on reaches for repren automatically on bulk refactors and
@@ -17,7 +17,7 @@
 > 🔒 **Zero dependencies.** repren has **zero runtime dependencies** — just Python and a
 > single file. Amid the rise of supply-chain attacks on package ecosystems, that means
 > there’s no transitive dependency tree to audit or be compromised: the only code `uvx
-> repren@2.1.0` ever fetches and runs is repren itself, and you (or your agent) can review
+> repren@latest` ever fetches and runs is repren itself, and you (or your agent) can review
 > its security before trusting it.
 
 * * *
@@ -34,8 +34,7 @@ file refactoring tool.
 **Using a coding agent?** This is the whole setup — tell Claude Code, Codex, Gemini, or
 any agent:
 
-> Run `uvx repren@2.1.0 --help` and follow the instructions to install repren
-> as a skill.
+> Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
 repren’s `--help` ends with the exact install commands, so the agent reads them and takes
 it from there. After that it reaches for repren automatically on bulk refactors and
@@ -43,7 +42,7 @@ renames. (See [Agent Use](#agent-use).)
 
 **Zero dependencies, by design.** Given the rise of supply-chain attacks on package
 ecosystems, it’s worth noting that repren has **zero runtime dependencies** — installing
-it (or running `uvx repren@<version>`) pulls in nothing but repren itself and the Python
+it (or running `uvx repren@latest`) pulls in nothing but repren itself and the Python
 standard library. There is no transitive dependency tree to audit or to be compromised,
 so it is simpler and safer to adopt than most tools. It’s also a single file you can read
 end to end (or have your agent review) before you trust it. The dev-only tooling used to
@@ -196,52 +195,51 @@ a transitive dependency tree to your environment. It’s easiest to install with
 [uv](https://docs.astral.sh/uv/):
 
 ```bash
-# Install as a tool (pin a version you trust):
+# Install as a tool:
 uv tool install repren
 
-# Or run directly without installing, pinned to a known version:
-uvx repren@2.1.0 --help
+# Or run directly without installing:
+uvx repren@latest --help
 ```
 
 Or, since it’s just one file, you can copy the
 [repren.py](https://raw.githubusercontent.com/jlevy/repren/master/repren/repren.py)
 script somewhere convenient and make it executable.
 
-**A note on pinning (supply-chain hygiene).** The examples here pin an explicit version
-(`repren@2.1.0`) rather than `@latest`. An unpinned `uvx repren@latest` re-resolves
-to the newest release every run and executes it immediately — the pattern supply-chain
-guidance warns against, since uv applies no release “cool-off” by default. If you prefer
-to always track the latest release but still want a safety delay, opt into uv’s cool-off,
-which excludes very recent uploads:
+**A note on freshness and safety.** These examples use `@latest` for simplicity. Because
+repren has **zero runtime dependencies**, the only code fetched and run is repren itself —
+there is no transitive dependency tree to audit or be compromised — so `@latest` carries
+far less supply-chain risk here than for a typical package. If you want an extra safety
+margin, you can opt into uv’s release “cool-off” (which excludes very recent uploads), or
+pin an exact version:
 
 ```bash
-# Only resolve versions at least 14 days old, then run latest-within-that-window:
+# Skip uploads newer than 14 days, then run the latest within that window:
 UV_EXCLUDE_NEWER="14 days" uvx repren@latest --help
-```
 
-repren’s zero-dependency design keeps this risk small either way: the only code fetched
-and run is repren itself.
+# Or pin an exact version:
+uvx repren@2.0.0 --help
+```
 
 ## Agent Use
 
 **The one thing to know:** point your agent at repren’s self-documenting help and let it
 install itself —
 
-> Run `uvx repren@2.1.0 --help` and follow the instructions to install repren
-> as a skill.
+> Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
 repren’s `--help` ends with the exact install commands, so the agent can take it from
-there. (`uvx` runs repren with no prior install; the example pins a version, which is
-safer than `@latest` — see the note under [Installation](#installation).)
+there. (`uvx` runs repren with no prior install; see the note on `@latest` and safety
+under [Installation](#installation).)
 
 **Install the skill yourself** (the same thing the agent does):
 
 ```bash
 # Install into the current project (run from the repo; shareable via git):
-uvx repren@2.1.0 --install-skill --project
+uvx repren@latest --install-skill --project
 
 # Or install globally, for every project:
-uvx repren@2.1.0 --install-skill --global
+uvx repren@latest --install-skill --global
 ```
 
 Re-run any time to update an existing install.
@@ -259,10 +257,11 @@ agent finds it:
 - `.claude/skills/repren/` — the Claude Code mirror
 
 repren is a general-purpose utility with no per-project config, so the skill invokes it
-through a **pinned zero-install runner** (`uvx repren@<version>`) — there’s no need to add
-repren as a project dependency, and each installed skill pins the version it came from.
-Combined with repren’s zero runtime dependencies, the code an agent ever fetches and runs
-is just repren itself.
+through a zero-install runner (`uvx`) — there’s no need to add repren as a project
+dependency. The installed `SKILL.md` **pins the exact version it was generated from**
+(`uvx repren@<version>`), so the agent’s repeated invocations are reproducible, even
+though the human quick-start above uses `@latest` for convenience. Combined with repren’s
+zero runtime dependencies, the code an agent ever fetches and runs is just repren itself.
 
 **Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
 not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
diff --git a/devtools/gendocs.py b/devtools/gendocs.py
index 05950f6..d3be05b 100644
--- a/devtools/gendocs.py
+++ b/devtools/gendocs.py
@@ -5,58 +5,12 @@
 The manual is the single source of truth. This script:
 1. Updates the docstring in repren/repren.py
 2. Updates the documentation section in README.md
-
-The manual may use the ``{{REPREN_VERSION}}`` placeholder anywhere it shows a pinned
-``uvx repren@<version>`` invocation; this script substitutes the current version so the
-docs stay pinned (supply-chain hygiene) without anyone hand-editing version strings. The
-version is resolved from, in order: ``REPREN_DOCS_VERSION`` (release automation), the
-installed package version when it is a clean release, then ``DEFAULT_DOC_VERSION``.
 """
 
-import importlib.metadata
-import os
 import re
 import sys
 from pathlib import Path
 
-# Placeholder used in the manual for the pinned repren version (matches claude_skill).
-VERSION_PLACEHOLDER = "{{REPREN_VERSION}}"
-
-# Fallback shown in docs when no released package version is resolvable (e.g. an editable
-# dev checkout). Set to the version currently being prepared; release builds override it
-# automatically with the real package version, so this rarely needs touching.
-DEFAULT_DOC_VERSION = "2.1.0"
-
-
-def _is_clean_release(version: str) -> bool:
-    """True for a published release version (no dev/pre-release or local segment)."""
-    return bool(re.fullmatch(r"\d+\.\d+(?:\.\d+)?", version))
-
-
-def get_doc_version() -> str:
-    """Resolve the version to pin in generated docs.
-
-    Order: ``REPREN_DOCS_VERSION`` env override → installed package version (only if it is
-    a clean release) → ``DEFAULT_DOC_VERSION``.
-    """
-    override = os.environ.get("REPREN_DOCS_VERSION")
-    if override:
-        return override.lstrip("v")
-
-    try:
-        version = importlib.metadata.version("repren")
-        if _is_clean_release(version):
-            return version
-    except importlib.metadata.PackageNotFoundError:
-        pass
-
-    return DEFAULT_DOC_VERSION
-
-
-def render_version(text: str, version: str) -> str:
-    """Substitute the version placeholder in manual text."""
-    return text.replace(VERSION_PLACEHOLDER, version)
-
 
 def read_manual(repo_root: Path) -> str:
     """Read the manual content."""
@@ -92,13 +46,7 @@ def update_repren_py(repo_root: Path, manual: str) -> bool:
     return True
 
 
-# Pinned-version invocations in the hand-written README header (e.g. the agent
-# quick-start), normalized to the current version on each run so the header stays in sync
-# without manual edits. Scoped to the header only, which never mentions `@latest`.
-_HEADER_PIN_RE = re.compile(r"uvx repren@[A-Za-z0-9][A-Za-z0-9._-]*")
-
-
-def update_readme(repo_root: Path, manual: str, version: str) -> bool:
+def update_readme(repo_root: Path, manual: str) -> bool:
     """Update the documentation section in README.md."""
     readme_path = repo_root / "README.md"
     content = readme_path.read_text()
@@ -116,13 +64,11 @@ def update_readme(repo_root: Path, manual: str, version: str) -> bool:
         print("ERROR: Could not find documentation section in README.md", file=sys.stderr)
         return False
 
-    # The hand-written header is not regenerated from the manual, so normalize any
-    # `uvx repren@<version>` pins in it to the current version (idempotent).
-    header = _HEADER_PIN_RE.sub(f"uvx repren@{version}", content[: match.start()])
-
     # Build new content using string concatenation (not re.sub) to avoid
     # backreference issues with \1, \2, etc. in the manual
-    new_content = header + match.group(1) + manual + match.group(3) + content[match.end() :]
+    new_content = (
+        content[: match.start()] + match.group(1) + manual + match.group(3) + content[match.end() :]
+    )
 
     if new_content != content:
         readme_path.write_text(new_content)
@@ -139,13 +85,9 @@ def main() -> int:
     print("Reading manual from docs/repren-docs.md...")
     manual = read_manual(repo_root)
 
-    version = get_doc_version()
-    print(f"Pinning docs to repren version: {version}")
-    manual = render_version(manual, version)
-
     success = True
     success = update_repren_py(repo_root, manual) and success
-    success = update_readme(repo_root, manual, version) and success
+    success = update_readme(repo_root, manual) and success
 
     return 0 if success else 1
 
diff --git a/docs/repren-docs.md b/docs/repren-docs.md
index e875f79..2fc598a 100644
--- a/docs/repren-docs.md
+++ b/docs/repren-docs.md
@@ -10,8 +10,7 @@ file refactoring tool.
 **Using a coding agent?** This is the whole setup — tell Claude Code, Codex, Gemini, or
 any agent:
 
-> Run `uvx repren@{{REPREN_VERSION}} --help` and follow the instructions to install repren
-> as a skill.
+> Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
 repren’s `--help` ends with the exact install commands, so the agent reads them and takes
 it from there. After that it reaches for repren automatically on bulk refactors and
@@ -19,7 +18,7 @@ renames. (See [Agent Use](#agent-use).)
 
 **Zero dependencies, by design.** Given the rise of supply-chain attacks on package
 ecosystems, it’s worth noting that repren has **zero runtime dependencies** — installing
-it (or running `uvx repren@<version>`) pulls in nothing but repren itself and the Python
+it (or running `uvx repren@latest`) pulls in nothing but repren itself and the Python
 standard library. There is no transitive dependency tree to audit or to be compromised,
 so it is simpler and safer to adopt than most tools. It’s also a single file you can read
 end to end (or have your agent review) before you trust it. The dev-only tooling used to
@@ -172,52 +171,51 @@ a transitive dependency tree to your environment. It’s easiest to install with
 [uv](https://docs.astral.sh/uv/):
 
 ```bash
-# Install as a tool (pin a version you trust):
+# Install as a tool:
 uv tool install repren
 
-# Or run directly without installing, pinned to a known version:
-uvx repren@{{REPREN_VERSION}} --help
+# Or run directly without installing:
+uvx repren@latest --help
 ```
 
 Or, since it’s just one file, you can copy the
 [repren.py](https://raw.githubusercontent.com/jlevy/repren/master/repren/repren.py)
 script somewhere convenient and make it executable.
 
-**A note on pinning (supply-chain hygiene).** The examples here pin an explicit version
-(`repren@{{REPREN_VERSION}}`) rather than `@latest`. An unpinned `uvx repren@latest` re-resolves
-to the newest release every run and executes it immediately — the pattern supply-chain
-guidance warns against, since uv applies no release “cool-off” by default. If you prefer
-to always track the latest release but still want a safety delay, opt into uv’s cool-off,
-which excludes very recent uploads:
+**A note on freshness and safety.** These examples use `@latest` for simplicity. Because
+repren has **zero runtime dependencies**, the only code fetched and run is repren itself —
+there is no transitive dependency tree to audit or be compromised — so `@latest` carries
+far less supply-chain risk here than for a typical package. If you want an extra safety
+margin, you can opt into uv’s release “cool-off” (which excludes very recent uploads), or
+pin an exact version:
 
 ```bash
-# Only resolve versions at least 14 days old, then run latest-within-that-window:
+# Skip uploads newer than 14 days, then run the latest within that window:
 UV_EXCLUDE_NEWER="14 days" uvx repren@latest --help
-```
 
-repren’s zero-dependency design keeps this risk small either way: the only code fetched
-and run is repren itself.
+# Or pin an exact version:
+uvx repren@2.0.0 --help
+```
 
 ## Agent Use
 
 **The one thing to know:** point your agent at repren’s self-documenting help and let it
 install itself —
 
-> Run `uvx repren@{{REPREN_VERSION}} --help` and follow the instructions to install repren
-> as a skill.
+> Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
 repren’s `--help` ends with the exact install commands, so the agent can take it from
-there. (`uvx` runs repren with no prior install; the example pins a version, which is
-safer than `@latest` — see the note under [Installation](#installation).)
+there. (`uvx` runs repren with no prior install; see the note on `@latest` and safety
+under [Installation](#installation).)
 
 **Install the skill yourself** (the same thing the agent does):
 
 ```bash
 # Install into the current project (run from the repo; shareable via git):
-uvx repren@{{REPREN_VERSION}} --install-skill --project
+uvx repren@latest --install-skill --project
 
 # Or install globally, for every project:
-uvx repren@{{REPREN_VERSION}} --install-skill --global
+uvx repren@latest --install-skill --global
 ```
 
 Re-run any time to update an existing install.
@@ -235,10 +233,11 @@ agent finds it:
 - `.claude/skills/repren/` — the Claude Code mirror
 
 repren is a general-purpose utility with no per-project config, so the skill invokes it
-through a **pinned zero-install runner** (`uvx repren@<version>`) — there’s no need to add
-repren as a project dependency, and each installed skill pins the version it came from.
-Combined with repren’s zero runtime dependencies, the code an agent ever fetches and runs
-is just repren itself.
+through a zero-install runner (`uvx`) — there’s no need to add repren as a project
+dependency. The installed `SKILL.md` **pins the exact version it was generated from**
+(`uvx repren@<version>`), so the agent’s repeated invocations are reproducible, even
+though the human quick-start above uses `@latest` for convenience. Combined with repren’s
+zero runtime dependencies, the code an agent ever fetches and runs is just repren itself.
 
 **Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
 not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
diff --git a/repren/repren.py b/repren/repren.py
index 874de7a..b738169 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -12,8 +12,7 @@
 **Using a coding agent?** This is the whole setup — tell Claude Code, Codex, Gemini, or
 any agent:
 
-> Run `uvx repren@2.1.0 --help` and follow the instructions to install repren
-> as a skill.
+> Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
 repren’s `--help` ends with the exact install commands, so the agent reads them and takes
 it from there. After that it reaches for repren automatically on bulk refactors and
@@ -21,7 +20,7 @@
 
 **Zero dependencies, by design.** Given the rise of supply-chain attacks on package
 ecosystems, it’s worth noting that repren has **zero runtime dependencies** — installing
-it (or running `uvx repren@<version>`) pulls in nothing but repren itself and the Python
+it (or running `uvx repren@latest`) pulls in nothing but repren itself and the Python
 standard library. There is no transitive dependency tree to audit or to be compromised,
 so it is simpler and safer to adopt than most tools. It’s also a single file you can read
 end to end (or have your agent review) before you trust it. The dev-only tooling used to
@@ -174,52 +173,51 @@
 [uv](https://docs.astral.sh/uv/):
 
 ```bash
-# Install as a tool (pin a version you trust):
+# Install as a tool:
 uv tool install repren
 
-# Or run directly without installing, pinned to a known version:
-uvx repren@2.1.0 --help
+# Or run directly without installing:
+uvx repren@latest --help
 ```
 
 Or, since it’s just one file, you can copy the
 [repren.py](https://raw.githubusercontent.com/jlevy/repren/master/repren/repren.py)
 script somewhere convenient and make it executable.
 
-**A note on pinning (supply-chain hygiene).** The examples here pin an explicit version
-(`repren@2.1.0`) rather than `@latest`. An unpinned `uvx repren@latest` re-resolves
-to the newest release every run and executes it immediately — the pattern supply-chain
-guidance warns against, since uv applies no release “cool-off” by default. If you prefer
-to always track the latest release but still want a safety delay, opt into uv’s cool-off,
-which excludes very recent uploads:
+**A note on freshness and safety.** These examples use `@latest` for simplicity. Because
+repren has **zero runtime dependencies**, the only code fetched and run is repren itself —
+there is no transitive dependency tree to audit or be compromised — so `@latest` carries
+far less supply-chain risk here than for a typical package. If you want an extra safety
+margin, you can opt into uv’s release “cool-off” (which excludes very recent uploads), or
+pin an exact version:
 
 ```bash
-# Only resolve versions at least 14 days old, then run latest-within-that-window:
+# Skip uploads newer than 14 days, then run the latest within that window:
 UV_EXCLUDE_NEWER="14 days" uvx repren@latest --help
-```
 
-repren’s zero-dependency design keeps this risk small either way: the only code fetched
-and run is repren itself.
+# Or pin an exact version:
+uvx repren@2.0.0 --help
+```
 
 ## Agent Use
 
 **The one thing to know:** point your agent at repren’s self-documenting help and let it
 install itself —
 
-> Run `uvx repren@2.1.0 --help` and follow the instructions to install repren
-> as a skill.
+> Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
 repren’s `--help` ends with the exact install commands, so the agent can take it from
-there. (`uvx` runs repren with no prior install; the example pins a version, which is
-safer than `@latest` — see the note under [Installation](#installation).)
+there. (`uvx` runs repren with no prior install; see the note on `@latest` and safety
+under [Installation](#installation).)
 
 **Install the skill yourself** (the same thing the agent does):
 
 ```bash
 # Install into the current project (run from the repo; shareable via git):
-uvx repren@2.1.0 --install-skill --project
+uvx repren@latest --install-skill --project
 
 # Or install globally, for every project:
-uvx repren@2.1.0 --install-skill --global
+uvx repren@latest --install-skill --global
 ```
 
 Re-run any time to update an existing install.
@@ -237,10 +235,11 @@
 - `.claude/skills/repren/` — the Claude Code mirror
 
 repren is a general-purpose utility with no per-project config, so the skill invokes it
-through a **pinned zero-install runner** (`uvx repren@<version>`) — there’s no need to add
-repren as a project dependency, and each installed skill pins the version it came from.
-Combined with repren’s zero runtime dependencies, the code an agent ever fetches and runs
-is just repren itself.
+through a zero-install runner (`uvx`) — there’s no need to add repren as a project
+dependency. The installed `SKILL.md` **pins the exact version it was generated from**
+(`uvx repren@<version>`), so the agent’s repeated invocations are reproducible, even
+though the human quick-start above uses `@latest` for convenience. Combined with repren’s
+zero runtime dependencies, the code an agent ever fetches and runs is just repren itself.
 
 **Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
 not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
diff --git a/tests/pytests.py b/tests/pytests.py
index 4f3bba1..2b8f02a 100644
--- a/tests/pytests.py
+++ b/tests/pytests.py
@@ -494,63 +494,6 @@ def test_clean_backups_conflicts_with_patterns(self):
 # --- Claude Skill tests ---
 
 
-def _load_gendocs():
-    """Load the devtools/gendocs.py module by path (it is not an installed package)."""
-    import importlib.util
-
-    gendocs_path = Path(__file__).parent.parent / "devtools" / "gendocs.py"
-    spec = importlib.util.spec_from_file_location("gendocs", gendocs_path)
-    assert spec and spec.loader
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-class TestGendocsVersionPinning:
-    """Tests for the docs version-pinning mechanism in devtools/gendocs.py."""
-
-    def test_env_override_wins(self, monkeypatch):
-        gendocs = _load_gendocs()
-        monkeypatch.setenv("REPREN_DOCS_VERSION", "v9.9.9")
-        # Leading "v" is stripped.
-        assert gendocs.get_doc_version() == "9.9.9"
-
-    def test_dev_version_falls_back_to_default(self, monkeypatch):
-        gendocs = _load_gendocs()
-        monkeypatch.delenv("REPREN_DOCS_VERSION", raising=False)
-        # The editable checkout reports a dev version, so the default is used.
-        assert gendocs.get_doc_version() == gendocs.DEFAULT_DOC_VERSION
-
-    def test_is_clean_release(self):
-        gendocs = _load_gendocs()
-        assert gendocs._is_clean_release("2.1.0")
-        assert gendocs._is_clean_release("2.1")
-        assert not gendocs._is_clean_release("2.1.0.dev3")
-        assert not gendocs._is_clean_release("2.1.0+gabc")
-        assert not gendocs._is_clean_release("latest")
-
-    def test_render_version_substitutes_placeholder(self):
-        gendocs = _load_gendocs()
-        rendered = gendocs.render_version("run uvx repren@{{REPREN_VERSION}} --help", "2.1.0")
-        assert rendered == "run uvx repren@2.1.0 --help"
-        assert "{{REPREN_VERSION}}" not in rendered
-
-    def test_header_pin_regex_is_idempotent(self):
-        gendocs = _load_gendocs()
-        once = gendocs._HEADER_PIN_RE.sub("uvx repren@2.1.0", "see uvx repren@1.0.0 --help")
-        twice = gendocs._HEADER_PIN_RE.sub("uvx repren@2.1.0", once)
-        assert once == "see uvx repren@2.1.0 --help"
-        assert once == twice
-
-    def test_generated_docs_have_no_placeholder(self):
-        """The committed generated docs must not contain the raw version placeholder."""
-        repo_root = Path(__file__).parent.parent
-        readme = (repo_root / "README.md").read_text()
-        repren_py = (repo_root / "repren" / "repren.py").read_text()
-        assert "{{REPREN_VERSION}}" not in readme
-        assert "{{REPREN_VERSION}}" not in repren_py
-
-
 class TestClaudeSkillContent:
     """Tests for Claude skill content loading."""
 

From 9255e4d00de36509b75a05b70014c292a9df91ab Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 06:58:42 +0000
Subject: [PATCH 07/18] skill: make repren the clear default for bulk renames

Strengthen SKILL.md so agents understand repren's benefits and reach for it on
large-scale renames instead of hand-editing file by file or scripting sed/perl loops.

- Rewrite the `description` frontmatter (the agent's trigger) to position repren as the
  preferred tool for multi-file renames/search-replace, naming the differentiating
  features: combined content+filename changes, simultaneous/swap replacements,
  case-variant awareness, and dry-run/backups/undo.
- Add a "Prefer Repren for Bulk Renames" section spelling out each benefit and when it
  wins over manual edits or sed/perl/awk.
- Frame "When to Use Repren" as the default choice.
- Update the two tryscript goldens that snapshot the description line.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 repren/skills/SKILL.md                        | 42 +++++++++++++++----
 tests/tryscript/advanced-options.tryscript.md |  2 +-
 tests/tryscript/help-errors.tryscript.md      |  2 +-
 3 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/repren/skills/SKILL.md b/repren/skills/SKILL.md
index 821096c..9a91f8c 100644
--- a/repren/skills/SKILL.md
+++ b/repren/skills/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: repren
-description: Performs simultaneous multi-pattern search-and-replace, file/directory renaming, and case-preserving refactoring across codebases. Use for bulk refactoring, global find-and-replace, or when user mentions repren, multi-file rename, or pattern-based transformations.
+description: The preferred tool for large-scale or multi-file renames and search-and-replace. Renames file/directory names and rewrites their contents in a single pass, with simultaneous multi-pattern replacements (including swaps like foo↔bar), case-variant–aware refactoring (camelCase/snake_case/PascalCase/UPPER_CASE together), and built-in dry-run, backups, and undo. Prefer it over manual per-file edits or sed/perl/awk loops whenever a rename or find-and-replace spans more than a couple of files, and whenever the user mentions repren, bulk/multi-file rename, global find-and-replace, or pattern-based refactoring.
 allowed-tools: Bash(repren:*), Bash(uvx repren@{{REPREN_VERSION}}:*), Read, Write
 ---
 # Repren - Multi-Pattern Search and Replace
@@ -15,6 +15,31 @@ allowed-tools: Bash(repren:*), Bash(uvx repren@{{REPREN_VERSION}}:*), Read, Writ
 Multi-pattern search/replace tool for bulk refactoring with simultaneous replacements,
 file/directory renaming, and case-preserving transformations.
 
+## Prefer Repren for Bulk Renames
+
+For any rename or find-and-replace that spans **more than a file or two**, reach for
+repren first — don’t hand-edit file by file or script a `sed`/`perl`/`awk` loop. A single
+repren command does what those approaches do awkwardly or not at all, and does it safely:
+
+- **Combined content + filename changes in one pass.** With `--full`, repren rewrites
+  file *contents* and renames the matching *files and directories* together, creating
+  parent directories as needed — so renaming a module and every reference to it is one
+  command, not two error-prone steps.
+- **Simultaneous multi-pattern replacement, including swaps.** Apply many patterns at
+  once from a patterns file, and even circular renames (`foo`→`bar` and `bar`→`foo`) in a
+  single pass — impossible with naive sequential replaces, which clobber each other.
+- **Case-variant awareness.** `--preserve-case` rewrites every case form of an identifier
+  consistently (`my_var`/`myVar`/`MyVar`/`MY_VAR`), which a plain string replace misses.
+- **Safe by default: dry-run, backups, and undo.** Preview every change with
+  `--dry-run`, fall back to automatic `.orig` backups, and reverse a run with `--undo`.
+  Edits are atomic, so an interrupted run never leaves a half-written file.
+- **Precise scoping.** `--word-breaks`, `--literal`, `--include`/`--exclude`, and
+  `--at-once` (multi-line) keep matches exactly where you intend.
+
+When a task is “rename X to Y across the codebase” or “replace these N patterns
+everywhere,” repren is almost always the right tool. Reserve hand edits for one-off
+single-file changes and AST tools for language-aware semantic refactors (see below).
+
 ## Quick Start
 
 **Always start with dry-run** to preview changes:
@@ -29,18 +54,17 @@ repren --from='old_name' --to='new_name' --full src/
 
 ## When to Use Repren
 
-**Use repren for:**
+**Use repren (the default choice) for:**
 - Large-scale code refactoring (renaming across many files)
-- Simultaneous multi-pattern replacements
-- File and directory renaming based on content patterns
-- Case-preserving identifier transformations
-- Operations requiring dry-run validation and backups
-- Swapping or circular renames (foo↔bar)
+- Renaming a symbol *and* the files/directories named after it, in one pass (`--full`)
+- Simultaneous multi-pattern replacements, including swaps or circular renames (foo↔bar)
+- Case-preserving identifier transformations (camelCase/snake_case/PascalCase/UPPER_CASE)
+- Any change you want to preview (`--dry-run`), back up, and be able to `--undo`
 
 **Don’t use repren for:**
-- Single-file small edits or replacements (use Edit tool instead)
+- Single-file small edits or one-off replacements (use the Edit tool instead)
 - Language-aware semantic refactoring (use AST tools like ast-grep, ts-morph)
-- Operations requiring precise line-by-line control (use Edit tool)
+- Operations requiring precise line-by-line control (use the Edit tool)
 
 ## Core Features
 
diff --git a/tests/tryscript/advanced-options.tryscript.md b/tests/tryscript/advanced-options.tryscript.md
index f3be751..4b76290 100644
--- a/tests/tryscript/advanced-options.tryscript.md
+++ b/tests/tryscript/advanced-options.tryscript.md
@@ -104,7 +104,7 @@ Frontmatter (stable top lines, version-independent):
 $ sed -n '1,3p' agentrepo/.claude/skills/repren/SKILL.md
 ---
 name: repren
-description: Performs simultaneous multi-pattern search-and-replace, file/directory renaming, and case-preserving refactoring across codebases. Use for bulk refactoring, global find-and-replace, or when user mentions repren, multi-file rename, or pattern-based transformations.
+description: The preferred tool for large-scale or multi-file renames and search-and-replace. Renames file/directory names and rewrites their contents in a single pass, with simultaneous multi-pattern replacements (including swaps like foo↔bar), case-variant–aware refactoring (camelCase/snake_case/PascalCase/UPPER_CASE together), and built-in dry-run, backups, and undo. Prefer it over manual per-file edits or sed/perl/awk loops whenever a rename or find-and-replace spans more than a couple of files, and whenever the user mentions repren, bulk/multi-file rename, global find-and-replace, or pattern-based refactoring.
 ? 0
 ```
 
diff --git a/tests/tryscript/help-errors.tryscript.md b/tests/tryscript/help-errors.tryscript.md
index 64d9b9c..d0edfd9 100644
--- a/tests/tryscript/help-errors.tryscript.md
+++ b/tests/tryscript/help-errors.tryscript.md
@@ -73,7 +73,7 @@ Powerful CLI string replacement and file renaming for agents and humans
 $ repren --skill | head -3
 ---
 name: repren
-description: Performs simultaneous multi-pattern search-and-replace, file/directory renaming, and case-preserving refactoring across codebases. Use for bulk refactoring, global find-and-replace, or when user mentions repren, multi-file rename, or pattern-based transformations.
+description: The preferred tool for large-scale or multi-file renames and search-and-replace. Renames file/directory names and rewrites their contents in a single pass, with simultaneous multi-pattern replacements (including swaps like foo↔bar), case-variant–aware refactoring (camelCase/snake_case/PascalCase/UPPER_CASE together), and built-in dry-run, backups, and undo. Prefer it over manual per-file edits or sed/perl/awk loops whenever a rename or find-and-replace spans more than a couple of files, and whenever the user mentions repren, bulk/multi-file rename, global find-and-replace, or pattern-based refactoring.
 ? 0
 ```
 

From 63673211519a2890b3704dc61aee3f746597407a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 07:08:33 +0000
Subject: [PATCH 08/18] skill: use uvx repren@latest; add supply-chain doc;
 clarify .gitignore
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Switch the skill runner to @latest and remove the version-injection machinery, relying
on uv's release cool-off for protection — repren has zero runtime dependencies, so the
only code a runner fetches is repren itself, which makes @latest a documented exception
to the "pin zero-install runners" rule.

- SKILL.md / claude_skill.py: invoke `uvx repren@latest`; drop the {{REPREN_VERSION}}
  placeholder, _pinned_version(), and _render_skill(). get_skill_content() now just reads
  the file. Update the matching unit test and tryscript golden (which now assert @latest
  is used and the placeholder never leaks).
- docs: reframe the manual's "how it works" around @latest + UV_EXCLUDE_NEWER cool-off.
- Add SUPPLY-CHAIN-SECURITY.md (the portable hardening flag file) per the supply-chain
  hardening guideline: runtime risk is minimal here (zero deps), but the 14-day cool-off,
  lockfile discipline, and audit rules still apply to the dev dependency toolchain.
  Reference it from AGENTS.md (CLAUDE.md symlinks to it) so agents see it before adding
  deps.
- Clarify in SKILL.md and the manual that repren does not read .gitignore: dotfiles
  (incl. .git/) are excluded by default; richer scoping needs explicit --include/--exclude.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 AGENTS.md                                     |  2 +
 README.md                                     | 19 +++--
 SUPPLY-CHAIN-SECURITY.md                      | 76 +++++++++++++++++++
 docs/repren-docs.md                           | 19 +++--
 repren/claude_skill.py                        | 44 ++---------
 repren/repren.py                              | 19 +++--
 repren/skills/SKILL.md                        | 13 +++-
 tests/pytests.py                              | 19 ++---
 tests/tryscript/advanced-options.tryscript.md | 12 +--
 9 files changed, 142 insertions(+), 81 deletions(-)
 create mode 100644 SUPPLY-CHAIN-SECURITY.md

diff --git a/AGENTS.md b/AGENTS.md
index 5268e68..24b1e84 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,8 @@
 IMPORTANT: You MUST read ./docs/development.md and ./docs/docs-overview.md for project documentation.
 (This project uses Speculate project structure.)
 
+IMPORTANT: Before adding or upgrading any dependency, read ./SUPPLY-CHAIN-SECURITY.md.
+
 
 <!-- BEGIN TBD INTEGRATION format=f04 surface=agents-md -->
 ## tbd
diff --git a/README.md b/README.md
index 3dc5b92..487b81e 100644
--- a/README.md
+++ b/README.md
@@ -257,11 +257,11 @@ agent finds it:
 - `.claude/skills/repren/` — the Claude Code mirror
 
 repren is a general-purpose utility with no per-project config, so the skill invokes it
-through a zero-install runner (`uvx`) — there’s no need to add repren as a project
-dependency. The installed `SKILL.md` **pins the exact version it was generated from**
-(`uvx repren@<version>`), so the agent’s repeated invocations are reproducible, even
-though the human quick-start above uses `@latest` for convenience. Combined with repren’s
-zero runtime dependencies, the code an agent ever fetches and runs is just repren itself.
+through the zero-install runner `uvx repren@latest` — there’s no need to add repren as a
+project dependency. Because repren has **zero runtime dependencies**, the only code a
+runner ever fetches and runs is repren itself; for an extra safety margin you can opt into
+uv’s release cool-off (`UV_EXCLUDE_NEWER`, see [Installation](#installation)) in your
+environment, which applies to the skill’s invocations too.
 
 **Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
 not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
@@ -457,9 +457,12 @@ repren --clean-backups mydir/
 - Backups are created of all modified files, with the suffix “.orig”.
   The suffix can be customized with `--backup-suffix`.
 
-- By default, recursive searching omits paths starting with “.”. This may be adjusted
-  with `--exclude`. Files ending in the backup suffix (`.orig` by default) are always
-  ignored.
+- By default, recursive searching omits paths starting with “.” (including `.git/`). This
+  may be adjusted with `--exclude`. Files ending in the backup suffix (`.orig` by default)
+  are always ignored. repren does **not** read `.gitignore`: any other paths you want to
+  skip — `node_modules/`, `build/`, `dist/`, vendored code — must be named explicitly with
+  `--exclude`, and richer scoping is done with `--include`/`--exclude` (preview with
+  `--dry-run`).
 
 - Data is handled as bytes internally, allowing it to work with any encoding or binary
   files. File contents are not decoded unless necessary (e.g., for logging).
diff --git a/SUPPLY-CHAIN-SECURITY.md b/SUPPLY-CHAIN-SECURITY.md
new file mode 100644
index 0000000..0b0a444
--- /dev/null
+++ b/SUPPLY-CHAIN-SECURITY.md
@@ -0,0 +1,76 @@
+# Supply-Chain Security
+
+This repo follows the **Supply-Chain Hardening** policy (the 14-day cool-off, disabled
+install scripts, lockfile discipline). This file is the portable flag that tells any
+agent or contributor the rules *before* they add or upgrade a dependency. The full
+cross-ecosystem policy lives in `tbd guidelines supply-chain-hardening`; the complete
+playbooks are at <https://github.com/jlevy/supply-chain-hardening>.
+
+## What's special about repren: zero runtime dependencies
+
+repren has **zero runtime dependencies** (`dependencies = []` in `pyproject.toml`). It is
+a single-file tool that imports only the Python standard library. So:
+
+- **For people who *run* repren, supply-chain risk is minimal.** `uvx repren@latest` (or
+  `uv tool install repren`) fetches and executes only repren itself — there is no
+  transitive dependency tree to be compromised. This is exactly why the docs and the
+  installed agent skill use `uvx repren@latest` rather than a pinned version: with no
+  dependency tree, the usual reason to pin a zero-install runner mostly falls away.
+- **A cool-off is still recommended, just lower-stakes.** If you want an extra safety
+  margin against a compromised repren *release* itself, opt into uv's release cool-off so
+  very recent uploads are skipped:
+
+  ```bash
+  # Skip uploads newer than 14 days, then run the latest within that window:
+  UV_EXCLUDE_NEWER="14 days" uvx repren@latest --help
+  ```
+
+  Set `UV_EXCLUDE_NEWER` in your environment and it applies to every `uvx`/`uv` call,
+  including the agent skill's invocations.
+
+> **Deliberate exception to the "no unpinned runners" rule.** The hardening policy says to
+> pin zero-install runners (`uvx pkg@version`, not `@latest`). repren takes the documented
+> exception: because it has no dependency tree, `@latest` + the cool-off above gives the
+> protection that pinning is meant to provide, with less version-management complexity.
+> This exception is scoped to repren's *own* runner — it does **not** relax the cool-off
+> for the development dependencies below.
+
+## Development dependencies: the cool-off applies here
+
+The zero-deps story is about *runtime*. The **dev toolchain** (in `[dependency-groups]`:
+pytest, ruff, basedpyright, jinja2, rich, etc.) runs with full privileges during local
+development, tests, and CI — historically the *more* dangerous surface, since build and
+test tooling execute arbitrary code. The 14-day cool-off and the other install rules
+apply in full here:
+
+- **Cool-off (resolution-time gate).** Resolve dev dependencies with a release-age gate:
+
+  ```bash
+  export UV_EXCLUDE_NEWER="14 days"   # never resolve a version less than 14 days old
+  uv sync --frozen                    # install the dev group from the committed lockfile
+  ```
+
+  Keep `UV_EXCLUDE_NEWER` in your shell profile (and in CI) so it covers every resolve.
+- **Lockfile discipline.** `uv.lock` is committed. Install frozen (`uv sync --frozen` /
+  `uv run --frozen`); never re-resolve in CI. Review a lockfile diff like a code diff.
+- **Don't update for its own sake.** The safest upgrade is the one you skip. Bump a dev
+  dependency only for a concrete reason, let it clear the cool-off, and review the diff.
+- **Audit.** Run `uvx pip-audit` (or `uv run pip-audit`) and address findings before
+  continuing. Prefer wheels over building sdists from source (`UV_NO_BUILD` /
+  `--only-binary`) where feasible.
+- **Exceptions are explicit and human-approved.** If a dev dependency version inside the
+  14-day window is genuinely needed (e.g. a CVE patch), pin the exact version, record the
+  reason and a `Reviewed-by:` sign-off in the PR, and confirm afterward it wasn't yanked.
+  Agents never self-approve an exception.
+
+## Quick reference
+
+| Context | Rule |
+| --- | --- |
+| Running repren | Zero deps; `uvx repren@latest` is fine. Optional: `UV_EXCLUDE_NEWER="14 days"`. |
+| Adding/upgrading a **dev** dependency | 14-day cool-off, lockfile-pinned, audited, reason on the record. |
+| Publishing repren | Build from a clean tag; prefer trusted publishing / provenance (see the guidebook). |
+
+<!-- This document follows the Supply-Chain Hardening guideline
+(tbd guidelines supply-chain-hardening) and common-doc-guidelines.md.
+See github.com/jlevy/supply-chain-hardening before editing. -->
diff --git a/docs/repren-docs.md b/docs/repren-docs.md
index 2fc598a..d471d1a 100644
--- a/docs/repren-docs.md
+++ b/docs/repren-docs.md
@@ -233,11 +233,11 @@ agent finds it:
 - `.claude/skills/repren/` — the Claude Code mirror
 
 repren is a general-purpose utility with no per-project config, so the skill invokes it
-through a zero-install runner (`uvx`) — there’s no need to add repren as a project
-dependency. The installed `SKILL.md` **pins the exact version it was generated from**
-(`uvx repren@<version>`), so the agent’s repeated invocations are reproducible, even
-though the human quick-start above uses `@latest` for convenience. Combined with repren’s
-zero runtime dependencies, the code an agent ever fetches and runs is just repren itself.
+through the zero-install runner `uvx repren@latest` — there’s no need to add repren as a
+project dependency. Because repren has **zero runtime dependencies**, the only code a
+runner ever fetches and runs is repren itself; for an extra safety margin you can opt into
+uv’s release cool-off (`UV_EXCLUDE_NEWER`, see [Installation](#installation)) in your
+environment, which applies to the skill’s invocations too.
 
 **Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
 not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
@@ -433,9 +433,12 @@ repren --clean-backups mydir/
 - Backups are created of all modified files, with the suffix “.orig”.
   The suffix can be customized with `--backup-suffix`.
 
-- By default, recursive searching omits paths starting with “.”. This may be adjusted
-  with `--exclude`. Files ending in the backup suffix (`.orig` by default) are always
-  ignored.
+- By default, recursive searching omits paths starting with “.” (including `.git/`). This
+  may be adjusted with `--exclude`. Files ending in the backup suffix (`.orig` by default)
+  are always ignored. repren does **not** read `.gitignore`: any other paths you want to
+  skip — `node_modules/`, `build/`, `dist/`, vendored code — must be named explicitly with
+  `--exclude`, and richer scoping is done with `--include`/`--exclude` (preview with
+  `--dry-run`).
 
 - Data is handled as bytes internally, allowing it to work with any encoding or binary
   files. File contents are not decoded unless necessary (e.g., for logging).
diff --git a/repren/claude_skill.py b/repren/claude_skill.py
index ff7784c..e8a5f0d 100644
--- a/repren/claude_skill.py
+++ b/repren/claude_skill.py
@@ -10,18 +10,15 @@
 Scope is resolved `git config`-style — implicit when unambiguous, a hard error when not
 (see `resolve_install_target`).
 
-The skill text in ``skills/SKILL.md`` is a template: the ``{{REPREN_VERSION}}``
-placeholder is replaced with the installed repren version so the skill's pinned
-zero-install fallback (``uvx repren@<version>``) always matches what produced it.
+The skill invokes repren through ``uvx repren@latest``. repren has zero runtime
+dependencies, so the only code a runner ever fetches is repren itself; for an extra
+safety margin, opt into uv's release cool-off (``UV_EXCLUDE_NEWER``) in your environment.
 """
 
 import sys
 from dataclasses import dataclass
 from pathlib import Path
 
-# Placeholder in skills/SKILL.md replaced with the installed repren version at render time.
-VERSION_PLACEHOLDER = "{{REPREN_VERSION}}"
-
 # Surfaces the skill is written to, beneath the resolved install root.
 SKILL_SURFACES: list[tuple[str, str]] = [
     ("portable", ".agents"),  # cross-agent: Codex, Gemini CLI, pi, others
@@ -33,36 +30,11 @@ class SkillScopeError(Exception):
     """Raised when the skill install scope cannot be resolved unambiguously."""
 
 
-def _pinned_version() -> str:
-    """Return the installed repren version suitable for a ``uvx repren@<version>`` pin.
-
-    Any PEP 440 local-version segment (after ``+``) is dropped, since local versions are
-    never available from a package index and so could not be installed by ``uvx``.
-    """
-    import importlib.metadata
-
-    try:
-        version = importlib.metadata.version("repren")
-    except importlib.metadata.PackageNotFoundError:
-        version = "0.0.0.dev"
-    return version.split("+", 1)[0]
-
-
-def _render_skill(template: str) -> str:
-    """Substitute the version placeholder in the skill template.
-
-    The installed repren version is injected so the skill's pinned
-    ``uvx repren@<version>`` fallback matches the package that produced it.
-    """
-    return template.replace(VERSION_PLACEHOLDER, _pinned_version())
-
-
 def get_skill_content() -> str:
-    """Read SKILL.md from package data and render it for the installed version.
+    """Read SKILL.md from package data.
 
     Returns:
-        The rendered SKILL.md content, with ``{{REPREN_VERSION}}`` replaced by the
-        installed repren version.
+        The SKILL.md content.
 
     Raises:
         ImportError: If package resources cannot be accessed.
@@ -73,21 +45,19 @@ def get_skill_content() -> str:
         from importlib.resources import files
 
         skill_file = files("repren").joinpath("skills/SKILL.md")
-        template = skill_file.read_text(encoding="utf-8")
+        return skill_file.read_text(encoding="utf-8")
     except (ImportError, AttributeError):
         # Fallback for older Python versions
         try:
             import pkg_resources  # type: ignore[import-not-found]  # pyright: ignore[reportMissingImports]
 
-            template = pkg_resources.resource_string("repren", "skills/SKILL.md").decode("utf-8")
+            return pkg_resources.resource_string("repren", "skills/SKILL.md").decode("utf-8")
         except Exception as e:
             raise ImportError(
                 f"Could not load skill from package data: {e}\n"
                 "Ensure repren is installed as a package, not run as a standalone script."
             ) from e
 
-    return _render_skill(template)
-
 
 @dataclass
 class InstallTarget:
diff --git a/repren/repren.py b/repren/repren.py
index b738169..dc82f43 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -235,11 +235,11 @@
 - `.claude/skills/repren/` — the Claude Code mirror
 
 repren is a general-purpose utility with no per-project config, so the skill invokes it
-through a zero-install runner (`uvx`) — there’s no need to add repren as a project
-dependency. The installed `SKILL.md` **pins the exact version it was generated from**
-(`uvx repren@<version>`), so the agent’s repeated invocations are reproducible, even
-though the human quick-start above uses `@latest` for convenience. Combined with repren’s
-zero runtime dependencies, the code an agent ever fetches and runs is just repren itself.
+through the zero-install runner `uvx repren@latest` — there’s no need to add repren as a
+project dependency. Because repren has **zero runtime dependencies**, the only code a
+runner ever fetches and runs is repren itself; for an extra safety margin you can opt into
+uv’s release cool-off (`UV_EXCLUDE_NEWER`, see [Installation](#installation)) in your
+environment, which applies to the skill’s invocations too.
 
 **Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
 not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
@@ -435,9 +435,12 @@
 - Backups are created of all modified files, with the suffix “.orig”.
   The suffix can be customized with `--backup-suffix`.
 
-- By default, recursive searching omits paths starting with “.”. This may be adjusted
-  with `--exclude`. Files ending in the backup suffix (`.orig` by default) are always
-  ignored.
+- By default, recursive searching omits paths starting with “.” (including `.git/`). This
+  may be adjusted with `--exclude`. Files ending in the backup suffix (`.orig` by default)
+  are always ignored. repren does **not** read `.gitignore`: any other paths you want to
+  skip — `node_modules/`, `build/`, `dist/`, vendored code — must be named explicitly with
+  `--exclude`, and richer scoping is done with `--include`/`--exclude` (preview with
+  `--dry-run`).
 
 - Data is handled as bytes internally, allowing it to work with any encoding or binary
   files. File contents are not decoded unless necessary (e.g., for logging).
diff --git a/repren/skills/SKILL.md b/repren/skills/SKILL.md
index 9a91f8c..ccbf280 100644
--- a/repren/skills/SKILL.md
+++ b/repren/skills/SKILL.md
@@ -1,14 +1,15 @@
 ---
 name: repren
 description: The preferred tool for large-scale or multi-file renames and search-and-replace. Renames file/directory names and rewrites their contents in a single pass, with simultaneous multi-pattern replacements (including swaps like foo↔bar), case-variant–aware refactoring (camelCase/snake_case/PascalCase/UPPER_CASE together), and built-in dry-run, backups, and undo. Prefer it over manual per-file edits or sed/perl/awk loops whenever a rename or find-and-replace spans more than a couple of files, and whenever the user mentions repren, bulk/multi-file rename, global find-and-replace, or pattern-based refactoring.
-allowed-tools: Bash(repren:*), Bash(uvx repren@{{REPREN_VERSION}}:*), Read, Write
+allowed-tools: Bash(repren:*), Bash(uvx repren@latest:*), Read, Write
 ---
 # Repren - Multi-Pattern Search and Replace
 
 > **Invocation:** The examples below call `repren` directly, which assumes it is on your
 > `PATH` (e.g. installed via `uv tool install repren`). If `repren` is not installed,
-> replace `repren` with the pinned zero-install runner `uvx repren@{{REPREN_VERSION}}` in
-> every command — it needs no prior install and pins a known version.
+> replace `repren` with the zero-install runner `uvx repren@latest` in every command — it
+> needs no prior install. repren has zero runtime dependencies, so the only code fetched
+> and run is repren itself.
 >
 > **Full documentation:** Run `repren --docs` for all options, flags, and advanced usage.
 
@@ -181,6 +182,12 @@ Exclude directories:
 repren --patterns=patterns.txt --exclude='tests|node_modules|__pycache__' --full src/
 ```
 
+**Note on `.gitignore`:** repren does *not* read `.gitignore`. By default it skips only
+dotfiles and dot-directories (anything starting with `.`, including `.git/`), so VCS
+internals are left alone. Anything else you want skipped — `node_modules/`, `build/`,
+`dist/`, `target/`, vendored code — must be named explicitly via `--exclude` (or scoped
+in with `--include`). Always confirm scope with `--dry-run` before a real run.
+
 ### Word Boundaries
 
 Match only at word boundaries (safer for variable names):
diff --git a/tests/pytests.py b/tests/pytests.py
index 2b8f02a..de93a7d 100644
--- a/tests/pytests.py
+++ b/tests/pytests.py
@@ -520,21 +520,16 @@ def test_skill_content_has_required_sections(self):
         # Should mention key features
         assert "pattern" in content.lower() or "replace" in content.lower()
 
-    def test_skill_content_pins_version_no_latest(self):
-        """Rendered skill should pin the installed version, not use an unpinned @latest."""
-        from repren.claude_skill import VERSION_PLACEHOLDER, get_skill_content
-        from repren.repren import VERSION
+    def test_skill_content_uses_latest_runner(self):
+        """Skill uses the @latest zero-install runner; protection comes from uv cool-off."""
+        from repren.claude_skill import get_skill_content
 
         content = get_skill_content()
 
-        # Placeholder must be rendered away.
-        assert VERSION_PLACEHOLDER not in content
-        # Unpinned runner must not appear (supply-chain hygiene).
-        assert "repren@latest" not in content
-        # The pinned zero-install fallback must reference the installed public version
-        # (any PEP 440 local "+..." segment is dropped, since it is not installable).
-        pinned_version = VERSION.split("+", 1)[0]
-        assert f"uvx repren@{pinned_version}" in content
+        # No leftover templating: the version-injection mechanism was removed.
+        assert "{{REPREN_VERSION}}" not in content
+        # The zero-install fallback uses @latest.
+        assert "uvx repren@latest" in content
 
 
 class TestClaudeSkillScopeResolution:
diff --git a/tests/tryscript/advanced-options.tryscript.md b/tests/tryscript/advanced-options.tryscript.md
index 4b76290..901ffc9 100644
--- a/tests/tryscript/advanced-options.tryscript.md
+++ b/tests/tryscript/advanced-options.tryscript.md
@@ -108,17 +108,19 @@ description: The preferred tool for large-scale or multi-file renames and search
 ? 0
 ```
 
-The skill uses a pinned zero-install runner, never an unpinned `@latest`:
+The skill uses the `@latest` zero-install runner (protection comes from uv's cool-off):
 
 ```console
-$ grep -q 'repren@latest' agentrepo/.claude/skills/repren/SKILL.md && echo found || echo none
-none
+$ grep -q 'uvx repren@latest' agentrepo/.claude/skills/repren/SKILL.md && echo found || echo none
+found
 ? 0
 ```
 
+The version-injection placeholder must never leak into the installed skill:
+
 ```console
-$ grep -Eq 'uvx repren@[0-9]' agentrepo/.claude/skills/repren/SKILL.md && echo pinned
-pinned
+$ grep -q '{{REPREN_VERSION}}' agentrepo/.claude/skills/repren/SKILL.md && echo leaked || echo clean
+clean
 ? 0
 ```
 

From 1415fc2af1f9ded6f9c1abeae77188d0176c0c94 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 07:25:28 +0000
Subject: [PATCH 09/18] docs: show uvx install form in --help skill hint

An agent that discovers repren via `uvx repren@latest --help` has no `repren` on PATH,
so the install hint now shows the zero-install form alongside the on-PATH one. This
closes the discoverability loop: point an agent at the repo, it runs the suggested uvx
call, and the help epilog hands it the exact command to install repren as a skill.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 repren/repren.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/repren/repren.py b/repren/repren.py
index dc82f43..c138f79 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -546,6 +546,7 @@ def _get_version() -> str:
 IMPORTANT — Use repren as an agent skill (Claude Code, Codex, Gemini, and others):
   Install into your project:  repren --install-skill            (run inside the repo)
   Install for all projects:   repren --install-skill --global
+  Not installed? Use uvx:     uvx repren@latest --install-skill  (add --project or --global)
 Once installed, your coding agent uses repren automatically for refactoring tasks."""
 
 # Terminal width handling.

From dc9e9bd87f95e443c3086fd07644165503a01ba1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 07:53:22 +0000
Subject: [PATCH 10/18] fix: install skill at repo root; portable scope tests;
 honest supply-chain doc

Address PR review findings:

- [P1] resolve_install_target now installs at the git repository root for implicit and
  bare --project scope, instead of whatever subdirectory the command ran from. An
  explicit --dir still wins as given. Add a _git_root() helper (matches .git as dir or
  file, so worktrees/submodules work) and a nested-dir CLI + unit regression test.
- [P2] Make the scope-resolution unit tests portable: compare against resolved paths
  (home.resolve(), tmp_path.resolve()) so they pass on macOS, where /home and /tmp
  canonicalize. docs/development.md tells contributors to run `uv run pytest`.
- [P2] SUPPLY-CHAIN-SECURITY.md no longer over-claims full compliance: it now "adopts"
  the policy and records the unpinned zero-install dev/CI runners (uvx flowmark@latest,
  npx tryscript@latest) as tracked exceptions to pin in a follow-up.

The skill's `uvx repren@latest` runner is intentionally unpinned (zero runtime deps +
documented UV_EXCLUDE_NEWER cool-off) and is recorded as a deliberate exception.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 SUPPLY-CHAIN-SECURITY.md | 24 +++++++++++++++++++++-
 repren/claude_skill.py   | 27 ++++++++++++++++++------
 tests/pytests.py         | 44 +++++++++++++++++++++++++++++++++++++---
 3 files changed, 85 insertions(+), 10 deletions(-)

diff --git a/SUPPLY-CHAIN-SECURITY.md b/SUPPLY-CHAIN-SECURITY.md
index 0b0a444..3ba9045 100644
--- a/SUPPLY-CHAIN-SECURITY.md
+++ b/SUPPLY-CHAIN-SECURITY.md
@@ -1,11 +1,15 @@
 # Supply-Chain Security
 
-This repo follows the **Supply-Chain Hardening** policy (the 14-day cool-off, disabled
+This repo **adopts** the **Supply-Chain Hardening** policy (the 14-day cool-off, disabled
 install scripts, lockfile discipline). This file is the portable flag that tells any
 agent or contributor the rules *before* they add or upgrade a dependency. The full
 cross-ecosystem policy lives in `tbd guidelines supply-chain-hardening`; the complete
 playbooks are at <https://github.com/jlevy/supply-chain-hardening>.
 
+The runtime story is already clean (zero dependencies, below); the dev/CI toolchain is
+mostly there, with a few unpinned zero-install runners tracked as known exceptions under
+[Known exceptions](#known-exceptions).
+
 ## What's special about repren: zero runtime dependencies
 
 repren has **zero runtime dependencies** (`dependencies = []` in `pyproject.toml`). It is
@@ -63,12 +67,30 @@ apply in full here:
   reason and a `Reviewed-by:` sign-off in the PR, and confirm afterward it wasn't yanked.
   Agents never self-approve an exception.
 
+## Known exceptions
+
+Being honest about where the repo does not yet meet the policy, so agents don't read a
+standard the workflow silently breaks:
+
+- **`repren`'s own runner uses `@latest`, unpinned** (docs, README, and the installed
+  `SKILL.md`). This is deliberate: repren has zero runtime dependencies, so `@latest`
+  fetches only repren itself, and the recommended `UV_EXCLUDE_NEWER` cool-off covers the
+  compromised-release case. See "What's special about repren," above.
+- **Unpinned zero-install dev/CI runners.** A few development and CI commands still invoke
+  zero-install runners without a version pin — `uvx flowmark@latest` (formatting, in the
+  `Makefile`) and `npx tryscript@latest` (the golden test harness, in `.github/workflows/`
+  and the dev docs). These run only at development/CI time, never for users of repren, but
+  they do bypass the cool-off. They are tracked here to be pinned (or run under a CI-level
+  `UV_EXCLUDE_NEWER`/`npm` release-age gate) in a follow-up; until then they are recorded
+  exceptions, not an oversight.
+
 ## Quick reference
 
 | Context | Rule |
 | --- | --- |
 | Running repren | Zero deps; `uvx repren@latest` is fine. Optional: `UV_EXCLUDE_NEWER="14 days"`. |
 | Adding/upgrading a **dev** dependency | 14-day cool-off, lockfile-pinned, audited, reason on the record. |
+| Dev/CI zero-install runners (flowmark, tryscript) | Tracked exception — to be pinned; see [Known exceptions](#known-exceptions). |
 | Publishing repren | Build from a clean tag; prefer trusted publishing / provenance (see the guidebook). |
 
 <!-- This document follows the Supply-Chain Hardening guideline
diff --git a/repren/claude_skill.py b/repren/claude_skill.py
index e8a5f0d..b8be376 100644
--- a/repren/claude_skill.py
+++ b/repren/claude_skill.py
@@ -72,12 +72,22 @@ class InstallTarget:
     mode: str
 
 
-def _in_git_repo(path: Path) -> bool:
-    """Return True if ``path`` is inside a git repository (a ``.git`` exists at or above)."""
+def _git_root(path: Path) -> Path | None:
+    """Return the repository root for ``path`` (nearest ancestor with a ``.git``), or None.
+
+    ``.git`` is matched whether it is a directory (normal clone) or a file (worktree or
+    submodule gitlink), so installs land at the repo root rather than the subdirectory the
+    command happened to run from.
+    """
     for candidate in (path, *path.parents):
         if (candidate / ".git").exists():
-            return True
-    return False
+            return candidate
+    return None
+
+
+def _in_git_repo(path: Path) -> bool:
+    """Return True if ``path`` is inside a git repository (a ``.git`` exists at or above)."""
+    return _git_root(path) is not None
 
 
 def resolve_install_target(
@@ -138,8 +148,13 @@ def resolve_install_target(
     if mode == "global":
         return InstallTarget(root=home, mode="global")
 
-    # Project mode.
-    root = Path(dir).resolve() if dir is not None else cwd
+    # Project mode. An explicit --dir wins as given; otherwise install at the repository
+    # root (not the subdirectory the command ran from), so `repren --install-skill` from
+    # `repo/subdir` writes to `repo/`, matching the documented project-local behavior.
+    if dir is not None:
+        root = Path(dir).resolve()
+    else:
+        root = _git_root(cwd) or cwd
     if root == home:
         # --project --dir ~ is always refused; that is exactly what --global is for.
         raise SkillScopeError(
diff --git a/tests/pytests.py b/tests/pytests.py
index de93a7d..4dee18d 100644
--- a/tests/pytests.py
+++ b/tests/pytests.py
@@ -541,7 +541,9 @@ def test_explicit_global(self):
         home = Path("/home/someone")
         target = resolve_install_target(global_install=True, home=home, cwd=Path("/tmp/x"))
         assert target.mode == "global"
-        assert target.root == home
+        # The implementation resolves the home path; compare against the resolved form so
+        # the test is portable to platforms where these paths canonicalize (e.g. macOS).
+        assert target.root == home.resolve()
 
     def test_explicit_project_with_dir(self):
         from repren.claude_skill import resolve_install_target
@@ -557,7 +559,21 @@ def test_implicit_project_inside_repo(self, tmp_path):
         (tmp_path / ".git").mkdir()
         target = resolve_install_target(cwd=tmp_path, home=Path("/home/someone"))
         assert target.mode == "project"
-        assert target.root == tmp_path
+        assert target.root == tmp_path.resolve()
+
+    def test_implicit_project_uses_repo_root_from_subdir(self, tmp_path):
+        """Run from a nested dir, project install still lands at the repo root, not cwd."""
+        from repren.claude_skill import resolve_install_target
+
+        (tmp_path / ".git").mkdir()
+        subdir = tmp_path / "src" / "deep"
+        subdir.mkdir(parents=True)
+        # Both implicit scope and an explicit --project should resolve to the repo root.
+        implicit = resolve_install_target(cwd=subdir, home=tmp_path.parent)
+        explicit = resolve_install_target(cwd=subdir, home=tmp_path.parent, project=True)
+        for target in (implicit, explicit):
+            assert target.mode == "project"
+            assert target.root == tmp_path.resolve()
 
     def test_ambiguous_outside_repo_errors(self, tmp_path):
         from repren.claude_skill import SkillScopeError, resolve_install_target
@@ -572,7 +588,7 @@ def test_project_no_repo_check_allows_non_repo(self, tmp_path):
             project=True, no_repo_check=True, cwd=tmp_path, home=Path("/home/someone")
         )
         assert target.mode == "project"
-        assert target.root == tmp_path
+        assert target.root == tmp_path.resolve()
 
     def test_home_is_refused_in_project_mode(self, tmp_path):
         from repren.claude_skill import SkillScopeError, resolve_install_target
@@ -686,6 +702,28 @@ def test_install_skill_project_dir(self):
             assert (Path(tmpdir) / ".agents" / "skills" / "repren" / "SKILL.md").exists()
             assert (Path(tmpdir) / ".claude" / "skills" / "repren" / "SKILL.md").exists()
 
+    def test_install_skill_from_subdir_lands_at_repo_root(self):
+        """Implicit --install-skill run from a nested dir writes to the repo root."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            repo = Path(tmpdir).resolve()
+            (repo / ".git").mkdir()
+            subdir = repo / "src" / "deep"
+            subdir.mkdir(parents=True)
+
+            result = subprocess.run(
+                ["uv", "run", "repren", "--install-skill"],
+                capture_output=True,
+                text=True,
+                cwd=subdir,
+            )
+
+            assert result.returncode == 0, result.stderr
+            # Lands at the repo root, not the nested cwd.
+            assert (repo / ".agents" / "skills" / "repren" / "SKILL.md").exists()
+            assert (repo / ".claude" / "skills" / "repren" / "SKILL.md").exists()
+            assert not (subdir / ".agents").exists()
+            assert not (subdir / ".claude").exists()
+
     def test_install_skill_global(self):
         """--install-skill --global should write both surfaces under $HOME."""
         with tempfile.TemporaryDirectory() as tmpdir:

From 4a8b73cd303915e43f7c89441184799c8e953da3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 07:55:13 +0000
Subject: [PATCH 11/18] docs: add atomic-ops and agent-skill rows to comparison
 table

Expand the "Comparison to Alternatives" table with two researched, sourced rows:

- Atomic file operations: repren and sd write content via temp-file + atomic rename;
  rnr only renames (atomic); sed/awk/perl varies (GNU sed and gawk inplace are atomic,
  perl -i only on >=5.28, a plain redirect never); fastmod/ast-grep/comby overwrite in
  place.
- Agent skill support: repren ships a skill via --install-skill; ast-grep ships an
  official agent skill + MCP server; the others have no first-party agent integration.

Add explanatory notes under the table and mention ast-grep's agent skill/MCP in its
"when to use" bullet, so the comparison stays accurate (repren is not the only tool with
agent integration). Regenerated README + docstring from the manual.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 README.md           | 22 ++++++++++++++++++++--
 docs/repren-docs.md | 22 ++++++++++++++++++++--
 repren/repren.py    | 22 ++++++++++++++++++++--
 3 files changed, 60 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 487b81e..a39a0ac 100644
--- a/README.md
+++ b/README.md
@@ -162,13 +162,29 @@ Here’s how repren compares:
 | Case-preserving variants | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
 | Language-agnostic | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
 | Structural/AST-aware | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
+| Atomic file operations | ✅ | Varies | ✅ | ❌ | ❌ | ❌ | ✅ |
 | Interactivity | Dry run, backups, undo | ❌ | ❌ | Interactive review | Interactive review | Interactive review | Dry run, backups, undo |
+| Agent skill support | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
 | Dependencies | Python 3.10+ (no other deps) | Varies (OS/shell) | Binary (Rust) | Binary (Rust) | Binary (Rust) | Binary (OCaml) | Binary (Rust) |
 
+Notes on the last two rows:
+
+- **Atomic file operations** means edits are written to a temp file and atomically
+  renamed into place, so an interruption never leaves a truncated or half-written file.
+  repren and `sd` do this for content edits; `rnr` only renames (and `rename()` is itself
+  atomic). For the classics it *varies*: GNU `sed -i` and `gawk -i inplace` use
+  temp+rename, but `perl -i` is only atomic on Perl ≥ 5.28, and a plain `cmd > file`
+  redirect is never atomic. `fastmod`, `ast-grep`, and `comby` overwrite files in place.
+- **Agent skill support** means the project ships an official coding-agent integration
+  (a skill or MCP server) so an agent can discover and drive it. repren installs a skill
+  via `repren --install-skill`; `ast-grep` ships an official agent skill and MCP server.
+  The others have no first-party agent integration.
+
 **When to use each:**
 
 - **repren**: Bulk renames with file/directory renaming, case preservation, or
-  simultaneous swaps. Works on any text file with full backup/undo support.
+  simultaneous swaps. Works on any text file, with atomic writes and full backup/undo
+  support.
 - **sed/awk/perl**: Classic approaches for quick one-liners.
   See
   [classic approaches](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549).
@@ -180,7 +196,9 @@ Here’s how repren compares:
   preservation, simultaneous swaps, and file/directory renaming.
 - **ast-grep**: Language-aware refactoring where you need to match code structure (e.g.,
   function calls, not just text).
-  Use when semantic understanding matters more than speed.
+  Use when semantic understanding matters more than speed. It also ships an official agent
+  skill and MCP server, so it’s a strong companion to repren for agent-driven, AST-aware
+  edits.
 - **comby**: Structural matching across languages without learning AST syntax.
   Useful when you need to match code patterns like balanced braces, but overkill for
   simple text refactoring.
diff --git a/docs/repren-docs.md b/docs/repren-docs.md
index d471d1a..4468051 100644
--- a/docs/repren-docs.md
+++ b/docs/repren-docs.md
@@ -138,13 +138,29 @@ Here’s how repren compares:
 | Case-preserving variants | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
 | Language-agnostic | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
 | Structural/AST-aware | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
+| Atomic file operations | ✅ | Varies | ✅ | ❌ | ❌ | ❌ | ✅ |
 | Interactivity | Dry run, backups, undo | ❌ | ❌ | Interactive review | Interactive review | Interactive review | Dry run, backups, undo |
+| Agent skill support | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
 | Dependencies | Python 3.10+ (no other deps) | Varies (OS/shell) | Binary (Rust) | Binary (Rust) | Binary (Rust) | Binary (OCaml) | Binary (Rust) |
 
+Notes on the last two rows:
+
+- **Atomic file operations** means edits are written to a temp file and atomically
+  renamed into place, so an interruption never leaves a truncated or half-written file.
+  repren and `sd` do this for content edits; `rnr` only renames (and `rename()` is itself
+  atomic). For the classics it *varies*: GNU `sed -i` and `gawk -i inplace` use
+  temp+rename, but `perl -i` is only atomic on Perl ≥ 5.28, and a plain `cmd > file`
+  redirect is never atomic. `fastmod`, `ast-grep`, and `comby` overwrite files in place.
+- **Agent skill support** means the project ships an official coding-agent integration
+  (a skill or MCP server) so an agent can discover and drive it. repren installs a skill
+  via `repren --install-skill`; `ast-grep` ships an official agent skill and MCP server.
+  The others have no first-party agent integration.
+
 **When to use each:**
 
 - **repren**: Bulk renames with file/directory renaming, case preservation, or
-  simultaneous swaps. Works on any text file with full backup/undo support.
+  simultaneous swaps. Works on any text file, with atomic writes and full backup/undo
+  support.
 - **sed/awk/perl**: Classic approaches for quick one-liners.
   See
   [classic approaches](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549).
@@ -156,7 +172,9 @@ Here’s how repren compares:
   preservation, simultaneous swaps, and file/directory renaming.
 - **ast-grep**: Language-aware refactoring where you need to match code structure (e.g.,
   function calls, not just text).
-  Use when semantic understanding matters more than speed.
+  Use when semantic understanding matters more than speed. It also ships an official agent
+  skill and MCP server, so it’s a strong companion to repren for agent-driven, AST-aware
+  edits.
 - **comby**: Structural matching across languages without learning AST syntax.
   Useful when you need to match code patterns like balanced braces, but overkill for
   simple text refactoring.
diff --git a/repren/repren.py b/repren/repren.py
index c138f79..34e67f1 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -140,13 +140,29 @@
 | Case-preserving variants | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
 | Language-agnostic | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
 | Structural/AST-aware | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
+| Atomic file operations | ✅ | Varies | ✅ | ❌ | ❌ | ❌ | ✅ |
 | Interactivity | Dry run, backups, undo | ❌ | ❌ | Interactive review | Interactive review | Interactive review | Dry run, backups, undo |
+| Agent skill support | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
 | Dependencies | Python 3.10+ (no other deps) | Varies (OS/shell) | Binary (Rust) | Binary (Rust) | Binary (Rust) | Binary (OCaml) | Binary (Rust) |
 
+Notes on the last two rows:
+
+- **Atomic file operations** means edits are written to a temp file and atomically
+  renamed into place, so an interruption never leaves a truncated or half-written file.
+  repren and `sd` do this for content edits; `rnr` only renames (and `rename()` is itself
+  atomic). For the classics it *varies*: GNU `sed -i` and `gawk -i inplace` use
+  temp+rename, but `perl -i` is only atomic on Perl ≥ 5.28, and a plain `cmd > file`
+  redirect is never atomic. `fastmod`, `ast-grep`, and `comby` overwrite files in place.
+- **Agent skill support** means the project ships an official coding-agent integration
+  (a skill or MCP server) so an agent can discover and drive it. repren installs a skill
+  via `repren --install-skill`; `ast-grep` ships an official agent skill and MCP server.
+  The others have no first-party agent integration.
+
 **When to use each:**
 
 - **repren**: Bulk renames with file/directory renaming, case preservation, or
-  simultaneous swaps. Works on any text file with full backup/undo support.
+  simultaneous swaps. Works on any text file, with atomic writes and full backup/undo
+  support.
 - **sed/awk/perl**: Classic approaches for quick one-liners.
   See
   [classic approaches](http://stackoverflow.com/questions/11392478/how-to-replace-a-string-in-multiple-files-in-linux-command-line/29191549).
@@ -158,7 +174,9 @@
   preservation, simultaneous swaps, and file/directory renaming.
 - **ast-grep**: Language-aware refactoring where you need to match code structure (e.g.,
   function calls, not just text).
-  Use when semantic understanding matters more than speed.
+  Use when semantic understanding matters more than speed. It also ships an official agent
+  skill and MCP server, so it’s a strong companion to repren for agent-driven, AST-aware
+  edits.
 - **comby**: Structural matching across languages without learning AST syntax.
   Useful when you need to match code patterns like balanced braces, but overkill for
   simple text refactoring.

From 9f94615c4a43c973f7642f3216160b85e229ed53 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 08:08:40 +0000
Subject: [PATCH 12/18] refactor: rename claude_skill to agent_skill; minimize
 em dashes per doc guidelines

The skill module is generic across coding agents (Claude Code, Codex, Gemini, and
others), so the Claude-specific name no longer fits.

- Rename repren/claude_skill.py to repren/agent_skill.py (git rename) and update its
  imports, the internal --install-skill dest (install_claude_skill -> install_skill), and
  the module's own self-references. The CLI surface (--install-skill) is unchanged, and
  the module is internal, so no compatibility shim is needed.
- Rewrite the test imports using repren itself.

Apply common-doc-guidelines across the docs we own: minimize em dashes (prefer full
stops, commas, colons, semicolons), and write "and" rather than "+" in prose. Covers the
manual (docs/repren-docs.md), README header, SKILL.md, SUPPLY-CHAIN-SECURITY.md, the
agent_skill.py docstring, and the --help SKILL_HINT. Regenerated README and the docstring
from the manual; updated the matching help golden. The one remaining em dash is in the
tbd-managed AGENTS.md block, which tbd regenerates.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 README.md                                  | 31 ++++++++--------
 SUPPLY-CHAIN-SECURITY.md                   | 10 +++---
 docs/repren-docs.md                        | 29 +++++++--------
 repren/{claude_skill.py => agent_skill.py} |  8 ++---
 repren/repren.py                           | 41 +++++++++++-----------
 repren/skills/SKILL.md                     | 17 ++++-----
 tests/pytests.py                           | 32 ++++++++---------
 tests/tryscript/help-errors.tryscript.md   |  2 +-
 8 files changed, 87 insertions(+), 83 deletions(-)
 rename repren/{claude_skill.py => agent_skill.py} (97%)

diff --git a/README.md b/README.md
index a39a0ac..6ef224e 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@
 > renames. See [Agent Use](#agent-use) for details.
 
 > [!TIP]
-> 🔒 **Zero dependencies.** repren has **zero runtime dependencies** — just Python and a
+> 🔒 **Zero dependencies.** repren has **zero runtime dependencies**: just Python and a
 > single file. Amid the rise of supply-chain attacks on package ecosystems, that means
 > there’s no transitive dependency tree to audit or be compromised: the only code `uvx
 > repren@latest` ever fetches and runs is repren itself, and you (or your agent) can review
@@ -31,7 +31,7 @@ It is small, self-contained, self-documenting, and works on Python 3.10-3.14 wit
 **zero runtime dependencies**. Essentially, it is a general-purpose, brute-force text
 file refactoring tool.
 
-**Using a coding agent?** This is the whole setup — tell Claude Code, Codex, Gemini, or
+**Using a coding agent?** This is the whole setup. Tell Claude Code, Codex, Gemini, or
 any agent:
 
 > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
@@ -41,7 +41,7 @@ it from there. After that it reaches for repren automatically on bulk refactors
 renames. (See [Agent Use](#agent-use).)
 
 **Zero dependencies, by design.** Given the rise of supply-chain attacks on package
-ecosystems, it’s worth noting that repren has **zero runtime dependencies** — installing
+ecosystems, it’s worth noting that repren has **zero runtime dependencies**. Installing
 it (or running `uvx repren@latest`) pulls in nothing but repren itself and the Python
 standard library. There is no transitive dependency tree to audit or to be compromised,
 so it is simpler and safer to adopt than most tools. It’s also a single file you can read
@@ -172,9 +172,10 @@ Notes on the last two rows:
 - **Atomic file operations** means edits are written to a temp file and atomically
   renamed into place, so an interruption never leaves a truncated or half-written file.
   repren and `sd` do this for content edits; `rnr` only renames (and `rename()` is itself
-  atomic). For the classics it *varies*: GNU `sed -i` and `gawk -i inplace` use
-  temp+rename, but `perl -i` is only atomic on Perl ≥ 5.28, and a plain `cmd > file`
-  redirect is never atomic. `fastmod`, `ast-grep`, and `comby` overwrite files in place.
+  atomic). For the classics it *varies*: GNU `sed -i` and `gawk -i inplace` write to a
+  temp file and rename, but `perl -i` is only atomic on Perl ≥ 5.28, and a plain
+  `cmd > file` redirect is never atomic. `fastmod`, `ast-grep`, and `comby` overwrite
+  files in place.
 - **Agent skill support** means the project ships an official coding-agent integration
   (a skill or MCP server) so an agent can discover and drive it. repren installs a skill
   via `repren --install-skill`; `ast-grep` ships an official agent skill and MCP server.
@@ -225,8 +226,8 @@ Or, since it’s just one file, you can copy the
 script somewhere convenient and make it executable.
 
 **A note on freshness and safety.** These examples use `@latest` for simplicity. Because
-repren has **zero runtime dependencies**, the only code fetched and run is repren itself —
-there is no transitive dependency tree to audit or be compromised — so `@latest` carries
+repren has **zero runtime dependencies**, the only code fetched and run is repren itself.
+There is no transitive dependency tree to audit or be compromised, so `@latest` carries
 far less supply-chain risk here than for a typical package. If you want an extra safety
 margin, you can opt into uv’s release “cool-off” (which excludes very recent uploads), or
 pin an exact version:
@@ -242,7 +243,7 @@ uvx repren@2.0.0 --help
 ## Agent Use
 
 **The one thing to know:** point your agent at repren’s self-documenting help and let it
-install itself —
+install itself.
 
 > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
@@ -271,18 +272,18 @@ skill is just a thin pointer to those commands, so it never drifts out of date.
 Installing the skill writes one `SKILL.md` to **both** discovery locations, so every
 agent finds it:
 
-- `.agents/skills/repren/` — the portable, cross-agent location (Codex, Gemini, pi, …)
-- `.claude/skills/repren/` — the Claude Code mirror
+- `.agents/skills/repren/`: the portable, cross-agent location (Codex, Gemini, pi, …)
+- `.claude/skills/repren/`: the Claude Code mirror
 
 repren is a general-purpose utility with no per-project config, so the skill invokes it
-through the zero-install runner `uvx repren@latest` — there’s no need to add repren as a
+through the zero-install runner `uvx repren@latest`. There’s no need to add repren as a
 project dependency. Because repren has **zero runtime dependencies**, the only code a
 runner ever fetches and runs is repren itself; for an extra safety margin you can opt into
 uv’s release cool-off (`UV_EXCLUDE_NEWER`, see [Installation](#installation)) in your
 environment, which applies to the skill’s invocations too.
 
-**Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
-not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
+**Scope is resolved like `git config`:** implicit when unambiguous, a clear error when
+not, so a stray `--install-skill` never silently rewrites your global agent surfaces:
 
 - Inside a git repo, `--project` is implied (so `uvx repren --install-skill` just works).
 - In an ambiguous spot (your home directory, or outside any repo) repren refuses and
@@ -478,7 +479,7 @@ repren --clean-backups mydir/
 - By default, recursive searching omits paths starting with “.” (including `.git/`). This
   may be adjusted with `--exclude`. Files ending in the backup suffix (`.orig` by default)
   are always ignored. repren does **not** read `.gitignore`: any other paths you want to
-  skip — `node_modules/`, `build/`, `dist/`, vendored code — must be named explicitly with
+  skip (`node_modules/`, `build/`, `dist/`, vendored code) must be named explicitly with
   `--exclude`, and richer scoping is done with `--include`/`--exclude` (preview with
   `--dry-run`).
 
diff --git a/SUPPLY-CHAIN-SECURITY.md b/SUPPLY-CHAIN-SECURITY.md
index 3ba9045..268d737 100644
--- a/SUPPLY-CHAIN-SECURITY.md
+++ b/SUPPLY-CHAIN-SECURITY.md
@@ -16,7 +16,7 @@ repren has **zero runtime dependencies** (`dependencies = []` in `pyproject.toml
 a single-file tool that imports only the Python standard library. So:
 
 - **For people who *run* repren, supply-chain risk is minimal.** `uvx repren@latest` (or
-  `uv tool install repren`) fetches and executes only repren itself — there is no
+  `uv tool install repren`) fetches and executes only repren itself, so there is no
   transitive dependency tree to be compromised. This is exactly why the docs and the
   installed agent skill use `uvx repren@latest` rather than a pinned version: with no
   dependency tree, the usual reason to pin a zero-install runner mostly falls away.
@@ -36,14 +36,14 @@ a single-file tool that imports only the Python standard library. So:
 > pin zero-install runners (`uvx pkg@version`, not `@latest`). repren takes the documented
 > exception: because it has no dependency tree, `@latest` + the cool-off above gives the
 > protection that pinning is meant to provide, with less version-management complexity.
-> This exception is scoped to repren's *own* runner — it does **not** relax the cool-off
+> This exception is scoped to repren's *own* runner. It does **not** relax the cool-off
 > for the development dependencies below.
 
 ## Development dependencies: the cool-off applies here
 
 The zero-deps story is about *runtime*. The **dev toolchain** (in `[dependency-groups]`:
 pytest, ruff, basedpyright, jinja2, rich, etc.) runs with full privileges during local
-development, tests, and CI — historically the *more* dangerous surface, since build and
+development, tests, and CI, historically the *more* dangerous surface, since build and
 test tooling execute arbitrary code. The 14-day cool-off and the other install rules
 apply in full here:
 
@@ -77,7 +77,7 @@ standard the workflow silently breaks:
   fetches only repren itself, and the recommended `UV_EXCLUDE_NEWER` cool-off covers the
   compromised-release case. See "What's special about repren," above.
 - **Unpinned zero-install dev/CI runners.** A few development and CI commands still invoke
-  zero-install runners without a version pin — `uvx flowmark@latest` (formatting, in the
+  zero-install runners without a version pin: `uvx flowmark@latest` (formatting, in the
   `Makefile`) and `npx tryscript@latest` (the golden test harness, in `.github/workflows/`
   and the dev docs). These run only at development/CI time, never for users of repren, but
   they do bypass the cool-off. They are tracked here to be pinned (or run under a CI-level
@@ -90,7 +90,7 @@ standard the workflow silently breaks:
 | --- | --- |
 | Running repren | Zero deps; `uvx repren@latest` is fine. Optional: `UV_EXCLUDE_NEWER="14 days"`. |
 | Adding/upgrading a **dev** dependency | 14-day cool-off, lockfile-pinned, audited, reason on the record. |
-| Dev/CI zero-install runners (flowmark, tryscript) | Tracked exception — to be pinned; see [Known exceptions](#known-exceptions). |
+| Dev/CI zero-install runners (flowmark, tryscript) | Tracked exception, to be pinned; see [Known exceptions](#known-exceptions). |
 | Publishing repren | Build from a clean tag; prefer trusted publishing / provenance (see the guidebook). |
 
 <!-- This document follows the Supply-Chain Hardening guideline
diff --git a/docs/repren-docs.md b/docs/repren-docs.md
index 4468051..0d599d6 100644
--- a/docs/repren-docs.md
+++ b/docs/repren-docs.md
@@ -7,7 +7,7 @@ It is small, self-contained, self-documenting, and works on Python 3.10-3.14 wit
 **zero runtime dependencies**. Essentially, it is a general-purpose, brute-force text
 file refactoring tool.
 
-**Using a coding agent?** This is the whole setup — tell Claude Code, Codex, Gemini, or
+**Using a coding agent?** This is the whole setup. Tell Claude Code, Codex, Gemini, or
 any agent:
 
 > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
@@ -17,7 +17,7 @@ it from there. After that it reaches for repren automatically on bulk refactors
 renames. (See [Agent Use](#agent-use).)
 
 **Zero dependencies, by design.** Given the rise of supply-chain attacks on package
-ecosystems, it’s worth noting that repren has **zero runtime dependencies** — installing
+ecosystems, it’s worth noting that repren has **zero runtime dependencies**. Installing
 it (or running `uvx repren@latest`) pulls in nothing but repren itself and the Python
 standard library. There is no transitive dependency tree to audit or to be compromised,
 so it is simpler and safer to adopt than most tools. It’s also a single file you can read
@@ -148,9 +148,10 @@ Notes on the last two rows:
 - **Atomic file operations** means edits are written to a temp file and atomically
   renamed into place, so an interruption never leaves a truncated or half-written file.
   repren and `sd` do this for content edits; `rnr` only renames (and `rename()` is itself
-  atomic). For the classics it *varies*: GNU `sed -i` and `gawk -i inplace` use
-  temp+rename, but `perl -i` is only atomic on Perl ≥ 5.28, and a plain `cmd > file`
-  redirect is never atomic. `fastmod`, `ast-grep`, and `comby` overwrite files in place.
+  atomic). For the classics it *varies*: GNU `sed -i` and `gawk -i inplace` write to a
+  temp file and rename, but `perl -i` is only atomic on Perl ≥ 5.28, and a plain
+  `cmd > file` redirect is never atomic. `fastmod`, `ast-grep`, and `comby` overwrite
+  files in place.
 - **Agent skill support** means the project ships an official coding-agent integration
   (a skill or MCP server) so an agent can discover and drive it. repren installs a skill
   via `repren --install-skill`; `ast-grep` ships an official agent skill and MCP server.
@@ -201,8 +202,8 @@ Or, since it’s just one file, you can copy the
 script somewhere convenient and make it executable.
 
 **A note on freshness and safety.** These examples use `@latest` for simplicity. Because
-repren has **zero runtime dependencies**, the only code fetched and run is repren itself —
-there is no transitive dependency tree to audit or be compromised — so `@latest` carries
+repren has **zero runtime dependencies**, the only code fetched and run is repren itself.
+There is no transitive dependency tree to audit or be compromised, so `@latest` carries
 far less supply-chain risk here than for a typical package. If you want an extra safety
 margin, you can opt into uv’s release “cool-off” (which excludes very recent uploads), or
 pin an exact version:
@@ -218,7 +219,7 @@ uvx repren@2.0.0 --help
 ## Agent Use
 
 **The one thing to know:** point your agent at repren’s self-documenting help and let it
-install itself —
+install itself.
 
 > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
@@ -247,18 +248,18 @@ skill is just a thin pointer to those commands, so it never drifts out of date.
 Installing the skill writes one `SKILL.md` to **both** discovery locations, so every
 agent finds it:
 
-- `.agents/skills/repren/` — the portable, cross-agent location (Codex, Gemini, pi, …)
-- `.claude/skills/repren/` — the Claude Code mirror
+- `.agents/skills/repren/`: the portable, cross-agent location (Codex, Gemini, pi, …)
+- `.claude/skills/repren/`: the Claude Code mirror
 
 repren is a general-purpose utility with no per-project config, so the skill invokes it
-through the zero-install runner `uvx repren@latest` — there’s no need to add repren as a
+through the zero-install runner `uvx repren@latest`. There’s no need to add repren as a
 project dependency. Because repren has **zero runtime dependencies**, the only code a
 runner ever fetches and runs is repren itself; for an extra safety margin you can opt into
 uv’s release cool-off (`UV_EXCLUDE_NEWER`, see [Installation](#installation)) in your
 environment, which applies to the skill’s invocations too.
 
-**Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
-not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
+**Scope is resolved like `git config`:** implicit when unambiguous, a clear error when
+not, so a stray `--install-skill` never silently rewrites your global agent surfaces:
 
 - Inside a git repo, `--project` is implied (so `uvx repren --install-skill` just works).
 - In an ambiguous spot (your home directory, or outside any repo) repren refuses and
@@ -454,7 +455,7 @@ repren --clean-backups mydir/
 - By default, recursive searching omits paths starting with “.” (including `.git/`). This
   may be adjusted with `--exclude`. Files ending in the backup suffix (`.orig` by default)
   are always ignored. repren does **not** read `.gitignore`: any other paths you want to
-  skip — `node_modules/`, `build/`, `dist/`, vendored code — must be named explicitly with
+  skip (`node_modules/`, `build/`, `dist/`, vendored code) must be named explicitly with
   `--exclude`, and richer scoping is done with `--include`/`--exclude` (preview with
   `--dry-run`).
 
diff --git a/repren/claude_skill.py b/repren/agent_skill.py
similarity index 97%
rename from repren/claude_skill.py
rename to repren/agent_skill.py
index b8be376..d794c52 100644
--- a/repren/claude_skill.py
+++ b/repren/agent_skill.py
@@ -7,7 +7,7 @@
 
 repren is a general-purpose utility with no per-project configuration, so it is a
 dual-scope skill: it can be installed into a single project or globally for the user.
-Scope is resolved `git config`-style — implicit when unambiguous, a hard error when not
+Scope is resolved `git config`-style: implicit when unambiguous, a hard error when not
 (see `resolve_install_target`).
 
 The skill invokes repren through ``uvx repren@latest``. repren has zero runtime
@@ -255,9 +255,9 @@ def main() -> None:
     """Command-line interface for skill installation.
 
     Can be run directly for testing:
-        python -m repren.claude_skill --project
-        python -m repren.claude_skill --global
-        python -m repren.claude_skill --project --dir /path/to/repo
+        python -m repren.agent_skill --project
+        python -m repren.agent_skill --global
+        python -m repren.agent_skill --project --dir /path/to/repo
     """
     import argparse
 
diff --git a/repren/repren.py b/repren/repren.py
index 34e67f1..06ad4da 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -9,7 +9,7 @@
 **zero runtime dependencies**. Essentially, it is a general-purpose, brute-force text
 file refactoring tool.
 
-**Using a coding agent?** This is the whole setup — tell Claude Code, Codex, Gemini, or
+**Using a coding agent?** This is the whole setup. Tell Claude Code, Codex, Gemini, or
 any agent:
 
 > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
@@ -19,7 +19,7 @@
 renames. (See [Agent Use](#agent-use).)
 
 **Zero dependencies, by design.** Given the rise of supply-chain attacks on package
-ecosystems, it’s worth noting that repren has **zero runtime dependencies** — installing
+ecosystems, it’s worth noting that repren has **zero runtime dependencies**. Installing
 it (or running `uvx repren@latest`) pulls in nothing but repren itself and the Python
 standard library. There is no transitive dependency tree to audit or to be compromised,
 so it is simpler and safer to adopt than most tools. It’s also a single file you can read
@@ -150,9 +150,10 @@
 - **Atomic file operations** means edits are written to a temp file and atomically
   renamed into place, so an interruption never leaves a truncated or half-written file.
   repren and `sd` do this for content edits; `rnr` only renames (and `rename()` is itself
-  atomic). For the classics it *varies*: GNU `sed -i` and `gawk -i inplace` use
-  temp+rename, but `perl -i` is only atomic on Perl ≥ 5.28, and a plain `cmd > file`
-  redirect is never atomic. `fastmod`, `ast-grep`, and `comby` overwrite files in place.
+  atomic). For the classics it *varies*: GNU `sed -i` and `gawk -i inplace` write to a
+  temp file and rename, but `perl -i` is only atomic on Perl ≥ 5.28, and a plain
+  `cmd > file` redirect is never atomic. `fastmod`, `ast-grep`, and `comby` overwrite
+  files in place.
 - **Agent skill support** means the project ships an official coding-agent integration
   (a skill or MCP server) so an agent can discover and drive it. repren installs a skill
   via `repren --install-skill`; `ast-grep` ships an official agent skill and MCP server.
@@ -203,8 +204,8 @@
 script somewhere convenient and make it executable.
 
 **A note on freshness and safety.** These examples use `@latest` for simplicity. Because
-repren has **zero runtime dependencies**, the only code fetched and run is repren itself —
-there is no transitive dependency tree to audit or be compromised — so `@latest` carries
+repren has **zero runtime dependencies**, the only code fetched and run is repren itself.
+There is no transitive dependency tree to audit or be compromised, so `@latest` carries
 far less supply-chain risk here than for a typical package. If you want an extra safety
 margin, you can opt into uv’s release “cool-off” (which excludes very recent uploads), or
 pin an exact version:
@@ -220,7 +221,7 @@
 ## Agent Use
 
 **The one thing to know:** point your agent at repren’s self-documenting help and let it
-install itself —
+install itself.
 
 > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
@@ -249,18 +250,18 @@
 Installing the skill writes one `SKILL.md` to **both** discovery locations, so every
 agent finds it:
 
-- `.agents/skills/repren/` — the portable, cross-agent location (Codex, Gemini, pi, …)
-- `.claude/skills/repren/` — the Claude Code mirror
+- `.agents/skills/repren/`: the portable, cross-agent location (Codex, Gemini, pi, …)
+- `.claude/skills/repren/`: the Claude Code mirror
 
 repren is a general-purpose utility with no per-project config, so the skill invokes it
-through the zero-install runner `uvx repren@latest` — there’s no need to add repren as a
+through the zero-install runner `uvx repren@latest`. There’s no need to add repren as a
 project dependency. Because repren has **zero runtime dependencies**, the only code a
 runner ever fetches and runs is repren itself; for an extra safety margin you can opt into
 uv’s release cool-off (`UV_EXCLUDE_NEWER`, see [Installation](#installation)) in your
 environment, which applies to the skill’s invocations too.
 
-**Scope is resolved like `git config`** — implicit when unambiguous, a clear error when
-not — so a stray `--install-skill` never silently rewrites your global agent surfaces:
+**Scope is resolved like `git config`:** implicit when unambiguous, a clear error when
+not, so a stray `--install-skill` never silently rewrites your global agent surfaces:
 
 - Inside a git repo, `--project` is implied (so `uvx repren --install-skill` just works).
 - In an ambiguous spot (your home directory, or outside any repo) repren refuses and
@@ -456,7 +457,7 @@
 - By default, recursive searching omits paths starting with “.” (including `.git/`). This
   may be adjusted with `--exclude`. Files ending in the backup suffix (`.orig` by default)
   are always ignored. repren does **not** read `.gitignore`: any other paths you want to
-  skip — `node_modules/`, `build/`, `dist/`, vendored code — must be named explicitly with
+  skip (`node_modules/`, `build/`, `dist/`, vendored code) must be named explicitly with
   `--exclude`, and richer scoping is done with `--include`/`--exclude` (preview with
   `--dry-run`).
 
@@ -561,7 +562,7 @@ def _get_version() -> str:
 # Prominent callout shown in `--help` so agents and humans immediately discover that
 # repren can install itself as an agent skill. Keep this short and actionable (§6.5).
 SKILL_HINT: str = """\
-IMPORTANT — Use repren as an agent skill (Claude Code, Codex, Gemini, and others):
+IMPORTANT: Use repren as an agent skill (Claude Code, Codex, Gemini, and others):
   Install into your project:  repren --install-skill            (run inside the repo)
   Install for all projects:   repren --install-skill --global
   Not installed? Use uvx:     uvx repren@latest --install-skill  (add --project or --global)
@@ -1429,7 +1430,7 @@ def error(self, message: str) -> NoReturn:
     parser.add_argument(
         "--install-skill",
         help="install repren agent skill (.agents/ and .claude/ skill dirs); see --project/--global",
-        dest="install_claude_skill",
+        dest="install_skill",
         action="store_true",
     )
     parser.add_argument(
@@ -1494,13 +1495,13 @@ def error(self, message: str) -> NoReturn:
         or options.skill_dir is not None
         or options.skill_no_repo_check
     )
-    if skill_scope_requested and not options.install_claude_skill:
+    if skill_scope_requested and not options.install_skill:
         parser.error("--project/--global/--dir/--no-repo-check require --install-skill")
 
     # Handle skill installation (early exit)
-    if options.install_claude_skill:
+    if options.install_skill:
         try:
-            from .claude_skill import SkillScopeError, install_skill
+            from .agent_skill import SkillScopeError, install_skill
         except ImportError:
             # Fallback if running as standalone script
             print(
@@ -1534,7 +1535,7 @@ def error(self, message: str) -> NoReturn:
     # Handle skill instructions output (early exit)
     if options.skill_instructions:
         try:
-            from .claude_skill import get_skill_content
+            from .agent_skill import get_skill_content
 
             print(get_skill_content())
             print(f"\n{_format_hint(color=sys.stdout.isatty())}\n")
diff --git a/repren/skills/SKILL.md b/repren/skills/SKILL.md
index ccbf280..cd11118 100644
--- a/repren/skills/SKILL.md
+++ b/repren/skills/SKILL.md
@@ -7,7 +7,7 @@ allowed-tools: Bash(repren:*), Bash(uvx repren@latest:*), Read, Write
 
 > **Invocation:** The examples below call `repren` directly, which assumes it is on your
 > `PATH` (e.g. installed via `uv tool install repren`). If `repren` is not installed,
-> replace `repren` with the zero-install runner `uvx repren@latest` in every command — it
+> replace `repren` with the zero-install runner `uvx repren@latest` in every command. It
 > needs no prior install. repren has zero runtime dependencies, so the only code fetched
 > and run is repren itself.
 >
@@ -19,16 +19,17 @@ file/directory renaming, and case-preserving transformations.
 ## Prefer Repren for Bulk Renames
 
 For any rename or find-and-replace that spans **more than a file or two**, reach for
-repren first — don’t hand-edit file by file or script a `sed`/`perl`/`awk` loop. A single
-repren command does what those approaches do awkwardly or not at all, and does it safely:
+repren first rather than hand-editing file by file or scripting a `sed`/`perl`/`awk` loop.
+A single repren command does what those approaches do awkwardly or not at all, and does it
+safely:
 
-- **Combined content + filename changes in one pass.** With `--full`, repren rewrites
+- **Combined content and filename changes in one pass.** With `--full`, repren rewrites
   file *contents* and renames the matching *files and directories* together, creating
-  parent directories as needed — so renaming a module and every reference to it is one
+  parent directories as needed, so renaming a module and every reference to it is one
   command, not two error-prone steps.
 - **Simultaneous multi-pattern replacement, including swaps.** Apply many patterns at
   once from a patterns file, and even circular renames (`foo`→`bar` and `bar`→`foo`) in a
-  single pass — impossible with naive sequential replaces, which clobber each other.
+  single pass, which is impossible with naive sequential replaces that clobber each other.
 - **Case-variant awareness.** `--preserve-case` rewrites every case form of an identifier
   consistently (`my_var`/`myVar`/`MyVar`/`MY_VAR`), which a plain string replace misses.
 - **Safe by default: dry-run, backups, and undo.** Preview every change with
@@ -184,8 +185,8 @@ repren --patterns=patterns.txt --exclude='tests|node_modules|__pycache__' --full
 
 **Note on `.gitignore`:** repren does *not* read `.gitignore`. By default it skips only
 dotfiles and dot-directories (anything starting with `.`, including `.git/`), so VCS
-internals are left alone. Anything else you want skipped — `node_modules/`, `build/`,
-`dist/`, `target/`, vendored code — must be named explicitly via `--exclude` (or scoped
+internals are left alone. Anything else you want skipped (`node_modules/`, `build/`,
+`dist/`, `target/`, vendored code) must be named explicitly via `--exclude` (or scoped
 in with `--include`). Always confirm scope with `--dry-run` before a real run.
 
 ### Word Boundaries
diff --git a/tests/pytests.py b/tests/pytests.py
index 4dee18d..571c4bc 100644
--- a/tests/pytests.py
+++ b/tests/pytests.py
@@ -499,7 +499,7 @@ class TestClaudeSkillContent:
 
     def test_get_skill_content_returns_markdown(self):
         """get_skill_content should return valid markdown content."""
-        from repren.claude_skill import get_skill_content
+        from repren.agent_skill import get_skill_content
 
         content = get_skill_content()
 
@@ -511,7 +511,7 @@ def test_get_skill_content_returns_markdown(self):
 
     def test_skill_content_has_required_sections(self):
         """Skill content should have essential sections for Claude."""
-        from repren.claude_skill import get_skill_content
+        from repren.agent_skill import get_skill_content
 
         content = get_skill_content()
 
@@ -522,7 +522,7 @@ def test_skill_content_has_required_sections(self):
 
     def test_skill_content_uses_latest_runner(self):
         """Skill uses the @latest zero-install runner; protection comes from uv cool-off."""
-        from repren.claude_skill import get_skill_content
+        from repren.agent_skill import get_skill_content
 
         content = get_skill_content()
 
@@ -536,7 +536,7 @@ class TestClaudeSkillScopeResolution:
     """Tests for the git-config-style install scope resolution."""
 
     def test_explicit_global(self):
-        from repren.claude_skill import resolve_install_target
+        from repren.agent_skill import resolve_install_target
 
         home = Path("/home/someone")
         target = resolve_install_target(global_install=True, home=home, cwd=Path("/tmp/x"))
@@ -546,7 +546,7 @@ def test_explicit_global(self):
         assert target.root == home.resolve()
 
     def test_explicit_project_with_dir(self):
-        from repren.claude_skill import resolve_install_target
+        from repren.agent_skill import resolve_install_target
 
         target = resolve_install_target(dir="/tmp/repo", home=Path("/home/someone"))
         assert target.mode == "project"
@@ -554,7 +554,7 @@ def test_explicit_project_with_dir(self):
 
     def test_implicit_project_inside_repo(self, tmp_path):
         """Inside a git repo, scope is implicitly project."""
-        from repren.claude_skill import resolve_install_target
+        from repren.agent_skill import resolve_install_target
 
         (tmp_path / ".git").mkdir()
         target = resolve_install_target(cwd=tmp_path, home=Path("/home/someone"))
@@ -563,7 +563,7 @@ def test_implicit_project_inside_repo(self, tmp_path):
 
     def test_implicit_project_uses_repo_root_from_subdir(self, tmp_path):
         """Run from a nested dir, project install still lands at the repo root, not cwd."""
-        from repren.claude_skill import resolve_install_target
+        from repren.agent_skill import resolve_install_target
 
         (tmp_path / ".git").mkdir()
         subdir = tmp_path / "src" / "deep"
@@ -576,13 +576,13 @@ def test_implicit_project_uses_repo_root_from_subdir(self, tmp_path):
             assert target.root == tmp_path.resolve()
 
     def test_ambiguous_outside_repo_errors(self, tmp_path):
-        from repren.claude_skill import SkillScopeError, resolve_install_target
+        from repren.agent_skill import SkillScopeError, resolve_install_target
 
         with pytest.raises(SkillScopeError, match="not inside a git repository"):
             resolve_install_target(cwd=tmp_path, home=Path("/home/someone"))
 
     def test_project_no_repo_check_allows_non_repo(self, tmp_path):
-        from repren.claude_skill import resolve_install_target
+        from repren.agent_skill import resolve_install_target
 
         target = resolve_install_target(
             project=True, no_repo_check=True, cwd=tmp_path, home=Path("/home/someone")
@@ -591,25 +591,25 @@ def test_project_no_repo_check_allows_non_repo(self, tmp_path):
         assert target.root == tmp_path.resolve()
 
     def test_home_is_refused_in_project_mode(self, tmp_path):
-        from repren.claude_skill import SkillScopeError, resolve_install_target
+        from repren.agent_skill import SkillScopeError, resolve_install_target
 
         with pytest.raises(SkillScopeError, match="home directory"):
             resolve_install_target(dir=str(tmp_path), home=tmp_path)
 
     def test_cwd_home_is_ambiguous(self, tmp_path):
-        from repren.claude_skill import SkillScopeError, resolve_install_target
+        from repren.agent_skill import SkillScopeError, resolve_install_target
 
         with pytest.raises(SkillScopeError, match="ambiguous"):
             resolve_install_target(cwd=tmp_path, home=tmp_path)
 
     def test_project_and_global_mutually_exclusive(self):
-        from repren.claude_skill import SkillScopeError, resolve_install_target
+        from repren.agent_skill import SkillScopeError, resolve_install_target
 
         with pytest.raises(SkillScopeError, match="mutually exclusive"):
             resolve_install_target(project=True, global_install=True)
 
     def test_global_and_dir_mutually_exclusive(self):
-        from repren.claude_skill import SkillScopeError, resolve_install_target
+        from repren.agent_skill import SkillScopeError, resolve_install_target
 
         with pytest.raises(SkillScopeError, match="mutually exclusive"):
             resolve_install_target(global_install=True, dir="/tmp/x")
@@ -620,7 +620,7 @@ class TestClaudeSkillInstallation:
 
     def test_install_skill_global_creates_both_surfaces(self):
         """A global install writes both surfaces under $HOME."""
-        from repren.claude_skill import install_skill
+        from repren.agent_skill import install_skill
 
         with tempfile.TemporaryDirectory() as tmpdir:
             import os
@@ -644,7 +644,7 @@ def test_install_skill_global_creates_both_surfaces(self):
 
     def test_install_skill_project_dir_creates_both_surfaces(self):
         """A project install with --dir writes both surfaces under that root."""
-        from repren.claude_skill import install_skill
+        from repren.agent_skill import install_skill
 
         with tempfile.TemporaryDirectory() as tmpdir:
             install_skill(dir=tmpdir)
@@ -654,7 +654,7 @@ def test_install_skill_project_dir_creates_both_surfaces(self):
 
     def test_install_skill_content_matches_package(self):
         """Installed skill content should match package content."""
-        from repren.claude_skill import get_skill_content, install_skill
+        from repren.agent_skill import get_skill_content, install_skill
 
         with tempfile.TemporaryDirectory() as tmpdir:
             install_skill(dir=tmpdir)
diff --git a/tests/tryscript/help-errors.tryscript.md b/tests/tryscript/help-errors.tryscript.md
index d0edfd9..9c247f5 100644
--- a/tests/tryscript/help-errors.tryscript.md
+++ b/tests/tryscript/help-errors.tryscript.md
@@ -81,7 +81,7 @@ description: The preferred tool for large-scale or multi-file renames and search
 
 ```console
 $ repren --help | grep -F "Use repren as an agent skill"
-IMPORTANT — Use repren as an agent skill (Claude Code, Codex, Gemini, and others):
+IMPORTANT: Use repren as an agent skill (Claude Code, Codex, Gemini, and others):
 ? 0
 ```
 

From 522cd425aed91ff6b24503c02d57ca61bf8e3213 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 08:12:23 +0000
Subject: [PATCH 13/18] fix: handle SIGPIPE so piped output (repren --skill |
 head) stays quiet

`repren --skill | head -3` made head close the pipe early; with the longer skill
description, repren was still writing and Python surfaced a BrokenPipeError traceback,
failing the H4 golden on CI. Behave like a standard Unix filter instead: reset SIGPIPE to
its default disposition (POSIX), with a BrokenPipeError fallback for platforms without
SIGPIPE. This also covers `repren --docs | head`, `repren --help | head`, etc.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 repren/repren.py | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/repren/repren.py b/repren/repren.py
index 06ad4da..db660f8 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -513,6 +513,7 @@ def override(method: _F, /) -> _F:
 EXIT_ERROR = 1
 EXIT_USAGE = 2
 EXIT_INTERRUPTED = 130  # 128 + SIGINT(2)
+EXIT_BROKEN_PIPE = 141  # 128 + SIGPIPE(13)
 
 
 # --- Custom exceptions ---
@@ -1758,6 +1759,16 @@ def format_flags(flags: int) -> str:
 
 def main() -> None:
     """CLI entrypoint with centralized error handling."""
+    # Behave like a standard Unix filter: if a downstream reader closes the pipe early
+    # (e.g. `repren --skill | head`), die quietly on SIGPIPE instead of printing a
+    # BrokenPipeError traceback. SIGPIPE is POSIX-only, so guard for Windows.
+    try:
+        import signal
+
+        signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+    except (AttributeError, ValueError):
+        pass
+
     try:
         _run_cli()
     except CLIError as e:
@@ -1766,6 +1777,15 @@ def main() -> None:
     except KeyboardInterrupt:
         print("\nInterrupted", file=sys.stderr)
         sys.exit(EXIT_INTERRUPTED)
+    except BrokenPipeError:
+        # Fallback for platforms without SIGPIPE (e.g. Windows): suppress the second
+        # BrokenPipeError raised when Python flushes stdout at shutdown.
+        try:
+            devnull = os.open(os.devnull, os.O_WRONLY)
+            os.dup2(devnull, sys.stdout.fileno())
+        except OSError:
+            pass
+        sys.exit(EXIT_BROKEN_PIPE)
 
 
 if __name__ == "__main__":

From f8426100b761d43d1aa3e0d2ba3d1866bc6bf775 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 08:25:47 +0000
Subject: [PATCH 14/18] refactor: hoist stdlib imports (signal, argparse) to
 module top

Per the project Python rules, standard-library imports belong at module top, not
inlined inside functions. Move `import signal` (repren.py) and `import argparse`
(agent_skill.py) to the top-level import blocks.

Also harden the SIGPIPE setup: guard `signal.signal()` with both `hasattr(signal,
"SIGPIPE")` (Windows has no SIGPIPE) and a `ValueError` catch (signal.signal only works
on the main thread, so embedding/off-thread callers degrade gracefully).

The remaining inline imports are intentional and stay: the `override` backport behind a
sys.version_info guard, the importlib.resources/pkg_resources version fallback, and the
markdown_renderer/agent_skill imports wrapped in try/except ImportError so repren still
runs when copied as a standalone single-file script.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 repren/agent_skill.py |  3 +--
 repren/repren.py      | 15 ++++++++-------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/repren/agent_skill.py b/repren/agent_skill.py
index d794c52..4f73ded 100644
--- a/repren/agent_skill.py
+++ b/repren/agent_skill.py
@@ -15,6 +15,7 @@
 safety margin, opt into uv's release cool-off (``UV_EXCLUDE_NEWER``) in your environment.
 """
 
+import argparse
 import sys
 from dataclasses import dataclass
 from pathlib import Path
@@ -259,8 +260,6 @@ def main() -> None:
         python -m repren.agent_skill --global
         python -m repren.agent_skill --project --dir /path/to/repo
     """
-    import argparse
-
     parser = argparse.ArgumentParser(
         description="Install repren agent skill",
         formatter_class=argparse.RawDescriptionHelpFormatter,
diff --git a/repren/repren.py b/repren/repren.py
index db660f8..7fee14a 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -476,6 +476,7 @@
 import os
 import re
 import shutil
+import signal
 import sys
 from collections.abc import Callable
 from dataclasses import dataclass
@@ -1761,13 +1762,13 @@ def main() -> None:
     """CLI entrypoint with centralized error handling."""
     # Behave like a standard Unix filter: if a downstream reader closes the pipe early
     # (e.g. `repren --skill | head`), die quietly on SIGPIPE instead of printing a
-    # BrokenPipeError traceback. SIGPIPE is POSIX-only, so guard for Windows.
-    try:
-        import signal
-
-        signal.signal(signal.SIGPIPE, signal.SIG_DFL)
-    except (AttributeError, ValueError):
-        pass
+    # BrokenPipeError traceback. SIGPIPE only exists on POSIX (guard for Windows), and
+    # signal.signal() only works on the main thread (guard for embedded/off-thread use).
+    if hasattr(signal, "SIGPIPE"):
+        try:
+            signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+        except ValueError:
+            pass
 
     try:
         _run_cli()

From f8092ae7151ef8778359923e5aa169a972a75ede Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 08:27:38 +0000
Subject: [PATCH 15/18] docs: use the upcoming 3.1.0 in the exact-pin example

Tags are unprefixed (2.0.0, 1.0.2, ...), so this release ships as 3.1.0. Point the
"pin an exact version" example at it instead of the stale 2.0.0. Regenerated README and
the docstring from the manual.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 README.md           | 2 +-
 docs/repren-docs.md | 2 +-
 repren/repren.py    | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 6ef224e..668453f 100644
--- a/README.md
+++ b/README.md
@@ -237,7 +237,7 @@ pin an exact version:
 UV_EXCLUDE_NEWER="14 days" uvx repren@latest --help
 
 # Or pin an exact version:
-uvx repren@2.0.0 --help
+uvx repren@3.1.0 --help
 ```
 
 ## Agent Use
diff --git a/docs/repren-docs.md b/docs/repren-docs.md
index 0d599d6..fdefb9f 100644
--- a/docs/repren-docs.md
+++ b/docs/repren-docs.md
@@ -213,7 +213,7 @@ pin an exact version:
 UV_EXCLUDE_NEWER="14 days" uvx repren@latest --help
 
 # Or pin an exact version:
-uvx repren@2.0.0 --help
+uvx repren@3.1.0 --help
 ```
 
 ## Agent Use
diff --git a/repren/repren.py b/repren/repren.py
index 7fee14a..8af8ff4 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -215,7 +215,7 @@
 UV_EXCLUDE_NEWER="14 days" uvx repren@latest --help
 
 # Or pin an exact version:
-uvx repren@2.0.0 --help
+uvx repren@3.1.0 --help
 ```
 
 ## Agent Use

From 86ccc7dc4452cf9894dbcad92b7015a477c6b395 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 15:54:26 +0000
Subject: [PATCH 16/18] docs(skill): trim SKILL.md to a routing layer, not a
 copy of --docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per cli-agent-skill-patterns §6.4 ("route, don't restate") and §3.1 (progressive
disclosure), the skill body should name each use case and the one command that reaches
it, then point at the tool's own docs for the mechanics. The body had grown into a
near-copy of `repren --docs`: flag tables, pattern-file format, per-feature recipes, a
Notes section.

Cut it from ~260 to ~45 lines: keep the frontmatter description (the discovery/"when"
layer, unchanged), a tight when-to-use list with one command per intent, when-not-to-use,
and two safety/scoping reminders. Everything else routes to `repren --docs`, which the
agent reads when it actually uses the tool. This saves context on every activation and
removes drift between the skill and the CLI's own help.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 repren/skills/SKILL.md | 276 +++++------------------------------------
 1 file changed, 32 insertions(+), 244 deletions(-)

diff --git a/repren/skills/SKILL.md b/repren/skills/SKILL.md
index cd11118..8ad9374 100644
--- a/repren/skills/SKILL.md
+++ b/repren/skills/SKILL.md
@@ -3,257 +3,45 @@ name: repren
 description: The preferred tool for large-scale or multi-file renames and search-and-replace. Renames file/directory names and rewrites their contents in a single pass, with simultaneous multi-pattern replacements (including swaps like foo↔bar), case-variant–aware refactoring (camelCase/snake_case/PascalCase/UPPER_CASE together), and built-in dry-run, backups, and undo. Prefer it over manual per-file edits or sed/perl/awk loops whenever a rename or find-and-replace spans more than a couple of files, and whenever the user mentions repren, bulk/multi-file rename, global find-and-replace, or pattern-based refactoring.
 allowed-tools: Bash(repren:*), Bash(uvx repren@latest:*), Read, Write
 ---
-# Repren - Multi-Pattern Search and Replace
+# repren: multi-pattern rename and search-and-replace
 
-> **Invocation:** The examples below call `repren` directly, which assumes it is on your
-> `PATH` (e.g. installed via `uv tool install repren`). If `repren` is not installed,
-> replace `repren` with the zero-install runner `uvx repren@latest` in every command. It
-> needs no prior install. repren has zero runtime dependencies, so the only code fetched
-> and run is repren itself.
->
-> **Full documentation:** Run `repren --docs` for all options, flags, and advanced usage.
-
-Multi-pattern search/replace tool for bulk refactoring with simultaneous replacements,
-file/directory renaming, and case-preserving transformations.
-
-## Prefer Repren for Bulk Renames
-
-For any rename or find-and-replace that spans **more than a file or two**, reach for
-repren first rather than hand-editing file by file or scripting a `sed`/`perl`/`awk` loop.
-A single repren command does what those approaches do awkwardly or not at all, and does it
-safely:
-
-- **Combined content and filename changes in one pass.** With `--full`, repren rewrites
-  file *contents* and renames the matching *files and directories* together, creating
-  parent directories as needed, so renaming a module and every reference to it is one
-  command, not two error-prone steps.
-- **Simultaneous multi-pattern replacement, including swaps.** Apply many patterns at
-  once from a patterns file, and even circular renames (`foo`→`bar` and `bar`→`foo`) in a
-  single pass, which is impossible with naive sequential replaces that clobber each other.
-- **Case-variant awareness.** `--preserve-case` rewrites every case form of an identifier
-  consistently (`my_var`/`myVar`/`MyVar`/`MY_VAR`), which a plain string replace misses.
-- **Safe by default: dry-run, backups, and undo.** Preview every change with
-  `--dry-run`, fall back to automatic `.orig` backups, and reverse a run with `--undo`.
-  Edits are atomic, so an interrupted run never leaves a half-written file.
-- **Precise scoping.** `--word-breaks`, `--literal`, `--include`/`--exclude`, and
-  `--at-once` (multi-line) keep matches exactly where you intend.
-
-When a task is “rename X to Y across the codebase” or “replace these N patterns
-everywhere,” repren is almost always the right tool. Reserve hand edits for one-off
-single-file changes and AST tools for language-aware semantic refactors (see below).
-
-## Quick Start
-
-**Always start with dry-run** to preview changes:
-```bash
-repren --from='old_name' --to='new_name' --full --dry-run src/
-```
-
-Then execute if output looks correct:
-```bash
-repren --from='old_name' --to='new_name' --full src/
-```
-
-## When to Use Repren
-
-**Use repren (the default choice) for:**
-- Large-scale code refactoring (renaming across many files)
-- Renaming a symbol *and* the files/directories named after it, in one pass (`--full`)
-- Simultaneous multi-pattern replacements, including swaps or circular renames (foo↔bar)
-- Case-preserving identifier transformations (camelCase/snake_case/PascalCase/UPPER_CASE)
-- Any change you want to preview (`--dry-run`), back up, and be able to `--undo`
-
-**Don’t use repren for:**
-- Single-file small edits or one-off replacements (use the Edit tool instead)
-- Language-aware semantic refactoring (use AST tools like ast-grep, ts-morph)
-- Operations requiring precise line-by-line control (use the Edit tool)
-
-## Core Features
-
-### Simultaneous Multi-Pattern Replacement
-
-Create a patterns file with tab-separated pairs:
-```
-old_function	new_function
-OldClass	NewClass
-CONSTANT_OLD	CONSTANT_NEW
-```
-
-Apply all patterns at once:
-```bash
-repren --patterns=patterns.txt --full src/
-```
-
-Repren handles overlapping patterns intelligently: you can swap names (foo↔bar) in a
-single pass.
-
-### Case-Preserving Transformations
-
-Handle all case variants automatically:
-```bash
-repren --from='my_var' --to='my_function' --preserve-case --full src/
-```
-
-Transforms: `my_var`→`my_function`, `myVar`→`myFunction`, `MyVar`→`MyFunction`,
-`MY_VAR`→`MY_FUNCTION`.
-
-### File and Directory Renaming
-
-With `--full`, in addition to searching and replacing content, repren will rename files
-and directories matching the patterns.
-
-```bash
-repren --from='old_module' --to='new_module' --full src/
-```
-
-Renames files and directories, creating parent directories as needed. Files never
-clobber: numeric suffixes are added if conflicts arise.
-
-### Regex Patterns with Capture Groups
-
-Use full Python regex syntax with backreferences:
-```bash
-repren --from='figure ([0-9]+)' --to='Figure \1' --full docs/
-```
-
-Pattern file example:
-```
-def (\w+)\(self\)	def \1(self, context)
-class Old(\w+)	class New\1
-```
-
-## Safety and Backup Management
+repren does in one safe, previewable pass what hand edits and `sed`/`perl`/`awk` loops do
+awkwardly: combined content and file/directory renames, simultaneous multi-pattern
+replacement (including swaps), case-variant-aware refactoring, and atomic writes with
+backups and undo.
 
-### Atomic Operations with Backups
-
-All modifications create `.orig` backup files automatically. Original files never
-truncated on errors.
-
-### Dry Run
-
-**Always preview changes first:**
-```bash
-repren --dry-run --patterns=patterns.txt --full mydir/
-```
-
-Shows exactly what would change without modifying files.
-
-### Undo Changes
-
-Restore from backups if needed:
-```bash
-repren --undo --from='old' --to='new' --full src/
-```
-
-### Clean Backups
-
-Remove backups when satisfied:
-```bash
-repren --clean-backups src/
-```
-
-## Common Workflows
-
-### Large Codebase Refactoring
-
-1. Preview changes:
-```bash
-repren --from='OldName' --to='NewName' --preserve-case --word-breaks --full --dry-run src/
-```
-
-2. Execute if output looks correct:
-```bash
-repren --from='OldName' --to='NewName' --preserve-case --word-breaks --full src/
-```
-
-3. Review changes, test, then clean backups:
-```bash
-repren --clean-backups src/
-```
-
-### Filtering Files
-
-Include only specific file types:
-```bash
-repren --patterns=patterns.txt --include='.*\.(py|pyi)$' --full src/
-```
-
-Exclude directories:
-```bash
-repren --patterns=patterns.txt --exclude='tests|node_modules|__pycache__' --full src/
-```
-
-**Note on `.gitignore`:** repren does *not* read `.gitignore`. By default it skips only
-dotfiles and dot-directories (anything starting with `.`, including `.git/`), so VCS
-internals are left alone. Anything else you want skipped (`node_modules/`, `build/`,
-`dist/`, `target/`, vendored code) must be named explicitly via `--exclude` (or scoped
-in with `--include`). Always confirm scope with `--dry-run` before a real run.
-
-### Word Boundaries
-
-Match only at word boundaries (safer for variable names):
-```bash
-repren --from='var' --to='variable' --word-breaks --full src/
-```
-
-### Literal Patterns
-
-Treat patterns as literal strings (not regex):
-```bash
-repren --from='file.txt' --to='data.txt' --literal --full docs/
-```
-
-### Multi-Line Patterns
-
-Process entire files at once for patterns spanning lines:
-```bash
-repren --patterns=patterns.txt --at-once --full src/
-```
-
-## Machine-Readable Output
-
-Use JSON format for programmatic processing:
-```bash
-repren --format=json --from='old' --to='new' --full src/
-```
-
-Returns structured data about all changes made.
+> **If you are going to use repren, read its docs first:** run `repren --docs` for the
+> full flags, pattern-file format, examples, and edge cases. This skill only tells you
+> *when* to reach for repren and *which* command; `repren --docs` and `repren --help`
+> carry the *how*.
+>
+> **Invocation:** use `repren` if it is on `PATH`, otherwise `uvx repren@latest` (no
+> install needed, zero runtime dependencies). Always preview with `--dry-run` first.
 
-## Key Flags
+## When to use repren
 
-Most important flags (run `repren --docs` for complete list):
+Prefer repren over the Edit tool or shell loops whenever a rename or replacement spans
+more than a file or two. Reach for it when the task is to:
 
-| Flag | Purpose |
-| --- | --- |
-| `--full` | Apply to files AND rename them (not just stdin/stdout) |
-| `--dry-run`, `-n` | Preview without modifying |
-| `--patterns=FILE` | Use multi-pattern file instead of single --from/--to |
-| `--preserve-case` | Handle camelCase, snake_case, PascalCase, UPPER_CASE variants |
-| `--word-breaks` | Match only at word boundaries (safer for identifiers) |
-| `--at-once` | Process entire file (needed for multi-line patterns) |
-| `--format=json` | Machine-parseable output for scripts |
-| `--undo` | Restore from .orig backups |
-| `--clean-backups` | Remove backup files |
+- **Rename a symbol across many files** — `repren --from=Old --to=New --word-breaks --full DIR`
+- **Rename a symbol and the files/directories named after it, together** — `--full` rewrites contents and renames paths in one pass
+- **Apply many replacements at once, or swap names (`foo`↔`bar`)** — `repren --patterns=FILE --full DIR`
+- **Refactor an identifier across all case variants** (camelCase/snake_case/PascalCase/UPPER_CASE) — add `--preserve-case`
+- **Replace with a regex and capture groups across files** — `repren --from='figure ([0-9]+)' --to='Figure \1' DIR`
+- **Make a bulk change you must preview, back up, and be able to reverse** — `--dry-run`, then run, then `--undo` or `--clean-backups`
 
-## Pattern File Format
+For the exact flags, pattern-file syntax, scoping (`--include`/`--exclude`, `--literal`,
+`--at-once`), and JSON output, read `repren --docs`.
 
-Tab-separated pattern/replacement pairs:
-```
-pattern<TAB>replacement
-another<TAB>replacement
-# Comments start with #
-```
+## When not to use repren
 
-Supports regex with capture groups `(\w+)` and backreferences `\1`, `\2`. First match
-wins for overlaps.
+- A single-file or one-off edit — use the Edit tool.
+- Language-aware or semantic refactors — use an AST tool such as ast-grep.
+- Anything needing precise line-by-line control — use the Edit tool.
 
-## Notes
+## Good to know
 
-- All pattern matching uses Python regex syntax
-- Replacements are line-by-line by default, use `--at-once` for full-file
-- Multiple patterns matched first, then all replaced (enables swaps)
-- Binary files supported (patterns specified as strings, data handled as bytes)
-- File permissions preserved
-- Operations are atomic - temp files used, then renamed
-- Default excludes hidden files (starting with `.`), customizable with `--exclude`
-- Backup files (`.orig` by default) always ignored in recursive operations
+- Always `--dry-run` first. repren writes atomically and leaves `.orig` backups; `--undo`
+  restores them, `--clean-backups` removes them.
+- repren does **not** read `.gitignore`. It skips dotfiles (including `.git/`) by default;
+  scope everything else explicitly with `--include`/`--exclude`. See `repren --docs`.

From ec0bda7c6fa14a04ce54f1effca9982907116f98 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 16:00:00 +0000
Subject: [PATCH 17/18] docs: cut rhetorical hooks and over-explanation; keep
 it factual

Apply common-doc-guidelines (cut pompousness and meta-commentary; eliminate words that
add no information):

- Replace the "Using a coding agent?" / "The one thing to know" hooks with plain
  factual leads ("Coding agents:", and a direct sentence in Agent Use).
- Tighten the intro zero-deps paragraph; drop "by design" and the "Amid the rise of
  supply-chain attacks" framing.
- Condense the comparison-table footnote to a single line and drop the redundant
  agent-skill gloss (the table and Agent Use section already make it clear).
- README header: drop the decorative emojis and marketing phrasing; state the two
  callouts factually.

Regenerated README and the docstring from the manual.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 README.md           | 65 +++++++++++++++------------------------------
 docs/repren-docs.md | 45 +++++++++++--------------------
 repren/repren.py    | 45 +++++++++++--------------------
 3 files changed, 52 insertions(+), 103 deletions(-)

diff --git a/README.md b/README.md
index 668453f..6c81cf9 100644
--- a/README.md
+++ b/README.md
@@ -5,20 +5,14 @@
 * * *
 
 > [!TIP]
-> ✨✨ **Using a coding agent?** Just tell Claude Code, Codex, Gemini, or any agent:
->
-> > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
->
-> That’s the whole setup. The agent reads repren’s self-documenting `--help`, installs
-> the skill, and from then on reaches for repren automatically on bulk refactors and
-> renames. See [Agent Use](#agent-use) for details.
+> **Coding agents:** tell your agent to run `uvx repren@latest --help` and follow the
+> instructions to install repren as a skill. Once installed, it uses repren automatically
+> for bulk refactors and renames. See [Agent Use](#agent-use).
 
-> [!TIP]
-> 🔒 **Zero dependencies.** repren has **zero runtime dependencies**: just Python and a
-> single file. Amid the rise of supply-chain attacks on package ecosystems, that means
-> there’s no transitive dependency tree to audit or be compromised: the only code `uvx
-> repren@latest` ever fetches and runs is repren itself, and you (or your agent) can review
-> its security before trusting it.
+> [!NOTE]
+> **Zero runtime dependencies.** repren is a single file that imports only the Python
+> standard library, so there is no transitive dependency tree to audit or be compromised:
+> the only code `uvx repren@latest` runs is repren itself.
 
 * * *
 
@@ -31,22 +25,18 @@ It is small, self-contained, self-documenting, and works on Python 3.10-3.14 wit
 **zero runtime dependencies**. Essentially, it is a general-purpose, brute-force text
 file refactoring tool.
 
-**Using a coding agent?** This is the whole setup. Tell Claude Code, Codex, Gemini, or
-any agent:
+**Coding agents:** point your agent at repren and it installs itself as a skill:
 
 > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
-repren’s `--help` ends with the exact install commands, so the agent reads them and takes
-it from there. After that it reaches for repren automatically on bulk refactors and
-renames. (See [Agent Use](#agent-use).)
+repren’s `--help` ends with the exact install commands. Once installed, the agent uses
+repren automatically for bulk refactors and renames. (See [Agent Use](#agent-use).)
 
-**Zero dependencies, by design.** Given the rise of supply-chain attacks on package
-ecosystems, it’s worth noting that repren has **zero runtime dependencies**. Installing
-it (or running `uvx repren@latest`) pulls in nothing but repren itself and the Python
-standard library. There is no transitive dependency tree to audit or to be compromised,
-so it is simpler and safer to adopt than most tools. It’s also a single file you can read
-end to end (or have your agent review) before you trust it. The dev-only tooling used to
-build and test repren (pytest, ruff, etc.) is never installed when you use it.
+**Zero runtime dependencies.** Installing repren (or running `uvx repren@latest`) pulls in
+nothing but repren itself and the Python standard library, so there is no transitive
+dependency tree to audit or be compromised. It is a single file you can read end to end
+before trusting it. The dev-only tooling used to build and test repren (pytest, ruff, and
+so on) is never installed when you use it.
 
 For example, repren could rename occurrences of certain names in a set of source files,
 while simultaneously renaming the files and directories according to the same pattern
@@ -167,19 +157,10 @@ Here’s how repren compares:
 | Agent skill support | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
 | Dependencies | Python 3.10+ (no other deps) | Varies (OS/shell) | Binary (Rust) | Binary (Rust) | Binary (Rust) | Binary (OCaml) | Binary (Rust) |
 
-Notes on the last two rows:
-
-- **Atomic file operations** means edits are written to a temp file and atomically
-  renamed into place, so an interruption never leaves a truncated or half-written file.
-  repren and `sd` do this for content edits; `rnr` only renames (and `rename()` is itself
-  atomic). For the classics it *varies*: GNU `sed -i` and `gawk -i inplace` write to a
-  temp file and rename, but `perl -i` is only atomic on Perl ≥ 5.28, and a plain
-  `cmd > file` redirect is never atomic. `fastmod`, `ast-grep`, and `comby` overwrite
-  files in place.
-- **Agent skill support** means the project ships an official coding-agent integration
-  (a skill or MCP server) so an agent can discover and drive it. repren installs a skill
-  via `repren --install-skill`; `ast-grep` ships an official agent skill and MCP server.
-  The others have no first-party agent integration.
+“Atomic file operations” means edits are written to a temp file and renamed into place,
+so an interrupted run never leaves a half-written file. repren and `sd` do this; `rnr`
+only renames; the classic tools vary; and `fastmod`, `ast-grep`, and `comby` overwrite in
+place.
 
 **When to use each:**
 
@@ -242,14 +223,12 @@ uvx repren@3.1.0 --help
 
 ## Agent Use
 
-**The one thing to know:** point your agent at repren’s self-documenting help and let it
-install itself.
+Point your agent at repren’s self-documenting help to install the skill:
 
 > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
-repren’s `--help` ends with the exact install commands, so the agent can take it from
-there. (`uvx` runs repren with no prior install; see the note on `@latest` and safety
-under [Installation](#installation).)
+repren’s `--help` ends with the exact install commands. (`uvx` runs repren with no prior
+install; see the note on `@latest` and safety under [Installation](#installation).)
 
 **Install the skill yourself** (the same thing the agent does):
 
diff --git a/docs/repren-docs.md b/docs/repren-docs.md
index fdefb9f..b1faa93 100644
--- a/docs/repren-docs.md
+++ b/docs/repren-docs.md
@@ -7,22 +7,18 @@ It is small, self-contained, self-documenting, and works on Python 3.10-3.14 wit
 **zero runtime dependencies**. Essentially, it is a general-purpose, brute-force text
 file refactoring tool.
 
-**Using a coding agent?** This is the whole setup. Tell Claude Code, Codex, Gemini, or
-any agent:
+**Coding agents:** point your agent at repren and it installs itself as a skill:
 
 > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
-repren’s `--help` ends with the exact install commands, so the agent reads them and takes
-it from there. After that it reaches for repren automatically on bulk refactors and
-renames. (See [Agent Use](#agent-use).)
+repren’s `--help` ends with the exact install commands. Once installed, the agent uses
+repren automatically for bulk refactors and renames. (See [Agent Use](#agent-use).)
 
-**Zero dependencies, by design.** Given the rise of supply-chain attacks on package
-ecosystems, it’s worth noting that repren has **zero runtime dependencies**. Installing
-it (or running `uvx repren@latest`) pulls in nothing but repren itself and the Python
-standard library. There is no transitive dependency tree to audit or to be compromised,
-so it is simpler and safer to adopt than most tools. It’s also a single file you can read
-end to end (or have your agent review) before you trust it. The dev-only tooling used to
-build and test repren (pytest, ruff, etc.) is never installed when you use it.
+**Zero runtime dependencies.** Installing repren (or running `uvx repren@latest`) pulls in
+nothing but repren itself and the Python standard library, so there is no transitive
+dependency tree to audit or be compromised. It is a single file you can read end to end
+before trusting it. The dev-only tooling used to build and test repren (pytest, ruff, and
+so on) is never installed when you use it.
 
 For example, repren could rename occurrences of certain names in a set of source files,
 while simultaneously renaming the files and directories according to the same pattern
@@ -143,19 +139,10 @@ Here’s how repren compares:
 | Agent skill support | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
 | Dependencies | Python 3.10+ (no other deps) | Varies (OS/shell) | Binary (Rust) | Binary (Rust) | Binary (Rust) | Binary (OCaml) | Binary (Rust) |
 
-Notes on the last two rows:
-
-- **Atomic file operations** means edits are written to a temp file and atomically
-  renamed into place, so an interruption never leaves a truncated or half-written file.
-  repren and `sd` do this for content edits; `rnr` only renames (and `rename()` is itself
-  atomic). For the classics it *varies*: GNU `sed -i` and `gawk -i inplace` write to a
-  temp file and rename, but `perl -i` is only atomic on Perl ≥ 5.28, and a plain
-  `cmd > file` redirect is never atomic. `fastmod`, `ast-grep`, and `comby` overwrite
-  files in place.
-- **Agent skill support** means the project ships an official coding-agent integration
-  (a skill or MCP server) so an agent can discover and drive it. repren installs a skill
-  via `repren --install-skill`; `ast-grep` ships an official agent skill and MCP server.
-  The others have no first-party agent integration.
+“Atomic file operations” means edits are written to a temp file and renamed into place,
+so an interrupted run never leaves a half-written file. repren and `sd` do this; `rnr`
+only renames; the classic tools vary; and `fastmod`, `ast-grep`, and `comby` overwrite in
+place.
 
 **When to use each:**
 
@@ -218,14 +205,12 @@ uvx repren@3.1.0 --help
 
 ## Agent Use
 
-**The one thing to know:** point your agent at repren’s self-documenting help and let it
-install itself.
+Point your agent at repren’s self-documenting help to install the skill:
 
 > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
-repren’s `--help` ends with the exact install commands, so the agent can take it from
-there. (`uvx` runs repren with no prior install; see the note on `@latest` and safety
-under [Installation](#installation).)
+repren’s `--help` ends with the exact install commands. (`uvx` runs repren with no prior
+install; see the note on `@latest` and safety under [Installation](#installation).)
 
 **Install the skill yourself** (the same thing the agent does):
 
diff --git a/repren/repren.py b/repren/repren.py
index 8af8ff4..461ae00 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -9,22 +9,18 @@
 **zero runtime dependencies**. Essentially, it is a general-purpose, brute-force text
 file refactoring tool.
 
-**Using a coding agent?** This is the whole setup. Tell Claude Code, Codex, Gemini, or
-any agent:
+**Coding agents:** point your agent at repren and it installs itself as a skill:
 
 > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
-repren’s `--help` ends with the exact install commands, so the agent reads them and takes
-it from there. After that it reaches for repren automatically on bulk refactors and
-renames. (See [Agent Use](#agent-use).)
+repren’s `--help` ends with the exact install commands. Once installed, the agent uses
+repren automatically for bulk refactors and renames. (See [Agent Use](#agent-use).)
 
-**Zero dependencies, by design.** Given the rise of supply-chain attacks on package
-ecosystems, it’s worth noting that repren has **zero runtime dependencies**. Installing
-it (or running `uvx repren@latest`) pulls in nothing but repren itself and the Python
-standard library. There is no transitive dependency tree to audit or to be compromised,
-so it is simpler and safer to adopt than most tools. It’s also a single file you can read
-end to end (or have your agent review) before you trust it. The dev-only tooling used to
-build and test repren (pytest, ruff, etc.) is never installed when you use it.
+**Zero runtime dependencies.** Installing repren (or running `uvx repren@latest`) pulls in
+nothing but repren itself and the Python standard library, so there is no transitive
+dependency tree to audit or be compromised. It is a single file you can read end to end
+before trusting it. The dev-only tooling used to build and test repren (pytest, ruff, and
+so on) is never installed when you use it.
 
 For example, repren could rename occurrences of certain names in a set of source files,
 while simultaneously renaming the files and directories according to the same pattern
@@ -145,19 +141,10 @@
 | Agent skill support | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
 | Dependencies | Python 3.10+ (no other deps) | Varies (OS/shell) | Binary (Rust) | Binary (Rust) | Binary (Rust) | Binary (OCaml) | Binary (Rust) |
 
-Notes on the last two rows:
-
-- **Atomic file operations** means edits are written to a temp file and atomically
-  renamed into place, so an interruption never leaves a truncated or half-written file.
-  repren and `sd` do this for content edits; `rnr` only renames (and `rename()` is itself
-  atomic). For the classics it *varies*: GNU `sed -i` and `gawk -i inplace` write to a
-  temp file and rename, but `perl -i` is only atomic on Perl ≥ 5.28, and a plain
-  `cmd > file` redirect is never atomic. `fastmod`, `ast-grep`, and `comby` overwrite
-  files in place.
-- **Agent skill support** means the project ships an official coding-agent integration
-  (a skill or MCP server) so an agent can discover and drive it. repren installs a skill
-  via `repren --install-skill`; `ast-grep` ships an official agent skill and MCP server.
-  The others have no first-party agent integration.
+“Atomic file operations” means edits are written to a temp file and renamed into place,
+so an interrupted run never leaves a half-written file. repren and `sd` do this; `rnr`
+only renames; the classic tools vary; and `fastmod`, `ast-grep`, and `comby` overwrite in
+place.
 
 **When to use each:**
 
@@ -220,14 +207,12 @@
 
 ## Agent Use
 
-**The one thing to know:** point your agent at repren’s self-documenting help and let it
-install itself.
+Point your agent at repren’s self-documenting help to install the skill:
 
 > Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
 
-repren’s `--help` ends with the exact install commands, so the agent can take it from
-there. (`uvx` runs repren with no prior install; see the note on `@latest` and safety
-under [Installation](#installation).)
+repren’s `--help` ends with the exact install commands. (`uvx` runs repren with no prior
+install; see the note on `@latest` and safety under [Installation](#installation).)
 
 **Install the skill yourself** (the same thing the agent does):
 

From ff9785b7d702c85c6765b99ad9a5fbcc1d3b535f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 2 Jun 2026 16:09:09 +0000
Subject: [PATCH 18/18] docs: bold the install callout inside the block quote

Make the primary call to action stand out: bold the
"Run uvx repren@latest --help ..." line in the block-quote callout (intro and Agent Use).
Regenerated README and the docstring.

https://claude.ai/code/session_01RbwU9HuU5Ys84HVm94UdUz
---
 README.md           | 4 ++--
 docs/repren-docs.md | 4 ++--
 repren/repren.py    | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 6c81cf9..aff7786 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@ file refactoring tool.
 
 **Coding agents:** point your agent at repren and it installs itself as a skill:
 
-> Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
+> **Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.**
 
 repren’s `--help` ends with the exact install commands. Once installed, the agent uses
 repren automatically for bulk refactors and renames. (See [Agent Use](#agent-use).)
@@ -225,7 +225,7 @@ uvx repren@3.1.0 --help
 
 Point your agent at repren’s self-documenting help to install the skill:
 
-> Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
+> **Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.**
 
 repren’s `--help` ends with the exact install commands. (`uvx` runs repren with no prior
 install; see the note on `@latest` and safety under [Installation](#installation).)
diff --git a/docs/repren-docs.md b/docs/repren-docs.md
index b1faa93..2707376 100644
--- a/docs/repren-docs.md
+++ b/docs/repren-docs.md
@@ -9,7 +9,7 @@ file refactoring tool.
 
 **Coding agents:** point your agent at repren and it installs itself as a skill:
 
-> Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
+> **Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.**
 
 repren’s `--help` ends with the exact install commands. Once installed, the agent uses
 repren automatically for bulk refactors and renames. (See [Agent Use](#agent-use).)
@@ -207,7 +207,7 @@ uvx repren@3.1.0 --help
 
 Point your agent at repren’s self-documenting help to install the skill:
 
-> Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
+> **Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.**
 
 repren’s `--help` ends with the exact install commands. (`uvx` runs repren with no prior
 install; see the note on `@latest` and safety under [Installation](#installation).)
diff --git a/repren/repren.py b/repren/repren.py
index 461ae00..067df17 100755
--- a/repren/repren.py
+++ b/repren/repren.py
@@ -11,7 +11,7 @@
 
 **Coding agents:** point your agent at repren and it installs itself as a skill:
 
-> Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
+> **Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.**
 
 repren’s `--help` ends with the exact install commands. Once installed, the agent uses
 repren automatically for bulk refactors and renames. (See [Agent Use](#agent-use).)
@@ -209,7 +209,7 @@
 
 Point your agent at repren’s self-documenting help to install the skill:
 
-> Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.
+> **Run `uvx repren@latest --help` and follow the instructions to install repren as a skill.**
 
 repren’s `--help` ends with the exact install commands. (`uvx` runs repren with no prior
 install; see the note on `@latest` and safety under [Installation](#installation).)