docs(#6539): one local-run flow — pi is a --runtime flag on the standard examples

[waynesun09]

Stacked on #6583 (agent/6581-per-role-overrides, in the merge queue): the doc now describes the per-agent runtime/model/effort settings that PR adds. Base retargets to main automatically when #6583 merges (the repo deletes merged branches).

Summary

Replaces the 350-line pi-specific walkthrough in docs/guides/user/running-agents-locally.md with a single local-run flow that stays runtime-agnostic: the existing fleet examples plus a short "Choosing the runtime" redirect (one --runtime pi command and links to the Runtimes section). The pi content that a local run actually needs moves to a new Running it locally section on docs/runtimes/pi.md, and the per-agent agent set → agent list → plan-block flow lands in the per-agent section of docs/runtimes.md (from #6583). Shape agreed with @rh-hemartin's review comment. 890 → 562 lines; no code changes.

The example output is verbatim from a verified run of fullsend main @ 89bf3b8 against fullsend-ai/agents main @ 299f264 (macOS Apple Silicon and Fedora): harness-default Model:/Effort: print bare, overridden values carry (from …), metrics.json shows runtime_source separately from override_source. review/retro were re-confirmed schema-valid under --runtime pi (single-context, stated as such). The doc deliberately shows Gemini selection syntax without a success transcript (known model-behaviour items are tracked in #6527/#6535).

Note: the code agent's run for #6539 ended with "no changed files", so this PR was authored directly by the human takeover session.

Rebase 2026-08-25 (after #6574 / #6583) and reshape per review

• d3bcc36 (answering @rh-hemartin): the guide keeps exactly one pi command; everything else pi moved to the Pi page. Follow-up (not in this PR): move "Debugging network policies locally" to its own page and the status/remote flag tables into docs/cli/run.md.

• docs/runtimes.md is no longer touched: the callout this PR rewrote moved to docs/runtimes/pi.md in docs: split runtimes.md into a user page and an implementer page #6574, so that page's two links now target #choosing-the-runtime; the pi-notes cross-link goes to the Pi page and the security feature matrix in runtime-implementation.md.

• v0.37.0 is the first release that carries the pi runtime (internal/runtime/pi*.go is in the tag; fullsend-runner:0.37.0 published), so the build-from-main bullet and the guides-index caveat are gone.

• Per-agent settings from feat(#6581): per-agent runtime, model and effort on agents: entries #6583: the override table gains a "Per-agent config" column and the precedence line reads flag > env > the agent's agents: entry > repo-wide; a "Make it stick per agent" flow (set → list → plan block, early validation errors) is taken from the local verification matrix on feat(#6581): per-agent runtime, model and effort on agents: entries #6583 — the fleet clone the guide already uses is a per-repo-style config, so fullsend agent set … --fullsend-dir /tmp/fullsend-agents/ works on the guide's own example.

Site preview check (playwright, 2026-08-25)

Verified on the PR preview: guide stub + alias anchors + See also, the Pi page's new section and troubleshooting, the runtimes per-agent list — all internal links 200, same-page anchors resolve, no console errors. Two things it caught, fixed in follow-up commits: a line-wrapped <config path> code span rendered as <config path>, and the per-agent heading's anchor — VitePress slugs config.yaml as config-yaml, GitHub as configyaml — so the four links to it (three from #6583) landed at the page top on the site; the heading is now "Per-agent runtime, model and effort" (same slug on both). The same GitHub-vs-VitePress divergence affects ~20 older links (ADRs, landscape, architecture) — out of scope here, noted for the follow-up.

Review rounds

• Round 1 (Grok, full diff): no CRITICAL; one HIGH — the docs/runtimes.md callout still promised a "no fleet repo required" walkthrough (rewritten); MEDIUMs all applied: image requirement now referenced as v0.37.0+ (was an unsourced tag mix-up), the deleted section's operational knowledge relocated into a pi runtime Troubleshooting subheading (sandbox env via harness host_files not --env-file per ADR 0055, export needed in .env.d files — re-verified against run.go's plain . sourcing loop — the disabled-provider symptom, the silent-Claude fallback and where the plan block shows it), the container path carries the same build-from-main caveat, HTML alias anchors keep the three old permalinks working, the Gemini example is a full command, run-dir tree notes pi-debug.log, guides index no longer claims released binaries cover pi.
• Accuracy checks that passed in review: withSource bare-vs-annotated printing, FULLSEND_PI_PROVIDER default, FULLSEND_PI_BASH_ALLOWLIST=enforce, the #choosing-the-runtime anchor.

Related Issue

Closes #6539

Changes

• Delete "Run a minimal agent on the pi runtime" and all subsections (pi-hello harness layout, pi knobs, pi security hooks, pi troubleshooting, pi platform notes)
• Add "Run default agents → Choosing the runtime" — a redirect: one --runtime pi command, links to Agent runtimes and Pi › Running it locally, alias anchors for the three old permalinks; plus a See also at the end of the guide
• docs/runtimes/pi.md: new "Running it locally" section (prerequisite pointer, verified plan block, model selection, v0.37.0+ CLI/image, platforms, single-context review/retro, knobs, hooks, debugging) and five troubleshooting entries moved from the guide
• docs/runtimes.md: the per-agent section's CLI line grows into the set → list → plan-block flow with generic paths
• Re-point the Pi runtime page's (docs/runtimes/pi.md) two local-run links to the new anchor

Testing

• make lint equivalents on changed files: docs-link lint, lychee, markdown checks via pre-commit — clean
• Tests added/updated for new or modified logic — N/A (docs only)

Checklist

• PR title follows Conventional Commits (correct type, ! for breaking changes)
• Commits are signed off (DCO) — human and human-directed agent sessions only
• I wrote this contribution myself and can explain all changes in it

[qodo-code-review]

PR Summary by Qodo

Docs: unify local-run guide; choose pi via --runtime on standard examples

📝 Documentation 🕐 20-40 Minutes

AI Description

• Replace the separate pi walkthrough with a single “run locally” flow using fleet examples.
• Document runtime selection via --runtime pi, including override precedence and verified output.
• Update runtime docs to link to the new “Choosing the runtime” section.

Diagram

graph TD
  A["running-agents-locally.md"] --> B["Standard examples"] --> C{{"Choose runtime"}}
  C --> D["--runtime pi"]
  C --> E["Override precedence"]
  F["runtimes.md"] --> A

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep a separate pi walkthrough (shortened)

• ➕ Dedicated space for pi-specific harness/security/troubleshooting details
• ➕ Reduces cognitive load for Claude Code-only readers
• ➖ Duplicates the core local-run flow and diverges over time
• ➖ Encourages treating pi as a separate product path instead of a runtime toggle

2. Move pi operational details to a dedicated pi runtime guide (and link from local-run)

• ➕ Keeps the local-run guide minimal while still providing depth
• ➕ Allows expanding pi troubleshooting without bloating the main guide
• ➖ More navigation/context switching for users trying pi for the first time
• ➖ Requires curating two entry points and keeping links/anchors stable

3. Generate runtime-selection docs from CLI help/flags (doc-as-code)

• ➕ Reduces risk of drift in flags/precedence rules over time
• ➕ Makes it easier to keep transcripts/fields aligned with actual output
• ➖ Higher upfront tooling cost for a docs-only change
• ➖ Harder to include narrative guidance and verified transcripts cleanly

Recommendation: The PR’s approach is the best default: treat pi as a per-run runtime choice on the existing, canonical commands. This removes parallel “how to run locally” narratives and makes the runtime toggle explicit (--runtime pi) while still preserving essential pi caveats (build-from-main, image version, single-context review/retro, debug behavior). If pi-specific operational content grows again, consider a dedicated pi runtime appendix linked from this section rather than reintroducing a full parallel walkthrough.

Files changed (2) +73 / -359

Documentation (2) +73 / -359

running-agents-locally.mdUnify local-run flow and add “Choosing the runtime” ('--runtime pi') +72/-358

Unify local-run flow and add “Choosing the runtime” ('--runtime pi')

• Adds a new “Choosing the runtime” subsection showing pi as an opt-in runtime flag on the existing example commands, including verified sample output and an override-precedence table. Removes the prior long, pi-specific end-to-end walkthrough (custom harness layout, knobs, security hooks, troubleshooting, platform notes). Folds minimal pi platform verification notes into the existing macOS/Linux platform sections.

docs/guides/user/running-agents-locally.md

runtimes.mdUpdate pi local-run link to new anchor in local-run guide +1/-1

Update pi local-run link to new anchor in local-run guide

• Repoints the ‘Running pi locally?’ reference from the removed pi walkthrough section to the new “Choosing the runtime” anchor in the local-run guide.

docs/runtimes.md

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 7:36 PM UTC · Ended 7:42 PM UTC

Commit: bae6eac · View workflow run →

[github-actions]

Site preview

Preview: https://cd0ffaa1-site.fullsend-ai.workers.dev

Commit: cb50b8f04398981569e4d8d7650f34a5cb8a2bb5

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[qodo-code-review]

Code Review by Qodo

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

1. Outdated pi local-run claim ✓ Resolved 🐞 Bug ≡ Correctness

Description

docs/runtimes.md still says the linked pi local-run walkthrough requires “no fleet repo”, but the
new target section (“Choosing the runtime”) assumes you cloned fullsend-ai/agents and uses
/tmp/fullsend-agents. This mismatch will mislead readers and breaks the promise implied by the
link text (“Run a minimal agent…”).

Code

docs/runtimes.md[257]

+> runtime](guides/user/running-agents-locally.md#choosing-the-runtime)

Relevance

●●● Strong

New anchor changes context; fixing contradictory linked claims is a clear correctness fix teams
accept.

PR-#6508

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The PR changes the link anchor in docs/runtimes.md to #choosing-the-runtime, but the surrounding
prose still promises a fleet-free minimal walkthrough. The linked section lives in
running-agents-locally.md, which instructs cloning fullsend-ai/agents into
/tmp/fullsend-agents and uses that directory in the runtime example, contradicting the “no fleet
repo required” claim.

docs/runtimes.md[254-259]
docs/guides/user/running-agents-locally.md[107-121]
docs/guides/user/running-agents-locally.md[205-218]

Agent prompt

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

### Issue description
`docs/runtimes.md`’s “Running pi locally?” callout was written for the now-deleted “minimal pi agent” walkthrough (fleet-free). This PR repoints the link to `#choosing-the-runtime`, but the callout still claims “no fleet repo required” and the link text still says “Run a minimal agent…”, which is no longer true.

### Issue Context
The local-run guide now instructs cloning `fullsend-ai/agents` and the `#choosing-the-runtime` section is positioned after/within those fleet-based examples.

### Fix Focus Areas
- docs/runtimes.md[254-259]
- docs/guides/user/running-agents-locally.md[107-121]
- docs/guides/user/running-agents-locally.md[205-218]

### Suggested change
In `docs/runtimes.md`, update the callout text to match the new target:
- Rename the link text from “Run a minimal agent…” to something like “Choosing the runtime” (or similar).
- Remove/adjust “no fleet repo required” (e.g., say it follows the standard local-run flow using the `fullsend-ai/agents` examples), or add an accurate note about prerequisites.

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

---

2. Runtime procedure not numbered ✓ Resolved 📜 Skill insight ✧ Quality

Description

The new Choosing the runtime section introduces procedural instructions as prose instead of a
numbered step list, which makes the procedure harder to follow consistently and violates the guide
formatting requirement.

Code

docs/guides/user/running-agents-locally.md[R207-210]

+Every example above runs on **Claude Code, the stable default**. The **pi**
+runtime ([pi](https://github.com/earendil-works/pi)) is an experimental,
+opt-in alternative — same commands, one extra flag:
+

Relevance

●●● Strong

Team has accepted converting procedural prose into numbered steps in similar docs guides before.

PR-#5778
PR-#6364

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062079 requires procedures in documentation guides to use numbered steps, not
prose paragraphs. The added Choosing the runtime subsection introduces a procedural instruction
(how to run with --runtime pi) in prose immediately before the command block, without converting
it into an ordered list of steps.

docs/guides/user/running-agents-locally.md[205-218]
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
The new procedural instructions in `Choosing the runtime` are written as prose paragraphs rather than numbered steps.

## Issue Context
Compliance requires procedural content in documentation guides to use numbered (ordered) lists rather than narrative paragraphs.

## Fix Focus Areas
- docs/guides/user/running-agents-locally.md[205-218]

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

---

Context sources

✅ Compliance rules (platform): 58 rules

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

Tip of the day

💡 Did you know, you can hide the parts of a finding you never read, like the evidence or the agent prompt

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Ended 7:43 PM UTC

Commit: 3a7db17 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:45 PM UTC · Completed 7:59 PM UTC

Commit: 452698e · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $6.50

[fullsend-ai-review]

Review

Findings

Low

• [anchor misdirection] docs/guides/user/running-agents-locally.md:206 — The HTML redirect anchors <a id="troubleshooting-pi-runtime"> and <a id="platform-notes-pi"> are co-located with <a id="run-a-minimal-agent-on-the-pi-runtime"> at the "Choosing the runtime" heading, but the actual troubleshooting content now lives in the ### pi runtime subsection under Troubleshooting (~line 481), and platform notes are inlined into the macOS/Linux sections. A visitor following a bookmarked #troubleshooting-pi-runtime link lands at the runtime-selection section instead of the troubleshooting content.
  Remediation: Move <a id="troubleshooting-pi-runtime"> to the ### pi runtime troubleshooting subsection and <a id="platform-notes-pi"> to one of the pi bullets in Platform notes. Keep <a id="run-a-minimal-agent-on-the-pi-runtime"> at "Choosing the runtime" since that section absorbed the old content.

• [heading-hierarchy-consistency] docs/guides/user/running-agents-locally.md:479 — The new ### pi runtime heading under ## Troubleshooting introduces an H3 sub-heading that no other troubleshooting entry uses — all six existing entries use a flat **bold title** format directly under the H2. This creates a structural asymmetry in the section and affects the site outline/TOC.
  Remediation: Either convert the pi troubleshooting entries to the existing flat **bold title** format (removing the H3), or convert all existing troubleshooting entries to grouped H3 sections.

---

Labels: PR modifies only documentation files under docs/

Previous run

Review

Findings

Low

• [code-organization] docs/guides/user/running-agents-locally.md — The new ### pi runtime heading under ## Troubleshooting introduces a sub-heading hierarchy that the existing troubleshooting entries do not follow. All current troubleshooting items use a flat **bold title** format directly under the H2. Adding an H3 for only the pi items creates a structural asymmetry — consider either promoting the existing bold-title entries to H3 sub-headings as well, or converting the pi troubleshooting items to the flat bold-title format.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:03 PM UTC · Completed 8:19 PM UTC

Commit: a0addd5 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $5.26

[rh-hemartin]

Sounds like we need a runtime section with a page for each runtime with details about it. I think we need to keep the "running agents locally" basic and not mentioning pi or it will blow up (basically that happened, as it is the reason this PR exists). So my idea would be that the "Choose runtime" just redirects to the main README.md page of the runtime section. What do you think?

[ralphbean]

@waynesun09++

[waynesun09]

/fs-fix-stop

[github-actions]

Fix agent disabled for this PR. Remove the fullsend-no-fix label or use /fs-fix to re-engage.

[waynesun09]

@rh-hemartin — agreed, and done as of d3bcc36: the guide is back to the basic Claude Code flow.

• "Choosing the runtime" is now a redirect: one --runtime pi command (kept deliberately, so a reader who wants pi has a hook to follow) plus links to Agent runtimes and to a new Pi › Running it locally section. Nothing else on the page mentions pi any more — the platform-note bullets, the pi troubleshooting subsection and the pi-debug.log aside are gone too. 691 → 562 lines; the three old anchors stay as aliases so permalinks keep working.
• docs/runtimes/pi.md gets "Running it locally": the verified plan-block output, what a local pi run needs (v0.37.0+ CLI and sandbox image, platforms, single-context review/retro, knobs, fail-closed hooks, --debug='*'), and the five pi troubleshooting entries. It opens with "complete the local-run guide first", and its links point at itself rather than back at the guide.
• docs/runtimes.md per-agent section: the existing fullsend agent set line grows into the set → list → plan-block flow (generic paths), matching feat(#6581): per-agent runtime, model and effort on agents: entries #6583, which this PR is stacked on.

Left for a follow-up so this PR stays a doc reshape: moving "Debugging network policies locally" (145 lines) to its own page and the status/remote flag tables into docs/cli/run.md, which doesn't document them today.

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 5:49 PM UTC · Ended 5:50 PM UTC

Commit: d3bcc36 · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 5:52 PM UTC · Ended 5:56 PM UTC

Commit: 642b458 · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 5:58 PM UTC · Ended 6:01 PM UTC

Commit: 3d6d938 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:03 PM UTC · Completed 6:23 PM UTC

Commit: cb50b8f · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $7.07

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 6:13 PM UTC · Completed 6:27 PM UTC

Commit: cb50b8f · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $5.33

[fullsend-ai-review]

Review skipped — this PR is already merged.

The /fs-review command only reviews open PRs/MRs.

_{Posted by fullsend post-review check}

[fullsend-ai-retro]

Retro: PR #6540 — docs(#6539): one local-run flow

Timeline

1. Issue docs: one local-run flow — replace the pi-specific section with --runtime on the standard examples #6539 opened (2026-08-23 19:14) — consolidate the local-run guide by replacing the 350-line pi-specific walkthrough with --runtime pi on the standard examples.
2. Triage agent (run 32660624863) ran successfully, labeled ready-to-code. Cost: $0.79.
3. Code agent (run 32661006970) ran for ~9 minutes and made all the correct edits — inserted the new "Choosing the runtime" subsection, deleted the old pi section, fixed cross-references, reduced the guide from 891 to 588 lines — but never committed the changes. The agent staged files with git add, then ran pre-commit run which failed due to sandbox network restrictions. It recovered by running individual lint hooks manually (which passed), but the session ended without ever executing git commit. The post-script correctly reported "No changed files in agent's commit(s)." Cost: $3.06 wasted.
4. Human takeover — waynesun09 manually authored PR docs(#6539): one local-run flow — pi is a --runtime flag on the standard examples #6540 with the same changes (2026-08-23 19:35).
5. Review agent ran twice (first review on commit 452698e at $6.50, second review on commit a0addd5 at $5.26). Both approved. The second review found 2 Low-severity mechanical findings: misplaced HTML alias anchors and a heading-hierarchy inconsistency.
6. Human reviewer rh-hemartin (2026-08-25 09:27) identified the key structural issue: the guide was becoming a dumping ground for runtime-specific content and should stay runtime-agnostic. This led to a significant reshape in commit d3bcc36 that moved pi details to docs/runtimes/pi.md, making both of the review agent's findings moot.
7. ralphbean approved (2026-08-25 17:00). waynesun09 pushed 5 rapid commits for the reshape, causing 5 cancelled review dispatches. PR merged 2026-08-25 18:11.

Observations

Code agent: correct edits, zero output. The code agent understood the task, explored the right files, made valid edits, and verified them with lint checks — then ended without committing. The root cause is that pre-commit run failed (sandbox network restriction), diverting the agent into manual lint validation, after which it never returned to the commit step. This is a $3.06 waste and forced a human takeover. See proposal below.

Review agent vs. human reviewer gap. The review agent caught valid but low-impact mechanical findings (anchor placement, heading style). The human reviewer caught the higher-value structural concern: the guide's scope was wrong. The PR existed because pi content had bloated the guide, yet the initial PR still inlined pi content. The human recognized this meta-problem; the agent did not. This gap aligns with existing issue #3639 (intent-coherence sub-agent should evaluate approach proportionality) — this PR provides concrete evidence for that proposal.

Cancelled review dispatches. Five review dispatches were cancelled on Aug 25 due to rapid human pushes. Already tracked by #4069 and #4960.

Total agent cost: ~$15.61 (triage $0.79 + code $3.06 + review $11.76). The code agent cost was entirely wasted. The review cost was reasonable for the diff scope but both reviews were superseded by the human-requested reshape.

Agents repo

Discovered from triage run logs: fullsend-ai/agents@main (commit 299f264ab55f).

Proposals filed

• Code agent loses edits when pre-commit hooks fail in sandbox (in fullsend-ai/agents)