docs: split runtimes.md into a user page and an implementer page - #6574
Conversation
runtimes.md served two audiences at once and served neither well: 8,588 words in which the most user-relevant content -- how to select a runtime and a model -- sat at line 314 of 376, behind the security feature matrix, the runtime interface contract, the sandbox hook wire protocol and the workspace layout. Several single bullets ran past 3,900 characters. The user page is now 1,690 words and ordered the way someone actually arrives: what a runtime is, choosing between claude and pi, selecting one, models, running pi, troubleshooting. Selection moved to the top. A troubleshooting section is new, covering the failures that are hard to diagnose from their symptoms -- a silently dropped extension, "No API key found", a 403 from the wrong project, and a model misreporting which model it is. Contributor content moved verbatim to docs/contributing/runtime-implementation.md rather than being deleted: the security matrix, fail modes, interface contract, hook contract and wire protocol, workspace layout, agent rule layering, dummy ops, and the pi verification provenance -- which version of pi's source each claim was checked against, and what to re-check on a bump. Inbound anchors from ADR 0090, the local-run guide and the choosing-a-runtime guide are repointed; make lint-md-links passes with zero errors. Two diagrams are new: how the runtime/model override precedence resolves, and how each Vertex provider resolves its own GCP project from one set of ADC credentials -- the second documents behaviour that was not written down anywhere, and explains why an explicitly-set XAI_VERTEX_PROJECT_ID is left alone. Assisted-by: Claude (docs) Signed-off-by: Wayne Sun <gsun@redhat.com>
Site previewPreview: https://6a984b04-site.fullsend-ai.workers.dev Commit: |
PR Summary by QodoSplit runtimes docs into user guide and runtime implementer guide
AI Description
Diagram
High-Level Assessment
Files changed (6)
|
|
🤖 Review · Commit: |
The single runtimes page was still doing too much: a reader on Claude Code had to scroll past pi's provider table, its behaviour differences and its troubleshooting to reach the config-key mapping, and a reader on pi had no page to land on. Split by audience again, one level down: - /runtimes (923 words) -- what a runtime is, choosing between claude and pi, selecting one, where the selection appears, harness config keys. - /runtimes/pi (927 words) -- models and providers including the per-provider GCP project behaviour, the at-a-glance table, behaviour differences and troubleshooting. Sidebar "Runtimes" becomes a collapsible section with the pi page under it, matching the Agents section below it. /docs/runtimes is added to the Guides search scope: docs/doc-site.md notes that a docs/ subfolder missing from every scope becomes unreachable whenever a scope pill is active, which a new subfolder would otherwise trip. make lint-md-links passes with zero errors; the inbound anchors from the local-run guide and the implementer page are repointed at the pi page. Assisted-by: Claude (docs) Signed-off-by: Wayne Sun <gsun@redhat.com>
Code Review by Qodo
1. Guide missing prerequisites section
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| 1. **Next step — Configuring GitHub.** `fullsend github setup <owner/repo>` asks which runtime to use when run from a terminal; press Enter to keep `claude`. Passing `--runtime` skips the prompt. The setup PR it opens records the choice in `.fullsend/config.yaml` and describes how to change it. Nothing runs on this page — continue with [Configuring GitHub](configuring-github.md). | ||
| 2. **Later — changing it.** Edit `runtime:` in the repo's `.fullsend/config.yaml` (the setup PR shows the key), or re-run `fullsend github setup <owner/repo> --runtime <claude|pi>`. Fleets managed through `repos.yaml` set `defaults.runtime` (or a per-entry `runtime`) — `fullsend repos set-default defaults.runtime pi` — and run `fullsend repos install`; see [fullsend repos](../../cli/repos.md). | ||
| 3. **Per run — trying without changing the repo.** `fullsend run --runtime pi --model google-vertex/gemini-2.5-flash`, or the `FULLSEND_RUNTIME` / `FULLSEND_MODEL` / `FULLSEND_EFFORT` environment variables (flag beats environment beats config). In CI the same names work as repository variables. Reference: [fullsend run](../../cli/run.md) and [Runtimes — selecting and overriding](../../runtimes.md#selecting-and-overriding). | ||
| 3. **Per run — trying without changing the repo.** `fullsend run --runtime pi --model google-vertex/gemini-2.5-flash`, or the `FULLSEND_RUNTIME` / `FULLSEND_MODEL` / `FULLSEND_EFFORT` environment variables (flag beats environment beats config). In CI the same names work as repository variables. Reference: [fullsend run](../../cli/run.md) and [Runtimes — selecting and overriding](../../runtimes.md#selecting-a-runtime-and-model). |
There was a problem hiding this comment.
2. Guide missing prerequisites section 📜 Skill insight ✧ Quality
docs/guides/getting-started/choosing-a-runtime.md contains procedural numbered steps but does not include a clearly labeled Prerequisites section before those steps. Readers may start the procedure without required setup/context.
Agent Prompt
## Issue description
This guide includes a numbered procedure but lacks a clearly labeled `## Prerequisites` section before the steps.
## Issue Context
The procedure starts under `## When and how the runtime is selected` with steps, but there is no prerequisites section earlier in the document.
## Fix Focus Areas
- docs/guides/getting-started/choosing-a-runtime.md[1-25]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| | **`claude`** | Production agent runs (Claude Code) | Default | | ||
| | **`pi`** | Second runtime, opt-in per org/repo — [more models, incl. Grok and Gemini](#models) | Supported for `triage`, `prioritize`, `code`, `fix` | | ||
| | `dummy` | Behaviour tests — scripted ops, no inference | Internal | | ||
| | `opencode` | Not yet functional | Stub | |
There was a problem hiding this comment.
4. Opencode listed as runtime 🐞 Bug ≡ Correctness
docs/runtimes.md lists opencode as a runtime, but the CLI/config only allow claude, pi, and dummy, so users who try --runtime opencode or runtime: opencode will fail validation.
Agent Prompt
### Issue description
`docs/runtimes.md` currently lists `opencode` in the runtime table, implying it is a recognized/runtime choice. In code, `opencode` is intentionally excluded from `config.ValidRuntimes()` and therefore rejected for flags/env/config.
### Issue Context
This is user-facing documentation and will cause immediate confusion because the first attempt to set `runtime: opencode` (or `--runtime opencode`) fails at validation time.
### Fix Focus Areas
- docs/runtimes.md[7-13]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| vocabulary. Claude's `GenerateClaudeSettings` is rendered from `HookPlan` | ||
| so the two cannot diverge. The stdin/stdout/exit-code wire protocol is | ||
| documented in [runtimes.md](../runtimes.md#sandbox-hook-contract). | ||
| documented in [runtimes.md](../contributing/runtime-implementation.md#sandbox-hook-contract). |
There was a problem hiding this comment.
5. Adr matrix location outdated 🐞 Bug ≡ Correctness
ADR 0090 still tells readers to record runtime hook absence in the docs/runtimes.md security matrix, but this PR moved the security matrix into docs/contributing/runtime-implementation.md, leaving the ADR guidance incorrect.
Agent Prompt
### Issue description
ADR 0090 references the security feature matrix as living in `docs/runtimes.md`, but the matrix has been moved to the new implementer doc. This makes the ADR’s “where to record it” guidance wrong.
### Issue Context
This PR updates ADR 0090 links to point at the new sandbox hook contract section, which is consistent with the move, but the ADR still points at the old matrix location.
### Fix Focus Areas
- docs/ADRs/0090-runtime-neutral-sandbox-hooks-contract.md[54-67]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| X["exit 97\npi never starts unhooked\n(Run refuses earlier, exit -1,\nif the manifest has no hook plan)"] | ||
| E["source .env\nunset ANTHROPIC_*\npin GOOGLE_CLOUD_PROJECT"] | ||
| P["pi --print --mode json --no-approve\n--no-extensions [-e vertex, on Vertex] -e hooks\n--tools … --model … #lt;/dev/null"] | ||
| S["parsePiStream\nexactly one ResultEvent\nexit 0 + stream error ⇒ run fails"] |
There was a problem hiding this comment.
6. Broken mermaid escape sequence 🐞 Bug ≡ Correctness
The pi invocation mermaid diagram in docs/contributing/runtime-implementation.md contains #lt;/dev/null instead of a correct escape/markup for </dev/null, so it will render incorrectly and contradicts the correct text description later in the same section.
Agent Prompt
### Issue description
A mermaid node label includes the literal string `#lt;/dev/null`, which appears to be a mistaken HTML escape for `</dev/null`.
### Issue Context
Later text in the same section uses the correct `</dev/null` form, so the diagram is inconsistent and likely a typo.
### Fix Focus Areas
- docs/contributing/runtime-implementation.md[219-226]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
|
🤖 Review · Commit: |
…line A Runtimes section with a single child read as unfinished -- every other sidebar section here has several -- and made the default runtime look second-class next to the opt-in one. Claude Code now has a sibling page rather than a stub. The content was real and scattered: model aliases and FULLSEND_FALLBACK_MODELS (stranded in the overview's selection section), --agent replacing the system prompt where pi appends, native sub-agents, the CLAUDE.md bridge, the failed-tool-call sanitizing limit, and the repo .claude/settings.json auto-load caveat -- several of which only existed on the implementer page. The comparison stays on the overview; the runtime pages hold operational detail, so the fallback-chain mechanics live in exactly one place. Also fixes a nesting bug from the previous commit: renaming "Running pi" to "At a glance" silently demoted "Behaviour differences worth knowing" and "Not yet exercised" to children of the table above them, which is the wrong outline and renders wrongly in the page TOC. Both promoted back to H2. Assisted-by: Claude (docs) Signed-off-by: Wayne Sun <gsun@redhat.com>
|
🤖 Review · Commit: |
"Running pi" / "Running Claude Code" put a verb in front of every sidebar entry, which reads oddly in a list of nouns next to Agents and Getting Started, and buries the thing the reader is scanning for. The pages are now "Pi" and "Claude Code" -- capitalised as titles, while prose keeps the project's own lowercase "pi". Link text across the overview, the implementer page and between the two runtime pages follows. Signed-off-by: Wayne Sun <gsun@redhat.com>
cfc39d4
into
agent/6571-add-xai-vertex-provider
|
For the record: this was not merged to The docs now ship with #6572, which is where they belong — the runtime pages describe the xai-vertex provider that PR adds. |
|
🤖 Finished Review · ✅ Success · Started 12:57 AM UTC · Completed 1:15 AM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $7.68 |
|
Review skipped — this PR is already merged. The Posted by fullsend pre-review check |
|
🤖 Finished Retro · ✅ Success · Started 12:57 AM UTC · Completed 1:08 AM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $4.20 |
Retro: PR #6574 — docs: split runtimes.md into a user page and an implementer pageWhat happenedPR #6574 was a human-authored docs restructuring by waynesun09 that split the monolithic Four commits were pushed over 24 minutes (00:31–00:55 UTC). Three review agent runs (32794652838, 32794934170, 32795213967) were dispatched and all three were cancelled by GitHub Actions' Net result: zero completed fullsend review agent runs. The only automated review came from Qodo, which posted 6 findings including two real bugs that shipped: a broken mermaid escape sequence ( AssessmentThe workflow went reasonably well given its nature — a docs-only stacked PR by a repo member, targeting a non-main branch. The two bugs that shipped are minor rendering issues in contributor-facing documentation. The review agent's cancellation was caused by the standard Evidence for existing issues
No new proposalsAll identified improvements are already tracked in existing open issues. No novel proposals are warranted. |
|
Review skipped — this PR is already merged. The Posted by fullsend post-review check |
…i, re-point the Pi page The Pi runtime page (#6574) replaced the runtimes.md callout this PR rewrote, so its two links now target #choosing-the-runtime. The override table gains the per-agent agents: entry column and the precedence from #6583, with a pointer to the durable per-agent section. v0.37.0 is the first release that carries the pi runtime, so the build-from-main bullet and the guides-index caveat are gone. Assisted-by: Claude Signed-off-by: Wayne Sun <ericbreeze@gmail.com>
1 participant
Stacked on #6572 — review that first; this branch targets its head, not
main.docs/runtimes.mdserved two audiences at once. At 8,588 words, the most user-relevant content — how to select a runtime and a model — sat at line 314 of 376, behind the security feature matrix, the runtime interface contract, the sandbox hook wire protocol and the workspace layout. Several single bullets ran past 3,900 characters.docs/runtimes.mddocs/contributing/runtime-implementation.mdThe user page is reordered the way someone arrives: what a runtime is → choosing between claude and pi → selecting one → models → running pi → troubleshooting. Troubleshooting is new and covers failures that are hard to diagnose from their symptoms — a silently dropped extension,
No API key found, a 403 from the wrong project, and a model misreporting which model it is.The contributor page takes the moved content verbatim, including the pi verification provenance: which version of pi's source each claim was checked against and what to re-check on a bump. Nothing was deleted.
Two diagrams are new: how runtime/model override precedence resolves, and how each Vertex provider resolves its own GCP project from one set of ADC credentials. The second documents behaviour that was not written down anywhere and explains why an explicitly-set
XAI_VERTEX_PROJECT_IDis left alone.Test plan
make lint-md-links— 0 errors across 1,825 links, fragments included#sandbox-hook-contract), the local-run guide (#pi-specific-known-constraints-6464) and the choosing-a-runtime guide (#selecting-and-overriding) all resolved to moved sectionsAGENTS.md's contributing tableFULLSEND_*env var names, thevalidModelNameregex and all 4metrics.jsonfields exist as documented