From 3b06fae939770e099a17312e061ed862378a937a Mon Sep 17 00:00:00 2001
From: Aleksandr Kladov <mail@kladov.xyz>
Date: Tue, 28 Jul 2026 17:11:19 +0300
Subject: [PATCH] docs: restore agent-assisted setup

---
 README.md      | 28 ++++++++++++++++++++++++++++
 agent-guide.md | 25 +++++++++++++++++++++++--
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 2a53686..e31dc94 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,34 @@ The repository is `herdr-review`. The plugin ID retains the legacy
 `quantick.hunk-review` name so existing installations and keybindings keep
 working. The runtime no longer invokes or requires Hunk.
 
+## Agent-assisted setup
+
+**Recommended:** let a coding agent inspect the machine, install or link the
+plugin, preserve the existing Herdr configuration, add non-conflicting
+shortcuts, and validate the result.
+
+Paste this prompt into Codex, Claude, or another agent with terminal access:
+
+```text
+Set up Herdr Native Review on this machine.
+
+Read and follow this guide first:
+https://raw.githubusercontent.com/quantk/herdr-review/main/agent-guide.md
+
+Inspect the existing environment, installed Herdr plugins, and Herdr config
+before making changes. Preserve unrelated settings, avoid duplicate plugin
+installations and keybindings, validate the final config, reload it, and report
+exactly what changed.
+```
+
+The guide requires the setup agent to ask before installing OS-level
+dependencies or replacing conflicting keys or plugin installations. It also
+prevents the agent from opening a test review or inserting test text into an
+agent that is already running.
+
+Prefer to perform each step manually? Continue with the requirements and
+installation below.
+
 ## Features
 
 - Switches between working-tree, branch, and last-observed-agent-turn diffs.
diff --git a/agent-guide.md b/agent-guide.md
index 7be8674..33de1f3 100644
--- a/agent-guide.md
+++ b/agent-guide.md
@@ -25,6 +25,7 @@ herdr --version
 bun --version
 node --version
 git --version
+herdr plugin list --json
 ```
 
 Requirements:
@@ -39,9 +40,14 @@ If a prerequisite is missing or incompatible, stop and explain exactly what is
 needed. Do not install or upgrade it through an OS package manager without
 approval.
 
+Record any existing entry whose plugin ID is `quantick.hunk-review`, including
+its version, enabled state, and local or GitHub source. Read
+`~/.config/herdr/config.toml` when it exists and locate every assignment for
+`f6` and `f7` before changing either the plugin or its shortcuts.
+
 ## 2. Install
 
-For GitHub:
+If `quantick.hunk-review` is not installed, install it from GitHub:
 
 ```sh
 herdr plugin install quantk/herdr-review
@@ -51,7 +57,7 @@ Herdr runs the reviewed manifest build command (`npm ci --omit=dev`) before it
 registers the plugin. Do not register a checkout whose dependency install
 failed.
 
-For a local checkout:
+For a new local checkout:
 
 ```sh
 cd "/absolute/path/to/herdr-review"
@@ -62,6 +68,21 @@ herdr plugin link "$PWD" --enabled
 Resolve the checkout path; never invent it. `plugin link` does not run build
 commands, so install dependencies first.
 
+If the plugin is already installed, do not install or link a second copy.
+Compare its source and version with the current repository manifest. Enable an
+otherwise current disabled installation with:
+
+```sh
+herdr plugin enable quantick.hunk-review
+```
+
+The supported Herdr CLI has no separate `plugin update` command. Replacing an
+older GitHub installation or switching between GitHub and local sources may
+require `plugin uninstall` or `plugin unlink`, which can affect existing plugin
+state. Explain the detected situation and get the user's approval before
+replacing it; after approval, install or link the current source and verify that
+the same plugin ID is registered only once.
+
 Verify:
 
 ```sh