docs: business-first org profile and registry-driven GitHub metadata

[abrichr]

This rewrites the OpenAdaptAI organization profile so that a business reader learns from the first screen what OpenAdapt does, what changes for their team, and how to start. It corrects the fault-test figure: the screen-only check passed 54 of the 72 runs that left the record wrong, not "54 of 90". It also makes repository-lifecycle.yml the source of truth for the GitHub settings that visitors see, and it adds a script that an owner runs to apply them after merge.

What changes

Organization profile (profile/README.md)

• Opens with the launcher README's headline: OpenAdapt enters approved information into the systems your team already uses, and then it checks that the entry saved.
• Adds a before-and-after table for a faxed referral. The baseline of about 10 to 12 minutes cites two hospital time studies, and the profile says that nobody has measured an "after" time with OpenAdapt yet.
• Lists the five ways a run can end in plain terms. Only "Stopped before saving" says that nothing was written.
• Offers two paths: hand off a workflow, or run openadapt quickstart --break-it yourself. The billing-audit case study is withdrawn, so the profile doesn't link to it.
• Changes the install command from pip install --upgrade 'openadapt[browser]' and openadapt quickstart to pip install --upgrade openadapt and openadapt quickstart --break-it. In the current release (1.16.0), the base openadapt package already includes browser support, and the CLI has --break-it.
• Moves developer content below the business sections and adds a table that maps each plain result to its engine outcome.
• Restates the fault test with the correct counts (54, 9, and 0 of 72) and the 9 of 18 correct saves that every check stopped.
• Removes the historical MockMed comparison (100/100 and 20/20 runs, 4.9s and 37.5s median, $0 and $0.27 a run) and the "Install OpenAdapt" and "Read the docs" links in the top row. The OpenEMR and fault-test results stay. The docs are still linked from "Run it yourself".

Registry and checks

• repository-lifecycle.yml holds the organization description and website, the headline, the six pins, and a description, website, and topic list for 29 repositories. ehr-integration-directory replaces openadapt-evals among the pins and joins Support.
• Schema change: public_metadata.repository_descriptions (description only) is replaced by public_metadata.repositories (description, homepage, and topics). schema_version stays 2. A code search of the organization found no other reader of the old key, and the lifecycle validator reads only the lifecycle and public_surfaces groups.
• New scripts/github_metadata.py reads the registry without a YAML dependency and enforces GitHub's topic and pin limits and short-copy rules.
• scripts/check_profile.py checks the pins, lifecycle labels, plain terms in business-facing copy, section order, the headline, the absence of "54 of 90", and that the apply script matches the registry.
• benchmark-claims.json binds the 12 figures on the new profile to pinned artifacts and drops the entries for the removed figures.
• README.md replaces the manual list of GitHub settings with the apply-script steps. REPOSITORY_LIFECYCLE.md adds ehr-integration-directory to Support and uses sentence-case headings.

Apply script (.overhaul/APPLY.sh, rendered from the registry)

• The default is a dry run that prints each gh command and calls nothing.
• --apply requires an organization owner, reports each failed command, and then compares every value on GitHub with the registry.
• --verify only reads. It exits 0 only when everything matches, and 2 when only the hand-set pins remain.

Screenshots

Before	After
Before: the first screen of the org profile opens with engineering terms and a pip command.	After: the first screen says what OpenAdapt does in plain words and compares a faxed referral today and with OpenAdapt.

Before	After
Before: the fault test pairs 75.0% with "54 of 90 runs", which is the wrong denominator.	After: the fault test reports 54 of 72 wrong records (75.0%), the claim of record, plus the runs every check stopped.

After: developers get a table that maps each plain result to the engine outcome it comes from.

Before	After
Before: the profile on a 390-pixel phone screen.	After: the profile on a 390-pixel phone screen, where the before-and-after table wraps into narrow columns.

The read-only check of live GitHub settings shows today's descriptions and pins next to the values the apply script sets.

How it was tested

These were run on 2026-10-09:

• python3 -m unittest discover -s tests -p 'test_*.py': 400 tests pass. The 30 new tests cover the registry parser, the profile rules, and the apply script, and 11 of them run the script against a fake gh.
• python3 scripts/check_profile.py: 29 descriptions, 6 pins, and 45 Markdown links validated.
• python3 scripts/validate_evidence_registry.py: valid.
• python3 scripts/check_benchmark_claims.py --online --allow-recorded-drift: 12 figures bound, and all 4 upstream artifacts matched.
• shellcheck, bash -n, and ruff check on the changed files: clean.
• A dry run listed 59 changes and called nothing.
• A read-only --verify against GitHub exited 1 as expected: 45 of 90 values differ today, and the pins differ.
• Every link in the profile and every registry website returned HTTP 200.

After merging

Merging updates the profile. GitHub settings change only when an owner applies them:

1. Run .overhaul/APPLY.sh and review the 59 commands.
2. Run gh auth refresh -s admin:org,repo as an owner of OpenAdaptAI.
3. Run .overhaul/APPLY.sh --apply. It also sets the private openadapt-web and openadapt-cloud descriptions, and an empty website or topic list clears that field.
4. Under Customize pins, pin in this order: OpenAdapt, openadapt-flow, openadapt-desktop, openadapt-capture, openadapt-agent, ehr-integration-directory. GitHub has no API for pins.
5. Run .overhaul/APPLY.sh --verify and confirm that it exits 0.

Decisions for the owner:

• Confirm that ehr-integration-directory belongs in Support.
• Decide what to do with six public forks that have no registry entry: OpenCUA, OmniParser, UI-TARS-desktop, pynput, oa.blog, and atomacos.

The launcher README in OpenAdaptAI/OpenAdapt (branch feat/business-clarity-launcher) uses the same headline. No merge order is required. If its first line changes, update profile_headline in the registry and the first bold line of the profile. The profile check fails until the two match.

🤖 Generated with Claude Code