docs: Build-by-use-case guides

[irinanazarova]

Summary

Adds the Build by use case guides, split out of the repositioning PR (#59, now merged) per Vladimir's review feedback. These pages start from what the reader is building, show the architecture, and link into the front-door and capability pages that landed in #59.

Pages

• AI response streaming — ordered token streaming with mid-response catch-up
• Live dashboards — high fan-out market data / metrics feeds
• GPS tracking & dispatch — device location streams with online-driver presence
• Telehealth & collaboration — presence + reliable messaging for sessions
• Index ("Build by use case"), plus the sidebar group and the landing-page card

Verification

Every scenario was exercised against a running anycable-go: ordered token streaming and history catch-up (AI), fan-out to multiple subscribers (dashboards), presence join/leave/info via the real @anycable/core SDK (GPS/telehealth). Each --public dev command, signed-streams/JWT production note, and publish example is self-contained and copy-paste runnable; the JS clients pass an explicit ws://localhost:8080/cable for the standalone Node/Python persona. forspell/markdownlint clean, build passes, and every internal link resolves against the merged tree.

Notes

• Stacked on docs: reposition around ICP, use cases, and delivery guarantees #59 (merged); base is current master.
• Incorporates all the use-case fixes from the docs: reposition around ICP, use cases, and delivery guarantees #59 review passes (undefined BROADCAST_URL, the --public dev commands, scoped benchmark figure, OCPP-alpha wording, self-contained publish helpers).

[irinanazarova]

Solid, accurate use-case set with no blockers. Links resolve, the pages are wired into the sidebar and landing, and every code block runs in its intended context. This was a thorough multi-lens pass (class-generalization, code-block self-containment, links/anchors, cross-page consistency, per-persona journey, accuracy/ICP), each finding adversarially verified against source. Everything below is 🟡: a cleanup batch, not a merge gate. Base 30d200a is even with origin/master; CI green.

Accuracy / cross-page

🟡 NATS recommended for multi-node production without its experimental + 3-node caveat

ai-streaming.md:138-139 says "use a distributed broker (NATS, or Redis on Pro)". But reliable_streams.md:117 marks the NATS broker 🧪 experimental, and :146 requires a 3+ node JetStream cluster. Recommending it plainly alongside the Pro Redis broker overstates maturity. Fix: "NATS (experimental, 3+ node JetStream cluster), or Redis on Pro".

🟡 OCPP cross-linked from a backend-agnostic guide, but the feature is Rails/Action Cable only

gps-dispatch.md:108 ("AnyCable Pro speaks the OCPP WebSocket protocol") sits in a Python/Node, standalone-HTTP guide. The target ocpp.md:7 scopes OCPP to "Ruby or Rails applications ... using Action Cable" (RPC-backed OCPPChannel callbacks). A Python/Node reader follows the link expecting a standalone capability. The "alpha" qualifier is correct; the missing one is the Rails/RPC requirement. Fix: qualify ("alpha; integrates via Action Cable / a Rails backend") or drop the bullet here.

🟡 Presence multi-node caveat present on the AI page but missing from the two presence-heavy guides

gps-dispatch.md and telehealth.md lean entirely on presence and run the in-memory --presets=broker. presence.md:27 notes presence spans nodes only with the Pro Redis broker (Redis 7.4+ / Valkey 9.0+). ai-streaming.md:138 carries an equivalent multi-node note; these two don't. Fix: mirror the AI page's note in both Production-notes sections.

🟡 Live-dashboards headline benchmark has no in-repo source

live-dashboards.md:73-79 ("10,000 subscribers, 1M messages from 40 parallel publishers ... 4 ms median versus 155 ms for Socket.IO") traces only to the external compare page; benchmarks.md has no such figures and capabilities.md:107 is a different (latency) test, which the page correctly distinguishes. So no contradiction, but the headline number can't be cross-checked in-repo and lychee doesn't validate external content. Confirm the figures against the live compare page before publishing, or anchor them in benchmarks.md/capabilities.md.

Reader experience

🟡 ANYCABLE_BROADCAST_URL is read in step 2 but never set in step 1 (all four pages)

Step 1 runs anycable-go ... --public (which only prints the endpoint); step 2 then reads os.environ["ANYCABLE_BROADCAST_URL"] / process.env.ANYCABLE_BROADCAST_URL (ai-streaming.md:50, live-dashboards.md:43, gps-dispatch.md:46, telehealth.md:74). A literal top-to-bottom paste raises KeyError / fetch(undefined). The inline comment gives the value, so it's recoverable, but it's the first place copy-paste fails. Fix: add export ANYCABLE_BROADCAST_URL=http://localhost:8090/_broadcast under step 1, or default it in the snippet (os.environ.get("ANYCABLE_BROADCAST_URL", "http://localhost:8090/_broadcast")).

🟡 Demo step order broadcasts before any client subscribes

ai-streaming.md and live-dashboards.md put the producer (step 2) before the subscriber (step 3); telehealth.md correctly orders the subscriber first. A first-time tester who runs step 2, then opens the step-3 client, may see nothing, since a fresh streamFrom subscriber receives messages broadcast after it connects (offset-based catch-up is for reconnection; pre-subscription replay needs an explicit history.since, not the default). Fix: reorder so the client comes first (as telehealth does), or add a one-line note to keep the client open before broadcasting.

Code self-containment

🟡 gps-dispatch.md:79-82 second JS block isn't self-contained

The driver-app block does const board = cable.streamFrom('dispatch/online-drivers') but cable is created only in the earlier block (line 62), and driver (driver.id/name/vehicle) is undefined. It also re-declares const board (already at line 69) and leaves const online (line 74) unused in the prior block. It's framed as a separate actor so it won't collide at runtime, but it can't run alone. Fix: prefix it with the createCable setup and a // driver = current driver record comment, or fold the join into the first block; drop or use online.

🟡 (low) ai-streaming.md snippets are illustrative pseudocode

The Python/Node/client blocks reference llm, prompt, conversation_id, chunk.text, finalize, render with no definitions. The inline comments ("your LLM client's streaming API") signal intent, but unlike the other pages' concrete producer blocks these are skeletons. Optional: a one-line "these are your app's objects" comment to set expectations.

House style (linters don't enforce these)

🟡 Em dashes in ai-streaming.md:143,145

The "Example apps" bullets use — as a separator; house style forbids em dashes. These are the only two across all four pages. Fix: replace — with : .

🟡 Negative parallelism in telehealth.md:26

"AnyCable carries the signaling and session state, not the video itself." Fix: "AnyCable carries only the signaling and session state."

Naming consistency

🟡 Index table labels diverge from page title / nav / link text

index.md:9 column "Streaming AI responses" vs the link/nav "AI response streaming"; index.md:11 "Location tracking & dispatch" vs the link/H1/nav "GPS tracking & dispatch". The index column is arguably a use-case phrasing rather than a title mirror, so the clear outlier is "Location tracking" (the word "Location" appears nowhere else). Fix: at minimum align index.md:11 to "GPS tracking & dispatch"; decide whether the AI row's two phrasings are intentional.

Recommendation

Ship-ready on correctness: no 🔴, no broken links, no dead ends. Before merge I'd clear the higher-impact 🟡s, the unexported BROADCAST_URL (breaks literal copy-paste on all four pages), the NATS-experimental and OCPP-scope overstatements, and the missing presence multi-node caveat. The rest (em dashes, naming, step order, illustrative snippets) are a quick polish pass.

[irinanazarova]

Applied the review on 82d5579. All 🟡 items addressed; mdl + forspell clean locally on the changed pages.

Fixed

• ANYCABLE_BROADCAST_URL now defaults in all four backend snippets (os.environ.get(...) / ?? '...'), so a literal copy-paste runs without an unset-var error.
• NATS multi-node note now flags it as experimental and requiring a 3+ node JetStream cluster.
• OCPP cross-link scoped to its Action Cable / Rails backend requirement.
• Multi-node presence caveat (Redis broker, Redis 7.4+ / Valkey 9.0+) added to the gps-dispatch and telehealth guides.
• gps-dispatch driver-app snippet made self-contained (import + createCable + driver note); the dead presence.info() binding is now used.
• Local-testing note added to ai-streaming and live-dashboards (start the client before broadcasting; a fresh subscriber only gets messages sent after it connects).
• Naming aligned: "AI response streaming" and "GPS tracking & dispatch" across H1, index, and nav.
• House style: em dashes and the one negative parallelism removed.

Verified rather than changed

• The dashboards 4 ms / 155 ms fan-out figures check out against the published comparison (10K subscribers, 40 publishers). Tightened the wording to "1M deliveries" to match the source exactly.

Left as illustrative (by design)

• The AI-streaming llm / prompt / conversation_id snippets stay pseudocode; added a one-line note that these are your application's objects.