Skip to content

docs: rewrite the README around the first run - #1127

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

docs: rewrite the README around the first run#1127
abrichr merged 2 commits into
mainfrom
docs-readme-human-rewrite

Conversation

@abrichr

@abrichr abrichr commented Aug 28, 2026

Copy link
Copy Markdown
Member

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, quickstart
with 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.0 from
PyPI into a clean venv and ran it on macOS today. openadapt quickstart --help,
--break-it, openadapt flow visualize, lint, and all six extras were
checked 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 --check passes and
pytest tests/test_readme_maturity.py is 9/9. The generated PRODUCTION
LIFECYCLE 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/main worktree:

$ git worktree add --detach /tmp/oa-main origin/main
$ cd /tmp/oa-main && python scripts/render_readme_maturity.py --check --require-current-source
REFUSED: source file projection changed on openadapt-ops main; repin and rerender

$ python scripts/validate_platform_manifest.py
ERROR: flow version drift: manifest has '1.33.0' but PyPI's latest openadapt-flow is '1.34.0'.

validate fails because the openadapt-ops source bytes moved upstream and the
pin here is behind. It wants a repin and a rerender, which rewrites the generated
PRODUCTION LIFECYCLE block. validate-platform-manifest fails because
openadapt-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.

abrichr and others added 2 commits August 28, 2026 11:13
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>
@abrichr
abrichr merged commit a1c0b32 into main Aug 28, 2026
13 checks passed
@abrichr
abrichr deleted the docs-readme-human-rewrite branch August 28, 2026 17:04
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