Skip to content

docs: flow 2.2.0 reference (hold until 2.2.0 is released) - #269

Merged
abrichr merged 11 commits into
mainfrom
docs/flow-2.2.0
Oct 18, 2026
Merged

abrichr merged 11 commits into
mainfrom
docs/flow-2.2.0

Conversation

@abrichr

@abrichr abrichr commented Oct 18, 2026 •

Copy link
Copy Markdown
Member

Hold this PR. Don't merge it until openadapt-flow 2.2.0 is on PyPI. It goes live the day 2.2.0 is released.

This PR documents what ships in openadapt-flow 2.2.0 and openadapt-agent 2.2.1. That is OpenAdapt main plus the version bump in OpenAdaptAI/OpenAdapt#1209. Until the release, the pages describe behavior that's on main but not yet installable from PyPI.

It's stacked on #267, the launcher and agent help drift check. #266 is merged and is already included. Once #267 merges, change the base to main.

What it adds

  • Approvals. Every run under every profile waits on each save unless the operator chooses another mode. By default a person answers. With an approver policy, a delegated agent or system can answer from the CLI, over MCP, or through a signed webhook. Admission stays per workflow.
  • MCP tool reference. Which tools each server mode exposes, the authoring tools, and every serve option.
  • Record checks. One section covering the system-of-record kinds, candidates, the separate-session read, checks shown by demonstration, the on-screen read-back, and plugin verifiers.
  • How strong a read-back is. A table that maps each kind of read-back to its Flow tier, grade, VERIFIED eligibility, certification, and Seal check level. A marked spot is left for the R0–R3 ladder, which will be filled in when the reopen-readback change lands.
  • Receipts, Seals, and countersigning (new page). Covers the run receipt, the Seal and how to check it offline, verify-run effect receipts, and countersign: timestamps, the TSA choice, commitments, the vault, the exception queue, and the dossier. The receipt and Seal sections in the files page and the Execute page now link here instead of repeating it.
  • Configuration reference. Every backend field, remote-session markers and the frame contract, onscreen and plugin effects, candidates, identity:, idempotency:, require_settled, layout_drift_check, the remote-decision fields, and the 2.2.0 environment variables.
  • verify.yaml reference and the one-command qualify campaign.
  • Command reference moved to 2.2.0: check, countersign, jit, pull, triage, and verify-run.
  • Removes the "on main only" notes for features that ship in 2.2.0: agent recording, countersign disclosure, package folding, and the browser choice.

Command help pins

The pins point at OpenAdapt main at 9104577e and label it as the 2.2.0 and 2.2.1 releases:

  • Flow commands. scripts/flow_cli_reference.py (ci(docs): command reference from the released Flow; private name check #265) has FLOW_VERSION = "2.2.0", plus a FLOW_SOURCE that builds from that commit until 2.2.0 is on PyPI. The flow-cli-release job compares the snapshot against that build. The 2.2.0 snapshot has the same commands and options as the build the docs were written against.
  • Launcher and agent help. cli-reference/requirements.txt has source pins in the form name @ git+URL # release VERSION. The installed-version check skips those pins.

Not documented yet

The approvals pages describe main as it is now: every run waits on each save unless the operator picks another mode. The decided plan is to admit once, then stop only on problems, with per-save approval as the strictest setting. It lands in OpenAdaptAI/OpenAdapt#1212 and isn't described here. If #1212 merges before 2.2.0, the approvals section, the mode table, and the FAQ answer need updating before this merges.

These open PRs aren't documented either: OpenAdaptAI/OpenAdapt#1231 (surface rule), #1233 (record --verify), #1235 (SMART auth), and #1239 (the read-back ladder). The verification page leaves a marked spot for the ladder.

On release day

  1. Set FLOW_SOURCE = None and rerun flow_cli_reference.py snapshot. Change the two source pins to openadapt-flow==2.2.0 and openadapt-agent==2.2.1, then rerun scripts/generate_cli_reference.py. Fix any page the diff touches. #1209 has to merge main before the release, and the help text from docs: fix approval-mode default, agent approval tools, and launcher serve help OpenAdapt#1238 will show up here too.
  2. Update the compatibility table and its checker. In 2.2.0, openadapt-flow no longer depends on openadapt-types, and openadapt-agent depends on openadapt-flow.
  3. Add the changelog entries, then merge.

abrichr and others added 10 commits October 17, 2026 23:38
… versions

connect-an-agent said no tool approves a save without saying what does.
It now names the released route (openadapt flow item-approval) and the
three approval tools on main. Desktop pages described a per-save approval
form that desktop-v0.15.0 doesn't have. data-handling gains a by-command
table of what leaves the computer, including the countersign timestamp
request on main. configuration listed OPENADAPT_FLOW_BROWSER, which isn't
in openadapt-flow 2.1.0.
item-approval approve refuses an answer with neither --approver-id nor
--unauthenticated, so the example would have failed.
# Conflicts:
#	docs/security/data-handling.md
…signing, configuration, verify.yaml

Write the reference for what ships in openadapt-flow 2.2.0 and
openadapt-agent 2.2.1, and pin the generated command help to OpenAdapt
main until those versions are on PyPI.
Follow main's Flow reference (#265) for Flow: FLOW_VERSION 2.2.0, built
from OpenAdapt main until the release is on PyPI. The launcher and agent
help stay with generate_cli_reference.py.
# Conflicts:
#	docs/how-to/connect-an-agent.md
#	docs/reference/configuration.md
#	docs/security/data-handling.md
Release day for #269: pins openadapt-flow==2.2.0 and openadapt-agent==2.2.1,
snapshots the Flow command reference from the PyPI release, regenerates the
launcher and agent help, and lists the six verbs 2.2.0 added in the curated
table.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Base automatically changed from ci/cli-reference-drift to main October 18, 2026 16:06
Keeps the released 2.2.0 pins with main's click pin, and the release-only
version list in the generated help header.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@abrichr
abrichr merged commit 9a3c722 into main Oct 18, 2026
10 checks passed
@abrichr
abrichr deleted the docs/flow-2.2.0 branch October 18, 2026 16:26
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