Skip to content

docs: rebuild flagship README around first value#1047

Merged
abrichr merged 1 commit into
mainfrom
agent/readme-rebuild-20260725
Jul 25, 2026
Merged

docs: rebuild flagship README around first value#1047
abrichr merged 1 commit into
mainfrom
agent/readme-rebuild-20260725

Conversation

@abrichr

@abrichr abrichr commented Jul 25, 2026

Copy link
Copy Markdown
Member

Summary

  • reduce the flagship README from 681 lines / 4,318 words to 206 lines / 1,062 words
  • lead with the product outcome, the canonical pip install openadapt path, and a verified five-minute local quickstart
  • present browser, native desktop, and remote applications as one governed product model without transient Experimental/Research copy
  • make this repository's role unambiguous: flagship project and launcher entry point, with openadapt-flow as the canonical engine
  • retain concise customer/reference evidence, deployment choices, the MIT/open-core boundary, contribution routing, and support links
  • remove the source-text unit test that pinned ordinary marketing copy inside the retired hero image

Why

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/OpenAdapt remains the starred top-level open-source destination and source of pip install openadapt.
  • OpenAdaptAI/openadapt-flow is clearly named as the canonical compiler/runtime implementation, without creating a competing end-user install path.
  • The local launcher, runtime, Desktop, adapters, verification interfaces, and basic qualification tools are described as MIT; the multi-tenant Cloud control plane is described as commercial.
  • Deep architecture, qualification evidence, and the full CLI are linked to canonical live docs rather than copied into the README.

Validation

  • Published-package smoke against exact openadapt==1.7.2:
    • demo-record
    • compile
    • certify --policy permissive
    • replay
    • visualize
    • lint
  • 17 product/docs/repository/package/image links checked live: all HTTP 200
  • ruff check openadapt tests
  • ruff format --check openadapt tests
  • pytest tests -q (10 passed)
  • python -m build
  • python scripts/verify_release_artifacts.py
  • wheel: 8850318b62c8743377eb3ce4d4a3a66b424c32636704e983e6e1f4e1c39bd9bc
  • sdist: d7d76e0d42da3fb47920a1d7940bb3ecf7f52d03d02e1b0a5e20897a88c59e52

Tradeoffs

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.

@abrichr
abrichr marked this pull request as ready for review July 25, 2026 01:07
@abrichr
abrichr merged commit 543a7c1 into main Jul 25, 2026
10 checks passed
@abrichr
abrichr deleted the agent/readme-rebuild-20260725 branch July 25, 2026 01:08
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