docs: clarify that channels.release() is for niche use cases

[SimonWoolf]

Summary

• Reframes the channels.release() docs on both the Realtime and REST API pages to match the recent specification update.
• Adds an important admonition making clear that most applications should never call release — it exists for niche use cases (clients cycling through a continually changing set of channels).
• Warns that retaining and using a channel reference after release is undefined behaviour.
• Removes the singleton-client cautionary paragraphs, since they are subsumed by the stronger "don't use this unless you really need to" framing.

Test plan

• Visual check of the rendered pages in a review app for both /docs/api/realtime-sdk/channels#release and /docs/api/rest-sdk/channels#release.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 3ab9e42e-a0c1-40de-b2c0-ed6a5d7629f2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch release-warning

---

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 and usage tips.}

[m-hulbert]

I know it might seem pedantic, but I think the comma here is important 🙂

[SimonWoolf]

@m-hulbert note that the wording has now changed significantly since you reviewed it since I noticed that the ably-js behaviour differed from all other SDKs and ended up changing that in the interests of uniformity, so am now documenting the new behaviour, cf ably/specification#448 (comment)