Skip to content

docs: split runtimes.md into a user page and an implementer page #6574

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
waynesun09 merged 4 commits into from
Aug 25, 2026
Merged

docs: split runtimes.md into a user page and an implementer page #6574

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f63b61a
docs: split runtimes.md into a user page and an implementer page
waynesun09 Aug 25, 2026
f7ea3ae
docs: give pi its own page and a Runtimes sidebar section
waynesun09 Aug 25, 2026
4b44fa0
docs: give Claude Code a runtime page too, and fix the pi heading out…
waynesun09 Aug 25, 2026
cfc39d4
docs: title the runtime pages by their name, not by an action
waynesun09 Aug 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ Detailed guidance lives in `docs/contributing/` and topic-specific guides under

| File | When to read |
|------|-------------|
| [Runtime Implementation](docs/contributing/runtime-implementation.md) | Adding or changing a `runtime.Runtime` backend — covers the security feature matrix every runtime must fill in, the runtime interfaces, the sandbox hook contract and wire protocol, and the sandbox workspace layout |
| [Go Code](docs/contributing/go-code.md) | Changing Go code under `cmd/` or `internal/` — covers mint sync, coverage, vet, e2e tests, concurrency testing, suite-timeout policy, WASM binary size constraints, and preferring `go run` for the CLI |
| [Mintcore Architecture](docs/contributing/mintcore.md) | Changing `internal/mintcore/`, `cmd/mint-wasm/`, `cmd/mint/`, or `internal/mint/` — covers platform accessors, load-site construction, and WASM-safe wiring |
| [Behaviour Testing](docs/guides/dev/behaviour-testing.md) | Modifying behaviour test repo provisioning, fork handling, or workflow dispatch — covers forge API constraints (`auto_init`, fork name derivation, Actions readiness, CI timeout budgeting) |
Expand Down
7 changes: 6 additions & 1 deletion docs/.vitepress/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,12 @@ export default defineConfig({
},
{
text: "Runtimes",
collapsed: true,
link: "/runtimes",
items: [
{ text: "Claude Code", link: "/runtimes/claude" },
{ text: "Pi", link: "/runtimes/pi" },
],
},
{
text: "Agents",
Expand Down Expand Up @@ -335,7 +340,7 @@ export default defineConfig({
provider: "local",
options: {
scopes: [
{ label: "Guides", prefixes: ["/docs/guides/", "/docs/agents/", "/docs/cli/"] },
{ label: "Guides", prefixes: ["/docs/guides/", "/docs/agents/", "/docs/cli/", "/docs/runtimes"] },
{
label: "Design Docs",
prefixes: ["/docs/problems/", "/docs/ADRs/", "/docs/normative/", "/docs/spikes/"],
Expand Down
6 changes: 3 additions & 3 deletions docs/ADRs/0090-runtime-neutral-sandbox-hooks-contract.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ feature:
PreToolUse/PostToolUse phases with Claude tool names as the canonical
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).

@qodo-code-review qodo-code-review Bot Aug 25, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remediation recommended

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

- The bootstrap extension is `runtime.SandboxHooksBootstrap` (carrying
`security.SandboxHookConfig`). Every runtime's `Bootstrap` SHOULD honour it
by installing the scripts (`installHookScripts`, any directory) and wiring
Expand Down Expand Up @@ -95,7 +95,7 @@ feature:
> PostToolUse contract v2 — scripts read `tool_response` (fallback
> `tool_result`), replace via `hookSpecificOutput.updatedToolOutput`, and
> enforce unicode → canary → suppress → redact in `posttool_chain.py`. See
> [runtimes.md](../runtimes.md#sandbox-hook-contract).
> [runtimes.md](../contributing/runtime-implementation.md#sandbox-hook-contract).

> **Done ([#608](https://github.com/fullsend-ai/fullsend/issues/608)):**
> The canonical Claude tool-name vocabulary is recorded once in
Expand All @@ -112,4 +112,4 @@ feature:
> as a forbidden tool (`tool_blocked`, `critical`). MCP names are matched
> verbatim. The pi adapter's maps are held to canonical-or-legacy names
> (`ls` → `LS`), a deliberate relaxation of "canonical only". See
> [runtimes.md](../runtimes.md#sandbox-hook-contract).
> [runtimes.md](../contributing/runtime-implementation.md#sandbox-hook-contract).
255 changes: 255 additions & 0 deletions docs/contributing/runtime-implementation.md
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/guides/getting-started/choosing-a-runtime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Fullsend supports multiple agent runtimes. A runtime is the program that runs in

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).

@qodo-code-review qodo-code-review Bot Aug 25, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

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


## Where to see what ran

Expand Down
2 changes: 1 addition & 1 deletion docs/guides/user/running-agents-locally.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,7 +282,7 @@ config-registered agent to a local harness directory.

> For background on the pi runtime, its security posture, and known
> constraints, see [Agent runtimes — Pi-specific known
> constraints](../../runtimes.md#pi-specific-known-constraints-6464).
> constraints](../../runtimes/pi.md).

### Prerequisites (pi-specific)

Expand Down
Loading
Loading