docs: improve local setup guide with env requirements and troubleshooting (#14)

Documents the two-layer env architecture (runner context vs sandbox .env.d),
per-agent env file requirements (GH_TOKEN, GIT_BOT_EMAIL), custom image
requirement, sandbox log inspection, and common local setup mistakes.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: durandom

.claude/skills/fullsend/references/local-setup.md

@@ -16,7 +16,7 @@ Guide for running fullsend agents locally on a Mac. Covers only RHDH-specific se
 Direct the user to the canonical upstream guide for all generic setup:
 
 ```
-📘 Follow the upstream guide first:
+Follow the upstream guide first:
    https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/user/running-agents-locally.md
 
    It covers: fullsend CLI download, OpenShell install, GCP credentials,
@@ -31,15 +31,20 @@ Our agents run on the `rhdh-sidekick-167988` GCP project. If the user's team lea
 
 Present the GCP env file with our project values filled in:
 
-```
+```bash
 # ~/.config/fullsend/gcp-vertex.env
 ANTHROPIC_VERTEX_PROJECT_ID=rhdh-sidekick-167988
 CLOUD_ML_REGION=us-east5
 GOOGLE_CLOUD_PROJECT=rhdh-sidekick-167988
-GOOGLE_APPLICATION_CREDENTIALS=/path/to/.config/fullsend/fullsend-local-credentials.json
+GOOGLE_APPLICATION_CREDENTIALS=/Users/<you>/.config/fullsend/fullsend-local-credentials.json
 FULLSEND_SANDBOX_IMAGE=ghcr.io/redhat-developer/rhdh-fullsend-code:latest
 ```
 
+**IMPORTANT:** `FULLSEND_SANDBOX_IMAGE` must point to the RHDH custom image, not the upstream
+default (`ghcr.io/fullsend-ai/fullsend-sandbox:dev`). The custom image includes corepack,
+yarn, and openspec — without it, `yarn install` and `openspec validate` will fail inside
+the sandbox.
+
 ### 3. RHDH custom sandbox image
 
 Our image extends upstream with corepack + yarn for JS monorepos:
@@ -57,42 +62,115 @@ podman build -t rhdh-fullsend-code:local \
 export FULLSEND_SANDBOX_IMAGE=localhost/rhdh-fullsend-code:local
 ```
 
-### 4. Running an RHDH agent
+### 4. Per-agent env files
+
+Each agent needs a local env file with the runner-context variables that
+`expand: true` substitutes into the sandbox. The scaffold's env templates
+(e.g., `env/code-agent.env`) reference `${GH_TOKEN}`, `${ISSUE_NUMBER}`, etc.
+— your local env file provides the values.
+
+**Common variables all agents need:**
+
+| Variable | Source | Notes |
+|----------|--------|-------|
+| `GH_TOKEN` | `gh auth token` | Read-only in sandbox; used for `gh` commands |
+| `ISSUE_NUMBER` | Per-run | The issue or PR number to work on |
+| `GITHUB_ISSUE_URL` | Per-run | Full URL to the issue |
+| `REPO_FULL_NAME` | Per-run | `owner/repo` format |
+
+**Code agent** (`~/.config/fullsend/code-agent.env`):
+
+```bash
+GH_TOKEN=<output of gh auth token>
+ISSUE_NUMBER=<number>
+GITHUB_ISSUE_URL=https://github.com/redhat-developer/rhdh-plugins/issues/<number>
+REPO_FULL_NAME=redhat-developer/rhdh-plugins
+GIT_BOT_EMAIL=noreply@local
+GIT_AUTHOR_NAME=fullsend-local
+GIT_AUTHOR_EMAIL=noreply@local
+GIT_COMMITTER_NAME=fullsend-local
+GIT_COMMITTER_EMAIL=noreply@local
+MAX_RETRIES=1
+TIMEOUT_SECONDS=2100
+```
+
+`GIT_BOT_EMAIL` is required — the scaffold's `code-agent.env` template uses
+`${GIT_BOT_EMAIL}` for `GIT_AUTHOR_EMAIL` and `GIT_COMMITTER_EMAIL`. In CI,
+this is resolved from the GitHub App bot identity. Locally, `noreply@local` works.
 
-After gateway is running, show a typical triage run:
+**Triage agent** (`~/.config/fullsend/triage.env`):
 
 ```bash
-# Agent-specific env
-# ~/.config/fullsend/triage.env
-GH_TOKEN=<your-github-pat>
+GH_TOKEN=<output of gh auth token>
 GITHUB_ISSUE_URL=https://github.com/<org>/<repo>/issues/<number>
 ```
 
+### 5. Running an RHDH agent
+
+After gateway is running (`~/.config/fullsend/start-gateway.sh`), run an agent:
+
 ```bash
+# Triage (quickest — ~2 min, ~$2)
 fullsend run triage \
-  --fullsend-dir /path/to/fullsend/internal/scaffold/fullsend-repo/ \
-  --target-repo /path/to/your/target-repo/ \
+  --fullsend-dir ~/src/rhdh/asdlc-lab/resources/fullsend-ai/fullsend/internal/scaffold/fullsend-repo/ \
+  --target-repo ~/src/rhdh/rhdh-plugins/ \
   --env-file ~/.config/fullsend/gcp-vertex.env \
   --env-file ~/.config/fullsend/triage.env \
   --no-post-script
+
+# Code (full run — ~15-35 min, ~$15-30)
+fullsend run code \
+  --fullsend-dir ~/src/rhdh/asdlc-lab/resources/fullsend-ai/fullsend/internal/scaffold/fullsend-repo/ \
+  --target-repo ~/src/rhdh/rhdh-plugins/ \
+  --env-file ~/.config/fullsend/gcp-vertex.env \
+  --env-file ~/.config/fullsend/code-agent.env \
+  --no-post-script
 ```
 
-`--no-post-script` prevents the agent from modifying the GitHub issue. Remove it when you want the agent to act on its triage result.
+`--no-post-script` prevents the agent from pushing branches or creating PRs.
+Remove it only when you want the agent to act on its result.
+
+### 6. Checking sandbox logs
+
+After a run, inspect sandbox logs for network policy issues:
 
-Refer to the upstream guide's per-agent env var tables for `code`, `review`, and `fix` agents.
+```bash
+# Find the latest run output
+ls -td /tmp/fullsend/agent-*/ | head -1
+
+# Check for DENIED requests
+grep "DENIED" /tmp/fullsend/agent-*/logs/openshell-sandbox.log | sort | uniq -c | sort -rn
+
+# Full sandbox log
+less /tmp/fullsend/agent-*/logs/openshell-sandbox.log
+```
 
-### 5. What to expect
+### 7. What to expect
 
 | Metric | Value |
 |--------|-------|
 | Sandbox creation | ~2-8 seconds |
 | Bootstrap | ~7 seconds |
 | Agent inference | ~30-60 seconds per iteration |
 | Total (triage) | ~2 minutes |
+| Total (code) | ~15-35 minutes |
 | Estimated cost (triage) | ~$2.00 |
+| Estimated cost (code) | ~$15-30 |
+
+Output: `/tmp/fullsend/agent-<type>-*/iteration-*/output/agent-result.json`
+
+### 8. Troubleshooting (RHDH-specific)
 
-Output: `/tmp/fullsend/agent-triage-*/iteration-*/output/agent-result.json`
+For generic troubleshooting (sandbox creation, gateway connectivity, missing env vars,
+arm64 image pulls, Podman host-gateway), see the upstream guide.
 
-### 6. Troubleshooting (RHDH-specific)
+**Common local setup mistakes:**
 
-For generic troubleshooting (sandbox creation, gateway connectivity, missing env vars, arm64 image pulls, Podman host-gateway), see the upstream guide.
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `yarn: command not found` | Using upstream default image instead of RHDH custom image | Set `FULLSEND_SANDBOX_IMAGE=ghcr.io/redhat-developer/rhdh-fullsend-code:latest` in gcp-vertex.env |
+| Agent can't run `gh` commands | Missing `GH_TOKEN` in local env file | Add `GH_TOKEN=<gh auth token>` to your agent env file |
+| Git commits fail with empty email | Missing `GIT_BOT_EMAIL` in code-agent.env | Add `GIT_BOT_EMAIL=noreply@local` — the scaffold template uses `${GIT_BOT_EMAIL}` |
+| `COREPACK_HOME` not set | Using upstream image (Docker ENV stripped at runtime) | Use RHDH custom image + `rhdh-toolchain.env` sets it via `.env.d/` |
+| `DENIED ... edge.openspec.dev:443` | openspec telemetry not in policy | Set `OPENSPEC_TELEMETRY=0` in `rhdh-toolchain.env` |
+| 268 DENIED for `registry.npmjs.org` | Yarn scoped packages use `%2F` encoding | Add `allow_encoded_slash: true` to npmjs endpoint in policy |