docs(submitqueue): provider example configuration and landing runbook

[behinddwalls]

Summary

Why?

Every piece needed to land a change against a live provider was in place, but nothing said how to point the stack at one — and the pieces that vary by provider were scattered across environment variables and two config files with no worked example.

What?

Which provider a deployment targets becomes a bind-mounted directory: make local-provider-start PROVIDER=github mounts example/provider/<name>/ into the orchestrator and Runway. Because the choice is a mount rather than a build input, switching providers needs no rebuild, and adding one is a directory plus the extension implementations behind it — no compose, Makefile, or image change.

The compose overlay names no provider at all. It requires the token rather than defaulting it: falling back to the fake integrations would let the stack report a change as landed without having gone near the provider, which is a far worse failure than not starting.

example/provider/README.md carries the complete touchpoint list for adding a provider, and — more usefully — what is not on it: the merger's apply and push paths, the head-branch update, the pipeline, the wire contract, and the hermetic git E2E are all provider-independent.

The runbook covers the two first-run traps that are easy to misdiagnose. Branch protection on the target rejects the merger's push like anyone else's. And a change that lands but stays open is either a fork (expected and permanent — its head branch lives in another repository) or head-branch protection blocking the update; Runway's logs distinguish them.

Test Plan

✅ docker compose -f docker-compose.yml -f docker-compose.provider.yml config validates, and fails fast with required variable GITHUB_TOKEN is missing a value when the token is unset.

✅ make help lists land, local-provider-start, and local-provider-stop.

Landing against a live provider is manual by nature — it needs a scratch repository and a token, so it is not automated in CI. The runbook is the procedure.

Stack

1. feat(runway): move a change's head branch to the commit it landed as #542
2. feat(runway): resolve merge targets per queue and provision their checkouts #544
3. feat(orchestrator): build extension profiles from configuration #545
4. test(e2e): hermetic end-to-end coverage of a real git merge #546
5. feat(gateway): land and status subcommands for the client #547
6. @ docs(submitqueue): provider example configuration and landing runbook #548