docs: rewrite the README around the first run - #1127
Merged
Conversation
Same structural rewrite as openadapt-flow. The old opening spent 45 lines on repository roles and admission language before the reader saw a command. - Lead with what the tool does, then say plainly that this repo is the installer and the engine is elsewhere. - Replace the prose description of quickstart with its real terminal output, captured from openadapt 1.16.0 on 2026-08-28, and surface --break-it. - Keep the run-outcome table; it is reference material unique to this repo. - Fold the substrate tables from two into one, and the project map from a bullet list plus a details block into one list plus one paragraph. - Drop the OpenAdapt Desktop preview image. It is a synthetic headless fixture from Desktop PR #93, and its caption says the release hash will be updated after Desktop 0.15, which shipped. A mockup captioned as a product view is not worth the trust it costs. The generated PRODUCTION LIFECYCLE block is unchanged; scripts/render_readme_maturity.py --check and tests/test_readme_maturity.py both pass. 348 lines to 275. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.
Companion to openadapt-flow#423. Same diagnosis, same treatment.
The old README passed the word-level checks and still read like generated
text, because the problems were structural: it opened with a repository-role
note and an admission paragraph, and the first command was 45 lines down.
What changed
Order is now: what it does, who this repo is, docs link, install,
quickstartwith its real output,
--break-it, your own workflow, how a run ends,surfaces, where data lives, evidence, Execute, the lifecycle block, where the
code is, contributing.
The quickstart output is not paraphrased. I installed
openadapt==1.16.0fromPyPI into a clean venv and ran it on macOS today.
openadapt quickstart --help,--break-it,openadapt flow visualize,lint, and all six extras werechecked against that install rather than read off the source tree. Every
external link returns 200.
Two tables became one. The substrate model was stated twice, once as "product
family" and once as "substrate," with overlapping content.
One removal worth flagging
I dropped the Desktop preview image. Its own caption says it is a "headless
synthetic fixture from Desktop PR #93" and that the final release hash will be
updated after Desktop 0.15, which is now on PyPI at 0.15.0, so the caption is
stale. A mockup sitting where a reader expects a product screenshot costs more
trust than it buys, even with honest provenance underneath it. Happy to put it
back if you would rather, but by then it should be a real screenshot of a real
run.
Gates
python scripts/render_readme_maturity.py --checkpasses andpytest tests/test_readme_maturity.pyis 9/9. The generated PRODUCTIONLIFECYCLE block is byte-identical.
348 lines to 275. Zero em dashes.
Two red checks, neither of them this PR
Both reproduce on a pristine, unmodified
origin/mainworktree:validatefails because theopenadapt-opssource bytes moved upstream and thepin here is behind. It wants a repin and a rerender, which rewrites the generated
PRODUCTION LIFECYCLE block.
validate-platform-manifestfails becauseopenadapt-flow 1.34.0 published today and the manifest still advertises 1.33.0
and its digests. It wants
scripts/generate_platform_manifest.py.I fixed neither, deliberately. Both regenerate signed or digest-bearing
artifacts, and doing that inside a prose PR buries a real change in a diff nobody
expects to contain one. They also want to be one commit each, so the bisect is
readable the next time this drifts.