Skip to content

docs: make Reference > Glossary the one place terms are defined - #242

Merged
abrichr merged 1 commit into
mainfrom
glossary/canonical
Oct 17, 2026
Merged

abrichr merged 1 commit into
mainfrom
glossary/canonical

Conversation

@abrichr

@abrichr abrichr commented Oct 17, 2026

Copy link
Copy Markdown
Member

Richard wants key terms such as "qualify" defined in one place that the README, the docs and the CLI help can all link to. This makes Reference > Glossary that place. It builds on the #240 structure and moves no pages.

Changes

  • Qualify (#qualify), Certify (#certify) and Certification policy (#certification-policy) replace the old Qualification, Certification and Policy entries. They match the engine's terms page, packages/flow/docs/QUALIFICATION_TERMS.md, which is now on the monorepo's main. That resolves the TODO waiting on openadapt-flow#532. Each entry links to the engine page for the details: the fault cases, what gets signed, and the policy rules.
  • The old anchors #qualification, #certification and #policy are kept as <a id> targets, so existing links still land on the right entry.
  • New entries: Bundle, Demonstration ("a person or an agent shows the task"; "one or more demonstrations go into the compiler"), and Runner.
  • Substrate now leads with vision: OpenAdapt reads every substrate from what is on screen. DOM, UIA, AX or AT-SPI add evidence where a substrate has them, and RDP and Citrix give pixels only.
  • The plain-language glossary, the Reference index and llms.txt now point at this page as the canonical definitions. The plain-language page stays a map from plain terms to these entries.
  • qualify --certify isn't in a Flow release yet (tests/test_documented_flow_options.py checks documented options against the released CLI), so the Certify entry names it as a main-only option.

Checks

  • mkdocs build --strict, scripts/validate_docs.py and pytest tests all pass (546 passed, 1 skipped).
  • lychee, offline with --include-fragments, over the built site: 1,146 unique links, 0 errors.

Follow-ups

  • The README links qualify here in OpenAdaptAI/OpenAdapt (the README PR).
  • Flow's CLI help still points at the relative path docs/QUALIFICATION_TERMS.md, which means nothing to someone who installed from PyPI, and one help string uses a #policies anchor that doesn't exist. That's package code, which the carry-over work is changing right now, so it's left for after the carry-over.

Adds Qualify, Certify and Certification policy entries that match the
engine's qualification terms, now on the monorepo's main, and resolves
the TODO waiting for them. Old anchors (#qualification, #certification,
#policy) still land on the same entries.

Adds Bundle, Demonstration and Runner. The Substrate entry now says
OpenAdapt reads every substrate from what is on screen, with DOM, UIA,
AX or AT-SPI as added evidence where they exist.

The plain-language glossary, Reference index and llms.txt point at this
page as the canonical source.
@abrichr
abrichr merged commit cc27486 into main Oct 17, 2026
6 checks passed
@abrichr
abrichr deleted the glossary/canonical branch October 17, 2026 21:46
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