docs(proxy): tiered reference, basics page, 3.0.0 release mechanics (#93 workstream F)

[mhenrixon]

Summary

Workstream F of the v3.0.0 release gate (#93) — docs tiering, release mechanics, bookkeeping. The last PR before G (the release itself, waiting on kamal-proxy:v1.0.0.1).

• F1 — progressive disclosure. docs/proxy.yml reorganized into six titled tiers — 1 Essentials (~10 keys), 2 Traffic & routing, 3 Security & access, 4 Performance & observability, 5 Fleet, 6 Proxy container (run) — with a per-key layering table (edge / per-app / both) at the top and the "run.options are docker run options, not kamal-proxy flags" one-liner next to the key it disambiguates. docs/proxy-basics.md mirrors the Essentials tier as a standalone ten-key page with a "when you need more" map into the tiers. Reordering is free — validation looks keys up by name, and the suite (which drives validation through this file) proves it.
• F2 — release mechanics. bin/release-dash accepts the three-segment fork grammar (3.0.0 → tag dash-v3.0.0; the legacy four-segment form stays valid for the pre-3.0 patch line). .claude/rules/upstream-sync.md (the version.rb conflict rule becomes "keep ours — the fork declares its own major"), .claude/rules/git-workflow.md and CLAUDE.md stop teaching the abandoned grammar.
• F3 — release notes drafted at docs/release-notes/3.0.0.md with every required callout by name: per-role+destination prune retention, exact accessory tag matching, the R6 readiness warnings, the renames/cuts table, and the one-time digest-convergence fleet reboot on the first post-upgrade deploy.
• F4 — follow-ups filed: kamal doctor: report whether the running proxy was booted with a docker socket #98 (kamal doctor reports whether the running proxy has the docker socket) and kamal proxy cache CLI: stats and purge #99 (kamal proxy cache stats/purge CLI). Weighted-canary is already tracked (kamal#941 / ROADMAP R5) — not duplicated.

Refs #93 (workstream F — G is the release itself)

Test plan

• Suite green after the reorder — the docs file is the validation schema, so every config test re-proves it parses and validates identically
• bundle exec rubocop --parallel clean
• Release-notes claims cross-checked against the merged PRs (fix(prune): scope container pruning to a role and destination #68 prune, fix(config): resolve accessory tags through the roles that own the hosts #67 accessory tags, R6 warnings, feat(proxy): explicit loadbalancer layering contract + LB run plumbing (#93 workstream B) #94–feat(proxy): port_holder handoff, JSON-verified reboots, LB drift detection (#93 workstream E) #97)
• CI

Deviations & judgment calls

• In-path fix: scope_cookie_paths was still in the docs schema after D4 (validating while emitting nothing — the same miss class as the leases caught in feat(proxy): port_holder handoff, JSON-verified reboots, LB drift detection (#93 workstream E) #97). Cut during the reorder that touched every block anyway.
• The basics page lives at docs/proxy-basics.md (repo docs dir, plain markdown) — not a second schema file, per the "no docs-file split requiring loader changes" out-of-scope rule. The loader still reads exactly docs/<key>.yml.
• Section 4 is titled "Performance & observability" — logging and exclude_metrics_paths had no home in the issue's five names, and a seventh section for two keys wasn't worth it.
• Release notes qualify the zero-downtime claim: the fleet reboot is zero-downtime where port_holder: true is set — it's still opt-in (the open default question from feat(proxy): port_holder handoff, JSON-verified reboots, LB drift detection (#93 workstream E) #97). If you flip the default before G, the notes need one sentence changed.
• bin/release-dash keeps accepting the four-segment grammar rather than hard-switching — a 2.12.0.x patch release remains possible without reverting the script.
• Release notes are a repo file, not a GitHub release draft — G's release step can paste from it; drafting an actual GH release for an untagged version seemed premature.