runner: operator docs and the example campaign config

[marwen-abid]

This PR adds the operator documentation and the example campaign config. The code landed in the layers below; this layer says how to run it. It completes the stack, and the tree then equals the head of #16.

What is in this PR

• runner/README.md — the runner's reference. It documents the four subcommands and their flags, the TOML config keys with types and defaults, the four dataset kinds, the .cfg to .toml migration table, the $BENCH_ROOT layout, and the resume rules. Two sections are contracts. Compatibility floor: the runner needs a stellar-rpc ref whose bench subcommands write invocation.json, which is stellar-rpc#907 (6f35679f) or a descendant. Campaign bundle layout: the bundle tree, with the owner of every manifest — metadata.json, plan.json, and leg.json come from this repo; invocation.json and the CSVs come from stellar-rpc.
• README.md — a new "Run a campaign" section takes the operator from bootstrap.sh to a published bundle. The ingest section documents make ingest and scripts/ingest.sh with its three modes, and the ingest.yml section documents the workflow's three inputs. The repo tree gains runner/, scripts/, and the new workflows.
• runner/example-campaign.toml — the annotated config operators copy. Every key appears with its default and the reason for it.

Review focus

• The bundle layout section against SCHEMA.md § Inputs and the writers in internal/bundle. The two sides of this contract must agree on field names and on who writes each file.
• The config reference table against internal/config: types, defaults, and which keys are required.
• The migration table: every .cfg key must map to a .toml key. The fixture dataset is the one entry whose shape changes, because its old location field held the ledger count.
• The compatibility floor commit. It names a specific stellar-rpc commit as the minimum.

Verification

This layer changes documentation only, so no test gates it. Merge it and check that the resulting tree equals the head of #16:

git diff <merge-commit> campaign-runner --stat   # expect no output

---

Stack: part 8 of 8 · base runner-07-cli-e2e · replaces a slice of #16

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-02 01:05 UTC

[Copilot]

🟡 Not ready to approve

Several doc details are inconsistent with the repo’s actual conventions (notably the results vs benchmarks GCS prefix and <sha> vs <sha8> placeholders), which could mislead operators.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

Adds operator-facing documentation and a copyable example config for the campaign runner, plus updates the top-level README to describe the full “run → publish → ingest” workflow.

Changes:

• Added runner/README.md as the runner operator reference (CLI/config/bundle contract/resume/migration).
• Added runner/example-campaign.toml as an annotated config template.
• Updated README.md with “Run a campaign” + “Add a run”/ingest workflow documentation and refreshed repo layout.

File summaries

File	Description
runner/README.md	New runner operator reference (CLI, config reference, resume rules, and bundle layout contract).
runner/example-campaign.toml	New annotated example campaign TOML operators can copy and edit.
README.md	New end-to-end operator flow for running/publishing campaigns and ingesting bundles into committed runs.

Review details

Suppressed comments (2)

README.md:90

• The publish example points at gs://rpc-full-history/benchmarks, but the ingest workflow and run provenance examples use gs://rpc-full-history/results/<run_id>. Consider switching this example to the results prefix (or explicitly calling out the two locations if both are valid).

go run ./cmd/campaign publish /mnt/nvme/bench/results/<run-id> \
  gs://rpc-full-history/benchmarks --force

**runner/example-campaign.toml:34**
* The versioned binary name uses the first 8 hex characters of the commit SHA (see runner internal plan/path derivation). Documenting it as `<sha8>` would avoid implying a full SHA in filenames.

branches and tags. Default: feature/full-history, the branch this whole suite

benchmarks. The ref is built into a versioned binary

($BENCH_ROOT/bin/stellar-rpc-).

#ref = "feature/full-history"

- **Files reviewed:** 3/3 changed files
- **Comments generated:** 8
- **Review effort level:** Lite
</details>

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[marwen-abid]

@claude[agent] review

[Claude]

@claude[agent] review

Reviewed the three docs against the code. The config reference table matches internal/config/config.go exactly (DefaultRepo, DefaultRef = feature/full-history, DefaultCloseInterval = "0", runs=5, cold_iters=100, hot_iters=200, workers=1, query_concurrency=[1,4,16]), and the fixture ledgers rule (0 or >= 10000) matches minFixtureLedgers and its tests. All earlier review threads are resolved by d8be47a (publish prefix now results/, fixture chunk wording, explicit "5.5 hours"). No further changes needed — this layer is documentation-only.