Add Client and Orbit section to README

[Jarema]

Explains the split between the core nats.go client and the Orbit utility packages (https://github.com/synadia-io/orbit.go): what each is for, what goes where, and a small layering diagram. Mirrors the section added in nats.rs#1580.

Signed-off-by: Tomasz Pietrek tomasz@synadia.com

[synadia-claude-reviewer]

Claude finished @Jarema's task in 55s —— View job

---

PR Review

• Gather context and read PR changes
• Review README additions for accuracy and correctness
• Post final review

---

This is a documentation-only change (+68/-0 to README.md). No code, no logic, nothing executable — reviewed purely for content accuracy, clarity, and structure.

Overall: LGTM. The section is well-written, the layering diagram is accurate, and the table cleanly communicates the feature split. No bugs, security issues, or correctness problems found.

Minor observations (non-blocking):

1. "NATS contexts" row in the table — the meaning of "NATS contexts" as an Orbit feature may not be immediately obvious to readers unfamiliar with Orbit. A parenthetical like NATS contexts (request tracing) or similar might help, though it's a cosmetic concern.

2. ASCII diagram uses label position — the label uses sits one row above the ──────▶ arrow in the ASCII art, which is a common convention but could confuse readers at a quick glance. A label on the same line as the arrow (e.g., ──uses──▶) would be unambiguous, but this is truly a minor style point.

3. Section placement — placed between "Service API" and "New Authentication." This is logical since it gives context for what belongs in the repo vs. Orbit before readers encounter authentication, TLS, and reconnection details. No issue here.

The content mirrors what was added to nats.rs#1580, which provides consistent cross-repo documentation — that's the right call.

[coveralls]

coverage: 85.436% (+0.06%) from 85.372% — add-orbit-note into main

[piotrpio]

LGTM!