docs: restore the guard's own section, and tighten two pages

[sunib]

A docs pass, and it turned up a real structural bug rather than just prose.

The bug: I split the guard from its own description

docs/saving.md opens with ValidateMergePatch and its example. The list beginning "The guard rejects:" (redacted paths, managedFields, status under krm-spec/v1, malformed patches) describes that guard.

When I added the 204 and adoptSaved sections in #10, I inserted them between the guard and its own description. So the page read:

ValidateMergePatch + example
## Answer 204 and let the watch echo it
## If you must answer with the object      <- gateway.Project example
The guard rejects: ...                      <- looks like it describes Project. It does not.

A reader arriving at those bullets would reasonably conclude that gateway.Project rejects redacted paths and malformed merge patches. It does neither. The rules are now back with the guard, under What the guard rejects, and the 204 and adoptSaved sections follow it.

The prose

• Em-dashes gone from saving.md (the last two in docs/).
• Dropped "This is the recommended shape, and it is the one to reach for unless you have a specific reason not to" — the heading already says it.
• docs/why-a-gateway.md: four paragraphs that took a run-up to every point ("and the reason is a real trade", "There is a way to take the fan-out without giving up the boundary") now just make them. No content lost; the SharedBackend security trade and the SSARAuthorizer escape hatch both stay, because that is the part a reader can get wrong.

Docs only.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@sunib, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 24 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2a7764eb-3216-49b2-824e-40f946901612

📥 Commits

Reviewing files that changed from the base of the PR and between a16d803 and 7c2d2b1.

📒 Files selected for processing (2)

• docs/saving.md
• docs/why-a-gateway.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/tighten-saving-and-gateway

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}