agents.md: document upstream PR prep via agent-helpers/upstream-pr-prep.sh

Adds a new 'Upstream PR prep' section to the agent-facing build/run/test
instructions, pointing at the helper script shipped in this session
(commit 77532cf, merged to master via 89f87b5). Covers:

- Script invocation with all mode flags (prep, build, push, cleanup,
  dry-run)
- Prerequisites: gh auth login, jq installed
- Commit message review flow (agent prepares, operator confirms in
  chat, script reads file verbatim)
- Worktree strategy (not git switch -c, to keep agent-helpers/
  intact)
- /tmp-tmpfs workaround via --worktree /var/tmp/...
- Explicit 'never run travis-install-build-deps.sh'
- Convention: strip Co-Authored-By, no Signed-off-by
- Cross-references to auto-memory reference_upstream_pr_workflow.md
  and the lab parking doc at
  lab/cncmill1/memory/parked-linuxcnc-upstream-teleop-pr.md

Author: igor

agents.md

@@ -198,3 +198,60 @@ Revert to regular build:
 ```bash
 cd src && ./configure --with-realtime=uspace && make clean && make -j$(nproc) && cd ..
 ```
+
+---
+
+## Upstream PR prep
+
+When a fix exists on fork `master` and needs to go upstream as a PR
+against `LinuxCNC/linuxcnc`, use the helper script — not raw cherry-pick
+commands:
+
+```bash
+agent-helpers/upstream-pr-prep.sh \
+    --commit <fork-sha> \
+    --branch <pr-branch-name> \
+    --message /tmp/upstream-commit-msg.txt \
+    --worktree /var/tmp/linuxcnc-pr-<branch> \
+    [--build] [--push] [--cleanup] [--dry-run]
+```
+
+Default (no mode flag) runs prep: `git fetch upstream`, `git worktree add`
+off `upstream/master`, `git cherry-pick --no-commit`, strict diff
+verification, commit with dynamically-resolved GitHub-noreply author
+(via `gh api user`), and post-commit verification. Add `--build` to run
+`autogen`+`configure`+`make` matching upstream CI exactly. Add `--push`
+to push the PR branch to `origin` and print the compare URL. `--cleanup`
+tears down the worktree after the PR is open. `--dry-run` combines with
+any mode to print the would-be commands without executing.
+
+Prerequisites (one-time setup):
+- `gh auth login` — the script calls `gh api user` at commit time to
+  resolve the commit author dynamically as `<login> <id+login@users.noreply.github.com>`.
+  Never hardcoded, never cached.
+- `jq` installed — used to parse `gh api user` JSON output.
+
+Workflow notes for agents:
+- **Commit message is prepared by the agent, reviewed by the operator
+  in chat, then handed to the script via `--message <file>`.** The
+  script never prompts interactively — all review happens in chat.
+- **Worktree, not `git switch -c`.** A naive `git switch -c … upstream/master`
+  from the main working tree would wipe `agent-helpers/` (not on
+  upstream/master), breaking the wrapper on the next invocation. The
+  helper uses `git worktree add` so the main fork working tree stays
+  intact with `agent-helpers/` present.
+- **Pass `--worktree /var/tmp/linuxcnc-pr-<branch>`** on every invocation
+  if `/tmp` is tmpfs on the machine (the build artifacts are hundreds
+  of MB and would eat RAM). The script warns at preflight but doesn't
+  refuse.
+- **Never run `scripts/travis-install-build-deps.sh`** — that's what
+  upstream CI runs to set up a fresh container, and it installs system
+  packages via apt. The script never invokes it; rely on system deps
+  already installed from prior fork builds.
+- **Strip `Co-Authored-By:` trailers** from commit messages — absent
+  from recent upstream motion-area commits, stripping matches convention.
+- **No `Signed-off-by:`** needed — no DCO convention in LinuxCNC.
+
+See also: `reference_upstream_pr_workflow.md` in auto-memory, and
+`lab/cncmill1/memory/parked-linuxcnc-upstream-teleop-pr.md` for the full
+procedure with a worked example (PR #3933).