Add agentpr and watchpr CLI tools

agentpr manages PRs/comments/whoami as unkin-agent (Vault AppRole -> gitea creds
-> Gitea API), fixing tea's post-as-Ben default. watchpr polls PRs and alerts
only on merge/close, human comment, CI failure, or lost mergeability.

- cobra multi-binary layout mirroring node-lookup (cmd/ + internal/)
- Makefile (build, patch|minor|major, completions, rpm), nfpm RPM with both
  binaries + bash/zsh/fish completions, woodpecker CI publishing to rpm-internal
- unit tests for parsing, meaningful-change detection, and the Vault+Gitea client

README.md

@@ -1,3 +1,86 @@
 # agent-tools
 
-CLI tools for orchestrator PR automation as unkin-agent
+Two small Gitea-automation CLIs, shipped together in one RPM (`agent-tools`).
+Both act as the **`unkin-agent`** user by minting a scoped Gitea token from
+Vault, so automated PRs and comments are attributed to the agent — not to
+whoever happens to run the command.
+
+- **`agentpr`** — create pull requests and post PR comments as `unkin-agent`.
+- **`watchpr`** — poll one or more PRs and exit when one changes in a way worth
+  acting on.
+
+## How it gets a token
+
+On first use each tool performs a Vault AppRole login (`role_id` only, no
+`secret_id`), then reads `gitea/creds/unkin-agent` to obtain a short-lived Gitea
+token, cached in-process for the run.
+
+Everything is configured by environment variables, all with defaults:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `VAULT_ADDR` | `https://vault.service.consul:8200` | Vault/OpenBao address |
+| `AGENT_APPROLE_ROLE_ID` | `ababbcd3-9c77-5c6a-be2d-287fce9214a6` | AppRole role_id |
+| `GITEA_URL` | `https://git.unkin.net` | Gitea base URL |
+| `AGENT_LOGIN` | `unkin-agent` | login whose comments `watchpr` ignores |
+
+## agentpr
+
+```bash
+# Verify identity (should print: unkin-agent)
+agentpr whoami
+
+# Open a PR
+agentpr pr create --repo unkin/argocd-apps \
+  --base main --head benvin/my-change \
+  --title "Add woodpecker SA" --body "Adds the ServiceAccount ..."
+# prints: #<number> <html_url>
+
+# Comment on a PR
+agentpr pr comment --repo unkin/argocd-apps --pr 42 --body "Rebased, CI green."
+
+agentpr --version
+agentpr --help
+```
+
+Non-zero exit on any API error.
+
+## watchpr
+
+Poll PRs and exit (reporting what changed) when a tracked PR **merges/closes**,
+gets a **new comment from someone other than the agent**, its **CI fails**
+(failure/error), or it **loses mergeability** (a conflict appears). Benign
+transitions — CI `pending`→`success`, the agent's own comments — are ignored.
+
+```bash
+# Watch until something meaningful happens (default interval 60s)
+watchpr unkin/argocd-apps#42
+
+# Multiple PRs, custom interval; refs accept #N or :N
+watchpr --interval 30s unkin/argocd-apps#42 unkin/terraform-vault:98
+
+# One-shot: print current state and exit 0 (great for scripts)
+watchpr --once unkin/argocd-apps#42
+watchpr --once --json unkin/argocd-apps#42
+```
+
+On a meaningful change `watchpr` prints the reason and the PR's current state,
+then exits 0. Use `--json` for machine-readable output.
+
+## Build & package
+
+```bash
+make build                 # -> dist/agentpr, dist/watchpr
+make test                  # go test -race ./...
+make rpm                   # build + package dist/agent-tools-<version>-1.x86_64.rpm
+```
+
+Release is tag-driven (`v*`) via Woodpecker: builds the RPM, `PUT`s it to the
+artifactapi `rpm-internal` yum repo, and cuts a Gitea release with
+cross-compiled binaries attached.
+
+### Version bump
+
+```bash
+make patch   # or: make minor / make major  — tags vX.Y.Z and pushes the tag
+```