docs: rebuild flagship README around first value#1047
Merged
Conversation
abrichr
marked this pull request as ready for review
July 25, 2026 01:07
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.
Summary
pip install openadaptpath, and a verified five-minute local quickstartopenadapt-flowas the canonical engineWhy
The previous README had accumulated product positioning, two onboarding paths,
detailed Cloud ingestion, full CLI reference, substrate evidence ledgers,
diagrams, research history, migration notes, and repository topology at the
same visual level. That made the first useful action hard to find and duplicated
material maintained in the docs and engine repository.
GitHub's README guidance recommends answering what the project does, why it is
useful, how to start, where to get help, and who maintains it, while moving
longer documentation elsewhere. The new structure follows that pattern and the
install-first conventions used by projects such as Playwright, Temporal, uv,
and Supabase.
Product and repository boundary
OpenAdaptAI/OpenAdaptremains the starred top-level open-source destination and source ofpip install openadapt.OpenAdaptAI/openadapt-flowis clearly named as the canonical compiler/runtime implementation, without creating a competing end-user install path.Validation
openadapt==1.7.2:demo-recordcompilecertify --policy permissivereplayvisualizelintruff check openadapt testsruff format --check openadapt testspytest tests -q(10 passed)python -m buildpython scripts/verify_release_artifacts.py8850318b62c8743377eb3ce4d4a3a66b424c32636704e983e6e1f4e1c39bd9bcd7d76e0d42da3fb47920a1d7940bb3ecf7f52d03d02e1b0a5e20897a88c59e52Tradeoffs
The README no longer embeds the full Cloud sanitization recipe, every backend
flag, research-package history, benchmark caveat essay, or release ledger.
Those remain available through canonical documentation and the engine
repository. The README keeps enough evidence and architecture to establish
credibility, then prioritizes a successful first run.