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

[waynesun09]

Summary

Replaces the 350-line pi-specific walkthrough in docs/guides/user/running-agents-locally.md with a single local-run flow: the existing fleet examples plus a "Choosing the runtime" subsection (--runtime pi on the same commands, override precedence for both runtimes, Gemini-on-Vertex by model name, compact pi notes) and one pi bullet per OS in Platform notes. docs/runtimes.md now points at the new anchor. 890 → 604 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.

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" (stable default vs experimental framing, one extra flag, verified output, override table, pi notes incl. build-from-main until a release carries pi)
• Fold pi platform notes into "Platform notes" (one bullet each for macOS/Linux)
• Re-point docs/runtimes.md's local-run link 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://b804ae96-site.fullsend-ai.workers.dev

Commit: a0addd5950c25a9b9ed561cbd57359bd5c05edae

[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 turn these tips off under Display preferences

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

[fullsend-ai-review]

[low] anchor misdirection

The HTML redirect anchors troubleshooting-pi-runtime and platform-notes-pi are co-located at the Choosing the runtime heading, but the actual troubleshooting content lives in the ### pi runtime subsection under Troubleshooting, and platform notes are inlined into macOS/Linux sections. A visitor following a bookmarked #troubleshooting-pi-runtime link lands at the runtime-selection section instead of the troubleshooting content.

Suggested fix: Move the troubleshooting-pi-runtime anchor to the ### pi runtime troubleshooting subsection and platform-notes-pi to one of the pi bullets in Platform notes.

[fullsend-ai-review]

[low] heading-hierarchy-consistency

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.

Suggested fix: Either convert the pi troubleshooting entries to the existing flat bold title format, or convert all existing troubleshooting entries to grouped H3 sections.

[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?