docs(contributing): document testing agent changes against a remote provider

CONTRIBUTING.md

@@ -180,6 +180,35 @@ This requires:
    ./dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 up examples/simple
    ```
 
+### Testing Agent Changes Against a Remote/SSH Provider
+
+The Quick Start above works because with a local `docker` provider, the CLI
+process you just built *is* the agent. For any remote/SSH/cloud provider, the
+agent runs as a separate binary injected onto that host, so testing a change
+to agent code (`pkg/agent`, `pkg/git`, etc.) needs a couple of extra steps.
+
+1. Build dev binaries for every OS/arch (`task cli:build:dev` builds all of
+   them in one pass: `dist/devsy-dev_<os>_<arch>*/devsy-<os>-<arch>`).
+2. Set `DEVSY_AGENT_BINARY` to the binary matching your **remote host's**
+   OS/arch (not your own machine's) before running `up`/`ssh`/etc. Check
+   `devsy workspace list` for the provider's `HOST`/target arch if unsure.
+3. If you've tested against that workspace before, the remote host likely
+   already has an agent binary cached at the provider's `AGENT_PATH`. A dev
+   build (`version == v0.0.0`) skips the remote version check and only
+   verifies *that a binary exists* there — so a stale cached binary is
+   silently reused instead of your new one. Delete it first to force a fresh
+   injection: `ssh <host> rm -f <AGENT_PATH>` (both values are in
+   `devsy workspace list`'s provider options).
+
+```bash
+task cli:build:dev
+ssh <host> rm -f <AGENT_PATH>
+DEVSY_AGENT_BINARY=./dist/devsy-dev_linux_arm64_v8.0/devsy-linux-arm64 \
+  ./dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 workspace up <workspace> --reset
+```
+
+`task cli:test:remote` automates this (see below).
+
 ### Using Act for Local CI Testing
 
 ```bash
@@ -265,6 +294,7 @@ task cli:build              # Build CLI for production
 task cli:build:dev          # Build CLI for development
 task cli:lint               # Run linters
 task cli:test               # Run unit tests
+task cli:test:remote        # Test agent changes against a remote/SSH provider workspace
 task cli:tidy               # Tidy go.mod and go.sum
 
 # Desktop tasks

Taskfile.yml

@@ -88,6 +88,28 @@ tasks:
     desc: run devsy unit tests
     cmd: go test $(go list ./... | grep -v -e /test -e /e2e) -race -coverprofile=dist/profile.out -covermode=atomic
 
+  cli:test:remote:
+    # usage: HOST=user@host AGENT_PATH=/tmp/user/devsy/agent task cli:test:remote -- <workspace> [extra up flags]
+    # HOST/AGENT_PATH come from `devsy workspace list`'s provider options.
+    # GOOS/GOARCH target the remote host (default linux/arm64); override for e.g. an amd64 cloud VM.
+    desc: build a dev binary and inject it into a remote/SSH-provider workspace, bypassing the stale cached-binary reuse
+    vars:
+      GOOS: '{{.GOOS | default "linux"}}'
+      GOARCH: '{{.GOARCH | default "arm64"}}'
+    preconditions:
+      - sh: '[ -n "{{.HOST}}" ]'
+        msg: "HOST is required, e.g. HOST=user@host task cli:test:remote -- my-workspace"
+      - sh: '[ -n "{{.AGENT_PATH}}" ]'
+        msg: "AGENT_PATH is required (see `devsy workspace list`), e.g. AGENT_PATH=/tmp/user/devsy/agent"
+    cmds:
+      - task: cli:build:dev
+      - ssh {{.HOST}} rm -f {{.AGENT_PATH}}
+      - |
+        set -e
+        remote_bin="$(find dist -maxdepth 1 -type d -name 'devsy-dev_{{.GOOS}}_{{.GOARCH}}*')/devsy-{{.GOOS}}-{{.GOARCH}}"
+        local_bin="$(find dist -maxdepth 1 -type d -name "devsy-dev_$(go env GOOS)_$(go env GOARCH)*")/devsy-$(go env GOOS)-$(go env GOARCH)"
+        DEVSY_AGENT_BINARY="$remote_bin" "$local_bin" workspace up {{.CLI_ARGS}} --reset
+
   cli:test:e2e:build:
     desc: build devsy for e2e tests
     status: