docs(guides): migrate runner_env examples to env.runner

[ralphbean]

Summary

• Update harness YAML examples in customizing-agents.md and building-custom-agents.md to use the unified env: schema (ADR 0055)
• Replace deprecated runner_env: with env.runner: sub-map
• Update prose reference from "runner_env variables" to "env.runner variables"

Follows up on #2582.

Test plan

• Verify YAML examples render correctly in the doc site
• Confirm no remaining runner_env references in user-facing guides

🤖 Generated with Claude Code

[qodo-code-review]

PR Summary by Qodo

Docs: migrate harness examples from runner_env to env.runner

📝 Documentation 🕐 10-20 Minutes

AI Description

• Update harness YAML examples to use unified env.runner schema (ADR 0055).
• Replace deprecated runner_env blocks in user guides.
• Refresh prose to reference env.runner variables instead of runner_env.

Diagram

graph TD
  A["User guides"] --> B["YAML examples"] --> C["Harness config: env.runner"]
  D["ADR 0055"] --> C
  E["Deprecated: runner_env"] -.-> C

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Centralize harness YAML snippets as shared includes

• ➕ Eliminates duplication across guides, reducing drift during future schema migrations
• ➕ Makes bulk schema updates (like runner_env → env.runner) one-touch
• ➖ Requires doc tooling support (or conventions) for includes/partials
• ➖ Slightly harder for readers to see complete examples inline

2. Add a short compatibility/deprecation note near the examples

• ➕ Helps readers upgrading older harnesses understand why the field changed
• ➕ Reduces support churn from users searching for runner_env
• ➖ Adds extra text to the guide; may be unnecessary if deprecation is documented elsewhere

Recommendation: Current approach is correct for a follow-up migration: update the canonical examples and prose to the new schema. If similar schema shifts are expected again, consider centralizing YAML snippets to avoid repeated multi-file edits; otherwise this PR is sufficient as-is.

Files changed (2) +17 / -14

Documentation (2) +17 / -14

building-custom-agents.mdSwitch harness example to env.runner and update runner_env prose reference +7/-6

Switch harness example to env.runner and update runner_env prose reference

• Replaces the 'runner_env:' YAML example block with the unified 'env: { runner: ... }' structure. Updates the checklist prose to refer to 'env.runner' variables instead of 'runner_env' variables.

docs/guides/user/building-custom-agents.md

customizing-agents.mdMigrate customizing guide YAML examples from runner_env to env.runner +10/-8

Migrate customizing guide YAML examples from runner_env to env.runner

• Updates both harness YAML example blocks to replace 'runner_env:' with 'env.runner:'. Keeps the example variable names and intent intact while aligning with the ADR 0055 schema.

docs/guides/user/customizing-agents.md

[github-actions]

Site preview

Preview: https://5c4f7143-site.fullsend-ai.workers.dev

Commit: e9113c9d9badcabae7e129f4d895acffbf9af2f5

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 5:17 PM UTC · Completed 5:26 PM UTC
Commit: 2cd430f · View workflow run →

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (1)

Context used

✅ Compliance rules (platform): 51 rules

✅ Skills: writing-user-docs, writing-adrs

1. env.runner undefined in guide 📜 Skill insight ✧ Quality

Description

The updated harness examples introduce env.runner without defining what it means (or linking to a
glossary entry) at first use, which can confuse readers migrating from runner_env and leave the
distinction from other env scopes unclear. This violates the requirement to define jargon on first
use.

Code

docs/guides/user/building-custom-agents.md[R146-151]

+env:
+  runner:
+    MY_VAR: "${MY_VAR}"
+    ISSUE_KEY: "${ISSUE_KEY}"
+    GH_TOKEN: "${GH_TOKEN}"  # auto-minted in CI when --mint-url is provided
+    FULLSEND_OUTPUT_SCHEMA: ${FULLSEND_DIR}/customized/schemas/my-agent-result.schema.json

Relevance

⭐⭐⭐ High

Docs reviews often require defining/clarifying new terms and adding glossary links (accepted in PR
#665, #1179).

PR-#665
PR-#1179

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062083 requires domain-specific terms/jargon to be defined (or linked) on first
use. In the modified documentation, the YAML harness snippets introduce the new schema key
env.runner and later refer to it again, but the surrounding text at those first-use locations does
not provide an inline definition or a glossary link, leaving readers without the necessary context.

docs/guides/user/building-custom-agents.md[146-151]
docs/guides/user/building-custom-agents.md[466-466]
docs/guides/user/customizing-agents.md[43-47]
docs/guides/user/customizing-agents.md[362-366]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`env.runner` is introduced in YAML examples in the guide without an inline definition or a glossary link on first use.

## Issue Context
This PR migrates/replaces the deprecated `runner_env` with the unified `env.runner` schema. Readers need a short definition clarifying what `env.runner` controls (e.g., runner-side `pre_script`/`post_script` environment vs the sandbox) and how it differs from other `env` scopes.

## Fix Focus Areas
- docs/guides/user/building-custom-agents.md[146-151]
- docs/guides/user/building-custom-agents.md[466-466]
- docs/guides/user/customizing-agents.md[43-47]
- docs/guides/user/customizing-agents.md[362-366]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Overbroad env.runner rule 🐞 Bug ≡ Correctness

Description

building-custom-agents.md says all env.runner variables must be set in the workflow env block,
but env.runner entries can be literals and can reference runtime-injected values like
FULLSEND_DIR. This makes the guidance imprecise and can cause unnecessary (or incorrect) workflow
env wiring during setup/debugging.

Code

docs/guides/user/building-custom-agents.md[466]

+6. **All `env.runner` variables** must appear in the workflow `env` block. If your harness references `MY_VAR: "${MY_VAR}"`, the workflow must set `MY_VAR`.

Relevance

⭐⭐⭐ High

Team regularly fixes imprecise/misleading doc requirements (accepted wording-accuracy fixes in PR
#1179, #1688).

PR-#1179
PR-#1688

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The page asserts a blanket workflow requirement for env.runner, but the same page’s harness
example contains an env.runner entry that doesn’t need to be set in the workflow (it references
${FULLSEND_DIR}). The runner explicitly injects FULLSEND_DIR during expansion, and ADR 0055
defines env.runner as a harness field whose values support ${VAR} expansion rather than
requiring all keys to come from workflow env.

docs/guides/user/building-custom-agents.md[146-152]
docs/guides/user/building-custom-agents.md[454-466]
internal/cli/run.go[361-392]
docs/ADRs/0055-unified-env-var-delivery.md[62-78]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The guide currently states that **all** `env.runner` variables must appear in the GitHub Actions workflow `env` block. This is too broad: only *host env vars referenced by interpolation* (e.g. `${MY_VAR}`) must be provided by the workflow; `env.runner` can also contain literal values, and some interpolations (e.g. `${FULLSEND_DIR}`) are provided/injected by Fullsend.

## Issue Context
The same page’s harness example includes an `env.runner` value that references `${FULLSEND_DIR}`, and the CLI injects `FULLSEND_DIR` during env expansion.

## Fix Focus Areas
- docs/guides/user/building-custom-agents.md[454-466]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[fullsend-ai-review]

Looks good to me

---

Follow-up: Six scaffold harness templates (internal/scaffold/fullsend-repo/harness/{code,fix,prioritize,retro,review,triage}.yaml) still use the deprecated runner_env: key. These are pre-existing and functionally correct (the runtime supports both forms with deprecation warnings per ADR 0055), but should be migrated to env.runner: in a follow-up PR as part of the Phase 2 scaffold migration.

Previous run

Looks good to me

---

Labels: PR updates user-facing harness configuration guides for the env.runner schema migration.

[fullsend-ai-review]

🤖 Review · ❌ Terminated · Started 11:44 AM UTC · Ended 11:55 AM UTC
Commit: 104508d · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:44 AM UTC · Completed 11:55 AM UTC
Commit: e9113c9 · View workflow run →

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 3:10 PM UTC · Completed 3:16 PM UTC
Commit: e9113c9 · View workflow run →

[fullsend-ai-retro]

Retro: PR #2756 — docs(guides): migrate runner_env examples to env.runner

Workflow went smoothly. This was a minimal docs-only change (+17/−14 across 2 files) by a human author. The review agent approved and flagged a useful follow-up (six scaffold harness templates still using deprecated runner_env:). A human reviewer also approved without comments. The PR merged in ~2 days.

Observations

• Review agent quality: The fullsend review agent caught the scaffold template follow-up, which was a good cross-codebase observation. However, the Qodo bot independently identified two documentation accuracy issues (undefined jargon on first use, overbroad prose claim) that the fullsend review agent did not flag.
• Follow-up tracking gap: The review agent's scaffold migration follow-up was noted in a PR comment but was never converted into a tracked GitHub issue. This pattern is already tracked by existing issues (Auto-file tracking issues for unresolved medium+ severity review findings #1956, Auto-file tracking issues for unresolved low-severity review findings #1286).
• Documentation review depth: The gap between fullsend review agent and Qodo on docs accuracy is already tracked by existing issues (Review agent should fact-check technical claims in documentation PRs #2199 — fact-checking technical claims in docs PRs, Review agent provides shallow feedback on documentation PRs #1480 — shallow feedback on documentation PRs).

No new proposals filed

All identified improvement opportunities are already covered by existing open issues:

• Review agent should fact-check technical claims in documentation PRs #2199 — Review agent should fact-check technical claims in documentation PRs
• Review agent provides shallow feedback on documentation PRs #1480 — Review agent provides shallow feedback on documentation PRs
• Auto-file tracking issues for unresolved medium+ severity review findings #1956 — Auto-file tracking issues for unresolved medium+ severity review findings
• Auto-file tracking issues for unresolved low-severity review findings #1286 — Auto-file tracking issues for unresolved low-severity review findings

Filing duplicates would add noise. The existing issues adequately capture the gaps observed here.