Skip to content

docs: give the phone path an answer that does not start with "configure TLS" - #88

Merged
abrichr merged 1 commit into
mainfrom
docs/phone-decisions-without-ingress
Jul 28, 2026
Merged

docs: give the phone path an answer that does not start with "configure TLS"#88
abrichr merged 1 commit into
mainfrom
docs/phone-decisions-without-ingress

Conversation

@abrichr

@abrichr abrichr commented Jul 28, 2026

Copy link
Copy Markdown
Member

Why

The docs said, correctly, that reaching the decision surface from a phone requires the customer to terminate trusted TLS in front of the runner. That was the only documented phone path, and it disqualified the target buyer: a dental practice will not stand up an enterprise reverse proxy. So the phone path read as available and was not.

The hosted lane closes that (OpenAdaptAI/openadapt-cloud#184, merged and deployed; OpenAdaptAI/openadapt-flow#296 + #297). This says which path is which.

What changed

concepts/halt-learn-loop.md — "Reaching it from a phone is your ingress, not ours" becomes "Reaching it from a phone", with two subsections:

  • The hosted lane — nothing to configure. Named as the default for a practice without an IT department. Outbound only; three steps; explicitly "you do not terminate TLS".
  • The runner-local portal — full fidelity, on your own terms. The existing warning is kept verbatim, because it is still true of that surface and that surface is still right for an org with an ingress. It is now framed as the full-fidelity option rather than the only option, and the warning points at the alternative.

What the hosted lane carries is stated exactly, because "we send less" is only trustworthy if the reader can check it: closed enums, bounded integers, booleans, no string field, no image — structurally unable to hold a name, an MRN, an observed value, or a workflow label. Explicitly not scrubbed evidence. The one thing it gives up — the target control's accessible name — is named rather than glossed.

guides/security-and-data-handling.md — the decision-surface bullet now distinguishes the full-evidence runner surface from the hosted lane, and says plainly that a customer without an ingress uses the latter.

reference/configuration.md — a new section with the human_decisions.remote settings, OPENADAPT_RUNNER_TOKEN, the context_tier values (and that local_full is refused by name), the rule that the execution profile's ceiling and the configured tier both apply and the weaker wins, and a note that every misconfiguration stops the console rather than running one whose phone lane is silently absent.

Accuracy

  • The hosted control plane is live and ready: https://app.openadapt.ai/api/health/ready reports ready: true with the database/migration contract ready, after #184 deployed.
  • The engine flag ships in openadapt-flow #297. Desktop passes it in feat(portal): answer halts on a phone without any customer ingress openadapt-desktop#85 once the bundled Flow pin moves; this page describes the deployment setting and the lane, not a Desktop toggle, so it does not claim a control that is not there yet.
  • scripts/validate_docs.py passes.

…re TLS"

The docs said, correctly, that reaching the decision surface from a phone
requires the customer to terminate trusted TLS in front of the runner. That was
the only phone path, and it disqualified the target buyer: a dental practice
will not stand up an enterprise reverse proxy, so the phone path was documented
as real and was unavailable to the people it was for.

There are two paths now, and this says which is which.

The hosted lane needs nothing on the customer's network. The runner dials OUT,
so there is no inbound port, no port forward, no certificate, no reverse proxy
and no static address, and it works behind NAT on ordinary broadband. Connect
the computer once, enable remote decisions bound to the exact tenant and runner,
and staff answer from a web page on a phone.

What it carries is stated exactly, because "we send less" is only trustworthy if
the reader can check it. The closed halt context is closed enums, bounded
integers and booleans with no string field and no image, so the hosted service
is structurally unable to hold a name, an MRN, an observed value or a workflow
label. It is not scrubbed evidence. The one thing it gives up -- the target
control's accessible name -- is named rather than glossed.

The runner-local portal keeps its warning verbatim, because it is still true of
that surface and it is still the right surface for an organisation that operates
an ingress. It is now framed as the full-fidelity option rather than the only
option, and the warning points at the alternative.

The configuration reference gains the settings, the credential, the profile
ceiling rule, and the note that every misconfiguration stops the console: a lane
that looks on and is not is worse than one that is plainly off.
@abrichr
abrichr merged commit dd3d118 into main Jul 28, 2026
5 checks passed
@abrichr
abrichr deleted the docs/phone-decisions-without-ingress branch July 28, 2026 02:41
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