Skip to content

docs: rewrite the README around what the tray actually is - #48

Merged
abrichr merged 3 commits into
mainfrom
docs-readme-human-rewrite
Aug 28, 2026
Merged

docs: rewrite the README around what the tray actually is#48
abrichr merged 3 commits into
mainfrom
docs-readme-human-rewrite

Conversation

@abrichr

@abrichr abrichr commented Aug 28, 2026

Copy link
Copy Markdown
Member

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:

  • The wheel ships a second entry point, openadapt-tray-gui. It was
    undocumented. It's in the install block now. Both entry points call
    openadapt_tray.app:main; the only difference is that this one is registered
    under gui_scripts, so Windows launches it without a console window. It is
    not a different program.
  • The config sample listed "stop_recording": "<ctrl>+<ctrl>+<ctrl>" with no
    explanation, which reads like a typo. It isn't: stop_on_triple_ctrl on this
    package's TrayConfig in config.py defaults to True, and that's the
    hotkey it enables. I kept the line and said so.

Also checked the HotkeyConfig field names and deployment_lane against the
installed package rather than the source tree.

280 lines to 176. Zero em dashes.

The three README strings a test pinned

tests/test_public_metadata.py matched three literal strings against headings
this rewrite removed. All three facts are still in the file, and two of them
moved earlier:

Test asserted Where it is now
Lifecycle: Experimental supporting surface "this is a status surface, not an integrated desktop product", second paragraph
Release boundary (heading) "It records nothing, compiles nothing, and replays nothing", first paragraph
not been validated together end to end unchanged, first bullet of What this doesn't do yet

The 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 Control and monitoring training must still not
appear.

Open question for a reviewer. If you want the literal
Lifecycle: Experimental supporting surface string back in the README, say so
and it goes back. The argument for dropping it: the registry at
OpenAdaptAI/.github/REPOSITORY_LIFECYCLE.md is the canonical place for a
lifecycle 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-flow pins three
licensing strings in tests/test_openimis_claims_fixture.py, and
openadapt-capture pins an admission-state claim in
tests/test_public_lifecycle.py. Grep tests/ for the file name before
rewriting a README anywhere in the org.

abrichr and others added 3 commits August 28, 2026 11:24
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.
@abrichr
abrichr merged commit 3dc385c into main Aug 28, 2026
10 checks passed
@abrichr
abrichr deleted the docs-readme-human-rewrite branch August 28, 2026 17:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant