docs: name the three roles and default runtime interface

README.md

@@ -7,7 +7,11 @@
 
 OpenAdapt is a compiled program for GUI writes with no API. This package invokes it over MCP.
 
-Flow still runs the program. Policy, identity, verification, pauses, repair, and audit stay in [`openadapt-flow`](https://github.com/OpenAdaptAI/openadapt-flow). A healthy call goes through Flow's governed `run`. HALTED, refused, timeout, and error come back as those outcomes. Don't summarize any of them as success.
+This package is the default runtime interface for a calling agent. The CLI remains. Headless does not mean the UI is gone.
+
+Three roles: the calling agent operates; a named human is authority; compliance samples seals. Computer-use agents are the user of OpenAdapt. They are not the executor inside OpenAdapt.
+
+Flow still runs the program. Policy, identity, verification, pauses, repair, and audit stay in [`openadapt-flow`](https://github.com/OpenAdaptAI/openadapt-flow). A healthy call goes through Flow's governed `run`. HALTED, refused, timeout, and error come back as those outcomes. Don't summarize any of them as success. Never summarize halt as success.
 
 ## Install
 

docs/DESIGN.md

@@ -7,14 +7,32 @@ older admission or assign a fallback lifecycle label.
 
 OpenAdapt is a compiled program for GUI writes with no API. This package invokes it over MCP.
 
+`openadapt-agent` is the default runtime interface for a calling agent. It
+is not a second workflow engine, and it is not "OpenAdapt the agent." Flow
+owns compilation, policy, identity, verification, durable execution, repair,
+and audit. The CLI remains. Headless does not mean the UI is gone.
+
+## Roles
+
+| Role | Who | What they do |
+|---|---|---|
+| Operator | Calling agent (Claude Code, MCP client, orchestrator) | Discover, bind parameters, invoke, read outcomes |
+| Authority | Named human | Demonstrate once, certify policy, resolve identity / effect / judgment halts |
+| Auditor | Compliance | Sample seals, revoke admission |
+
+Computer-use agents are the user of OpenAdapt. They are not the executor
+inside OpenAdapt. Never summarize halt as success.
+
+Halt packets and typed agent-continue (missing parameter / retryable
+transport only) are not in this package yet. Identity, effect, expired
+policy, novel UI, and admission still require a human. Do not let a
+planner resolve those classes.
+
 `openadapt-agent` exposes two complementary interfaces:
 
 1. MCP tools over local stdio.
 2. Portable Agent Skills.
 
-It is not a second workflow engine. Flow owns compilation, policy,
-identity, verification, durable execution, repair, and audit.
-
 ## Architecture
 
 ```text

llms.txt

@@ -2,6 +2,8 @@
 
 > OpenAdapt is a compiled program for GUI writes with no API. This package invokes it over MCP.
 
+Default runtime interface for a calling agent. Computer-use agents are the user of OpenAdapt. They are not the executor inside it. Never summarize halt as success. Roles: operator (calling agent), authority (named human), auditor (samples seals).
+
 ## What it provides
 
 - `openadapt-agent serve --allow-run`: generate and serve the public synthetic tutorial at serve time. `openadapt-agent serve --tutorial` is the same path without run tools. `openadapt-agent serve --bundles <dir> [--allow-run]`: serve a private compiled bundle. `list_workflows`, `get_workflow`, `get_run_report`, `list_needs_attention`, and `get_attention_item` are always available as PHI-safe read-only projections. `run_workflow_<opaque-id>` tools require `--allow-run`. The synthetic tutorial registers `run_local_quickstart`. If a run returns HALTED, tell the user the record did not change. Never summarize halt, refused, timeout, or error as success.