docs: rewrite the README around what the tray actually is - #48
Merged
Conversation
Same structural rewrite as openadapt-flow. The old file spent 30 lines on a copy of the 'what OpenAdapt is' paragraph that appears verbatim in five other repositories before it said anything about a tray, and the install command was at line 165. - Open by saying plainly that this is a status surface: it records nothing, compiles nothing, replays nothing. - Install moves to the top. - Fold Release boundary and Known gaps into one honest section. They overlapped and both hedged the same three facts. - Document openadapt-tray-gui, the gui_scripts entry point that ships in the wheel and was undocumented. - Add stop_on_triple_ctrl beside the triple-ctrl stop_recording hotkey, which otherwise reads like a typo. Verified against openadapt-tray 0.3.3 from PyPI: both console entry points, the HotkeyConfig field names, deployment_lane, and stop_on_triple_ctrl. 280 lines to 176. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both entry points call openadapt_tray.app:main. The difference is the entry-points group: gui_scripts, so Windows launches it without a console window. 'Windowless variant' implied a different program.
test_public_metadata pinned three literal strings: a 'Lifecycle: Experimental supporting surface' label, a 'Release boundary' heading, and the not-validated-together sentence. The rewrite states all three facts more plainly, so the heading-shaped assertions failed while the guarantees they protect are intact and, if anything, stated earlier in the file. The assertions now name the claims: that this is a status surface rather than an integrated desktop product, that it records, compiles and replays nothing, and that the tray and openadapt-desktop have not been validated together end to end. The negative assertions are untouched. Whitespace is collapsed first so a reflow cannot break a match that a reader would still see as present.
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
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.
Part of the README pass across the public repos
(openadapt-flow#423
has the diagnosis).
Thirty lines went by before this file mentioned a tray. It opened with the
"OpenAdapt is a governed demonstration compiler" paragraph that appears word
for word in five other repositories, and the install command was at line 165.
The opening now says the thing the rest of the file spends its caveats
circling: this is a status surface. It records nothing, compiles nothing,
replays nothing. Saying that in the first sentence makes the whole document
shorter, because half the hedging existed to walk back an implication the
opening created.
"Release boundary" and "Known gaps" were two sections hedging the same three
facts. They're one section now, and it's more direct than either was.
Verified against 0.3.3 from PyPI
Two things the old README got wrong or missed:
openadapt-tray-gui. It wasundocumented. It's in the install block now. Both entry points call
openadapt_tray.app:main; the only difference is that this one is registeredunder
gui_scripts, so Windows launches it without a console window. It isnot a different program.
"stop_recording": "<ctrl>+<ctrl>+<ctrl>"with noexplanation, which reads like a typo. It isn't:
stop_on_triple_ctrlon thispackage's
TrayConfiginconfig.pydefaults toTrue, and that's thehotkey it enables. I kept the line and said so.
Also checked the
HotkeyConfigfield names anddeployment_laneagainst theinstalled package rather than the source tree.
280 lines to 176. Zero em dashes.
The three README strings a test pinned
tests/test_public_metadata.pymatched three literal strings against headingsthis rewrite removed. All three facts are still in the file, and two of them
moved earlier:
Lifecycle: Experimental supporting surfaceRelease boundary(heading)not been validated together end to endThe assertions now name the claims instead of the headings, and they collapse
whitespace before matching, so a line rewrap can't break an assertion on a
sentence a reader would still see. Every negative assertion is untouched:
openadapt train,Training Controlandmonitoring trainingmust still notappear.
Open question for a reviewer. If you want the literal
Lifecycle: Experimental supporting surfacestring back in the README, say soand it goes back. The argument for dropping it: the registry at
OpenAdaptAI/.github/REPOSITORY_LIFECYCLE.mdis the canonical place for alifecycle label, and a plain sentence about what the thing does not do is harder
to misread than a label is.
Two sibling repositories carry the same trap.
openadapt-flowpins threelicensing strings in
tests/test_openimis_claims_fixture.py, andopenadapt-capturepins an admission-state claim intests/test_public_lifecycle.py. Greptests/for the file name beforerewriting a README anywhere in the org.