docs: make the operational settings discoverable and the handbook true

[bgard68]

Two gaps left by the security and operability work, both the same kind: the behaviour changed and nothing outside the code said so.

The settings were invisible

Throttling budgets, the reservation sweep window, and TrustForwardedFor existed only as C# defaults. Nobody deploying this could discover they were tunable at all — which made the load-bearing one a trap: the app warns when TrustForwardedFor is wrong for its traffic, but there was nothing in configuration to set right.

appsettings.json now carries both sections with the values written out.

Writing them down costs a second source of truth, so ShippedConfigurationTests guards it — the file and the code defaults are asserted equal in both directions. A fourth test pins that the sweep window stays longer than the interval that looks for it; a window shorter than its own sweep leaves orders expired but unreleased for most of their life. Change one side without the other and the build fails rather than the file quietly starting to lie.

The handbook didn't know what the app does

Zero mentions of health/ready, correlation ids, TrustForwardedFor, or the sweep. On a project whose handbook is a large part of what it's for, that drift undoes the work — a reader reads the handbook, not the diff.

Doc	Added
04 · Configuration	Throttling built around the setting that can cause an outage: what each direction of getting it wrong does, which deployments need which value, and that the warning it logs is not advisory. Plus the sweep, with ExpireAfterMinutes explained as a trade, not a knob
09 · Runbook	Both probes with a table of which to point at what — and why merging them costs ~180 CU-hrs against a 100 CU-hr budget. Plus tracing a customer's report through a correlation id
08 · Bugs & lessons	Six new rows, including the three defects the tooling found rather than the author, and four new lessons
README + 03 · Setup	Both endpoints listed; the troubleshooting note now says which one keeps checking

The four new lessons: let the row arbitrate, not the handler · write what you mean, not the whole row · read the reasoning before changing the code · the gates catch what the author cannot.

Drift, measured

Term	Before	After
health/ready	0	4
correlation	0	2
TrustForwardedFor	0	1
reservation sweep	0	6
rate limit	2	4

Verification

• 518 backend tests pass locally against real PostgreSQL 16
• Build clean under -warnaserror; dotnet format --verify-no-changes clean

---

Generated by Claude Code