docs: restructure README around use cases - #52
Merged
Conversation
Lead with the CLI and route from a "what do you want to do?" table into a section per task, instead of a library-first tour organised by module. The library is still documented, collapsed into one section. Claude-Session: https://claude.ai/code/session_01Auxp5B8pSEsvFHRTCWFMUs
buckleypaul
force-pushed
the
docs/readme-use-case-restructure
branch
from
August 27, 2026 22:17
0618b03 to
548ba6b
Compare
buckleypaul
force-pushed
the
docs/readme-use-case-restructure
branch
from
August 27, 2026 22:20
35cf16a to
548ba6b
Compare
The use-case restructure carried over several statements that no longer matched the code, and the new framing made a few of them contradictory. Every claim here was checked against a live run rather than the source. - ble scan: --counter-mode / --period-exponent no longer advertise a default that auto-detection overrides. Document the sweep, the real "[INFO] Detected:" line, and the two usage rules (DEVICE_UPTIME needs --key, conflicts with --days) that a reader following the table hit. - "Every command lives inside a group" was false: doctor and validate-credentials are top level. Name them, and restore the cross-group "Did you mean" recovery demo dropped in the restructure. - Both scan samples are now byte-identical to what the printers emit. The old one showed 3 rows under a "4 packets" summary, and paired a V=2 (AES-EAX, counter 0-127) row with a 20320 day counter, which decrypt_eax cannot produce. Explain what V implies for the EID and CTR/SEQ columns instead. Doctor sample regenerated with the Unicode glyphs it actually prints. - Configuration listed two environment variables; there are six. SDR_DOCKER_IMAGE was documented nowhere. - Telemetry named only org and metrics as Cloud API callers, omitting doctor, validate-credentials, ble validate, ble scan --ingest and ready provision. - Org streaming applies to tabular output only; -o json/csv buffer, and get-packets applies --limit after the download. - sat is a ground receiver: an SDR beside you hears the device's uplink. Nothing arrives from a satellite. - Python examples: define key, filter by packet type before decrypt() (it returns None rather than raising on a type it can't handle), and distinguish decrypt_satellite's bytes from the others' DecryptedPacket. Give DockerError/SatelliteError their real import path and add the four SatellitePacket diagnostic fields behind the --debug columns. - Add the missing provisioning section: ready provision plus the eight per-characteristic commands, ble check-time and ble detect. Claude-Session: https://claude.ai/code/session_01Auxp5B8pSEsvFHRTCWFMUs
The `ready` commands are not working, so documenting them sends users at a broken path. Drops the "Provision a device over Bluetooth" section and every pointer to it: the use-case table row, the group list bullet, the intro blurb, the Bluetooth requirement, the SDK import list, and the telemetry command list. `ble check-time` and `ble detect` were documented inside that section because they contrast with connecting over GATT. They move to the end of `ble validate` with the lead rewritten, rather than being lost with it. Claude-Session: https://claude.ai/code/session_01Auxp5B8pSEsvFHRTCWFMUs
Cut ~13% of the README's words without dropping any commands, flags, or reference tables: - Merge the duplicated "also an SDK" intros into the opening sentence. - Drop the two illustrative blocks that repeated their own prose: the `Did you mean:` demo and the second (ASCII) sample table, which showed the same three rows as the Unicode one. - Collapse `ble validate`'s seven numbered steps into one arrow chain; the list restated what each step's name already said. - Turn the `V` protocol-version run-on into three bullets, one per case. - Compress the detection, satellite-container, org-buffering, ASCII and macOS-crash passages, and the telemetry constraints list. Claude-Session: https://claude.ai/code/session_01Auxp5B8pSEsvFHRTCWFMUs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Restructures the README to focus on use cases: CLI-first, with a "what do you want to do?" table routing into a section per task, rather than a library-first tour organised by module. The library is still documented, in one section.