Add a queue-throughput quickstart for high-volume personal repos

[coygeek]

Summary

DeployBot's README explains the full durable delivery controller, but the fastest path for a personal repo with many independent PRs is not obvious. The docs would benefit from a focused "high-throughput personal repo" quickstart that starts with queue coordination before full production release tracking.

This is distinct from a full first-run onboarding skill: it is a concise operator recipe for the common problem "I create PRs faster than GitHub/manual merging can land them."

Problem

The README covers many advanced concepts:

• durable deploy intent;
• exact-head authorization;
• event worker setup;
• release admission;
• integration PRs;
• deployment workflow dispatch;
• health checks;
• native thread notifications;
• unpause and repair ownership.

That completeness is useful, but a first-time user trying to solve queue stalls may not know which minimum settings matter for throughput.

The key decisions are scattered:

• release_admission = "merged" is the low-latency mode.
• integration.mode = "overlap" is a reasonable starting point before all.
• queue.required_checks must be exact PR check display names.
• pipeline.ci_workflows must be workflow names.
• deployment workflows are optional for initial queue behavior but matter for merge-to-live metrics and full release receipts.

Proposed documentation

Add a short README section or doc page:

High-throughput personal repo quickstart

Suggested contents:

1. Who this is for:
   • personal repos;
   • many small independent PRs;
   • user controls merge policy;
   • goal is avoiding accidental global queue stalls.
2. Minimum pilot configuration:

[queue]
required_checks = ["<exact PR check name>"]
trusted_actors = ["@repository-owner"]
coordinator_actors = ["@repository-owner", "github-actions[bot]"]

[pipeline]
release_admission = "merged"
batch_settle_seconds = 0
promotion_workers = 4

[integration]
mode = "overlap"
max_batch_size = 3

3. A warning that required_checks are PR check display names, not workflow names.
4. A pilot procedure:
   • create 3 independent trivial PRs;
   • create 2 overlapping PRs;
   • prove independent PRs merge while overlaps route to integration/repair.
5. A "do not use this if" section:
   • CI takes longer than PR production rate;
   • most PRs touch the same files;
   • every merge must be production-verified before the next merge;
   • deployment workflow identity is not configured yet but live receipts are expected.

Impact

This would help users evaluate DeployBot for the high-throughput queue problem without requiring them to absorb the entire release-controller model first.

It would also reduce misconfiguration risk by making the check-name/workflow-name split explicit in the first recipe users copy.

Acceptance criteria

• README or docs include a high-throughput personal-repo quickstart.
• The quickstart recommends release_admission = "merged" for independent-work throughput and explains the safety tradeoff.
• The quickstart recommends integration.mode = "overlap" as the first high-throughput integration setting.
• The quickstart explicitly distinguishes required check display names from workflow names.
• The quickstart includes a small pilot plan with independent and overlapping PRs.
• The quickstart states when DeployBot will not improve throughput.

Verification

• Documentation tests pass.
• Any docs-reference tests that require command/config coverage remain green.