docs: default reader is the calling agent

docs/agents.txt

@@ -0,0 +1,44 @@
+# OpenAdapt docs — agents.txt
+
+> Verified last-mile execution for agents. Compile a demonstration into a program an agent can invoke. Healthy runs make no model calls. Uncertainty escalates. Humans audit.
+
+Computer-use agents are the user of OpenAdapt. They are not the executor inside OpenAdapt.
+
+Site-wide machine contract: https://openadapt.ai/agents.txt
+Walkthrough: https://docs.openadapt.ai/get-started/
+Author a workflow (human authority): https://docs.openadapt.ai/get-started/first-workflow/
+Run outcomes: https://docs.openadapt.ai/reference/run-outcomes/
+
+## How to call
+
+```
+claude mcp add openadapt -- \
+  uvx --from 'openadapt-agent[tutorial]' openadapt-agent \
+  serve --allow-run
+```
+
+```
+python -m pip install --upgrade openadapt
+openadapt quickstart
+openadapt quickstart --break-it
+```
+
+`--allow-run` is an explicit opt-in. Never summarize halt as success.
+
+## Outcome vocabulary
+
+`VERIFIED` | `HALTED` | `RECONCILIATION_REQUIRED` | `REFUSED` | `TIMEOUT` | `ERROR`
+
+`VERIFIED` means the independent check passed. Halt is not success. If delivery is uncertain after an action may have been dispatched, the outcome is `RECONCILIATION_REQUIRED`. Do not blindly retry.
+
+Read `report.json` and the seal. `REPORT.md` is for humans.
+
+## Escalation
+
+Halt packets with typed agent-continue are not shipped this week.
+
+- Missing declared parameter: calling agent, if the schema allows it.
+- Retryable transport: agent, inside policy, same idempotency key.
+- Identity, effect contradiction, expired policy, novel UI, admission: human.
+
+Do not resolve identity or effect contradictions yourself. Do not fabricate a success path.

docs/get-started/first-workflow.md

@@ -6,7 +6,10 @@ first_workflow_scope: read_only
 first_write_admission: qualification_required
 ---
 
-# Your first workflow
+# Author a workflow
+
+This is authority work. A named human demonstrates the task once. An agent
+operates the compiled program later.
 
 Choose one small real task that doesn't change business data. A read-only lookup
 against test data works well. Open a known test record, then stop when a field

docs/get-started/index.md

@@ -6,8 +6,34 @@ description: >-
 
 # Get started
 
-You need no account, target application, API key, or operating-system
-automation permission. Python 3.10 through 3.12.
+The default reader is the calling agent. A named human authors the program
+and resolves identity, effect, and judgment halts. You need no account, target
+application, API key, or operating-system automation permission. Python 3.10
+through 3.12.
+
+Point Claude Code or Cursor at the local server:
+
+```bash
+claude mcp add openadapt -- \
+  uvx --from 'openadapt-agent[tutorial]' openadapt-agent \
+  serve --allow-run
+```
+
+`--allow-run` is an explicit opt-in. The server generates the public synthetic
+tutorial at serve time. Halt, refused, timeout, and error come back as those
+outcomes. Never summarize halt as success.
+
+!!! info "What the calling agent may do / must not do"
+    **May:** bind declared parameters, invoke the compiled program, read
+    typed outcomes, supply a missing declared parameter, retry a retryable
+    transport failure, escalate to a human.
+
+    **Must not:** summarize halt as success, resolve identity or effect
+    contradictions, or be the sole source of a production demonstration.
+
+    Full contract: [agents.txt](../agents.txt).
+
+Same loop from the CLI:
 
 ```bash
 python -m pip install --upgrade openadapt
@@ -107,7 +133,7 @@ Start with one real, read-only task. Don't start with a write.
 
 | Goal | Next guide |
 |---|---|
-| Record one real, read-only browser workflow | [Your first workflow](first-workflow.md) |
+| Author one real, read-only browser workflow | [Author a workflow](first-workflow.md) |
 | See what the compiled program looks like | [Read a compiled program](../concepts/program-visualizer.md) |
 | Bind identity, effects, faults, and policy | [Qualify a workflow](../guides/qualify-a-workflow.md) |
 | Use the Desktop application | [Install Desktop](../desktop/install.md) |
@@ -133,7 +159,7 @@ Want to watch before you record your own app?
 
 ## First real (read-only) workflow
 
-[Your first workflow](first-workflow.md) records one small real task that
+[Author a workflow](first-workflow.md) records one small real task that
 doesn't change business data. A read-only lookup against test data works.
 Open a known test record, then stop when a field shows the expected value.
 
@@ -245,7 +271,7 @@ resume from the last verified checkpoint after a halt.
 
 <div class="grid cards" markdown>
 
--   [__Your first workflow__](first-workflow.md)
+-   [__Author a workflow__](first-workflow.md)
 
     Record a read-only task with test data, review it, supervise its first
     replay, and inspect the report.

docs/index.md

@@ -1,33 +1,43 @@
 ---
 title: OpenAdapt documentation
 description: >-
-  Learn how OpenAdapt turns demonstrated browser, desktop, RDP, and Citrix
-  work into deterministic programs with explicit identity and result checks.
+  Verified last-mile execution for agents. Compile a demonstration into a
+  program an agent can invoke. Healthy runs make no model calls.
 hide:
   - toc
 ---
 
-# Verified automation from demonstration
+# Verified last-mile execution for agents
 
 <p class="oa-lede">
-Show OpenAdapt a repeated task. It compiles the demonstration into a
-deterministic program for browser, desktop, RDP, or Citrix, then checks the
-declared result before it reports success. A healthy run makes no
-generative-model API calls. If OpenAdapt cannot verify the result, the run
-stops with evidence for review.
+Compile a demonstration into a program an agent can invoke. Healthy runs make
+no model calls. Uncertainty escalates. Humans audit. Computer-use agents are
+the user of OpenAdapt. They are not the executor inside it.
 </p>
 
-[Run it locally](get-started/index.md){ .md-button .md-button--primary }
+[Call it from an agent](get-started/index.md){ .md-button .md-button--primary }
 [See how the compiler works](concepts/demonstration-compiler.md){ .md-button }
-[Review a workflow](https://openadapt.ai/qualify){ .md-button }
+[Author a workflow](get-started/first-workflow.md){ .md-button }
+
+!!! info "What the calling agent may do / must not do"
+    **May:** bind declared parameters, invoke a compiled program, read
+    `VERIFIED` / `HALTED` / `RECONCILIATION_REQUIRED`, supply a missing
+    declared parameter, retry a retryable transport failure, escalate.
+
+    **Must not:** summarize halt as success, resolve an identity or effect
+    contradiction, teach by emitting guessed clicks, or be the sole source of
+    a production demonstration.
+
+    Machine contract: [agents.txt](agents.txt). Outcome vocab:
+    [Run outcomes](reference/run-outcomes.md).
 
 ---
 
 ## Where OpenAdapt fits
 
-OpenAdapt handles repeated work that still requires a person to operate an
-application. Teams often use it for the final interface step after their input
-and business rules already exist.
+OpenAdapt is the governed last mile an agent calls when the next write has no
+API. A named human authors the program once. The calling agent operates it.
+The human returns for identity, effect, and judgment halt, then samples seals.
 
 A strong first workflow has these traits:
 
@@ -40,7 +50,7 @@ A strong first workflow has these traits:
 
 OpenAdapt supports automation teams, BPOs, service providers, and software
 companies that operate browser, native desktop, RDP, Citrix, or other virtual
-desktop applications.
+desktop applications. The daily user is the agent those teams already run.
 
 ---
 
@@ -80,7 +90,7 @@ desktop applications.
 
 ```mermaid
 flowchart LR
-    A([Demonstrate]) --> B[[Compile]]
+    A([Author]) --> B[[Compile]]
     B --> C[[Qualify]]
     C --> D[[Run]]
     D --> E{Result verified?}
@@ -148,14 +158,15 @@ report determine its outcome.
 
 <div class="grid cards" markdown>
 
--   [__Try the local tutorial__](get-started/index.md)
+-   [__Call it from an agent__](get-started/index.md)
 
-    Install OpenAdapt, run `openadapt quickstart`, then
-    `openadapt quickstart --break-it`.
+    `claude mcp add openadapt`, then `openadapt quickstart --break-it`.
+    Never summarize halt as success.
 
--   [__Record your application__](get-started/first-workflow.md)
+-   [__Author a workflow__](get-started/first-workflow.md)
 
-    Capture one browser workflow, compile it, run it, and inspect the report.
+    A named human captures one browser workflow, compiles it, runs it, and
+    inspects the report. Authority, not daily operator.
 
 -   [__Prepare a production workflow__](guides/qualify-a-workflow.md)
 

docs/llms.txt

@@ -1,11 +1,12 @@
 # OpenAdapt Documentation
 
-> Official documentation for OpenAdapt, an open-source demonstration compiler for repeated GUI work. Record a GUI workflow once and compile it into deterministic replay: healthy runs are local and make no generative-model API calls; under UI drift the runtime re-resolves from retained evidence, proposes governed repairs, accepts human teaching, or halts rather than guess. MIT licensed.
+> Verified last-mile execution for agents. Compile a demonstration into a program an agent can invoke. Healthy runs make no model calls. Uncertainty escalates. Humans audit. Computer-use agents are the user of OpenAdapt. They are not the executor inside it. Never summarize halt as success. MIT licensed.
 
 ## Get started
-- [Get started](https://docs.openadapt.ai/get-started/): Run `pip install openadapt`, then `openadapt quickstart`, then `openadapt quickstart --break-it`. The bundled workflow is a tutorial. The current CLI is `openadapt flow record`, `compile`, `replay`. Older `/getting-started/` URLs and the `/start/` alias redirect here.
+- [agents.txt](https://docs.openadapt.ai/agents.txt): MCP, skills, outcome vocabulary (`VERIFIED` / `HALTED` / `RECONCILIATION_REQUIRED`), who may resolve a halt
+- [Get started](https://docs.openadapt.ai/get-started/): `claude mcp add openadapt`, then `openadapt quickstart`, then `openadapt quickstart --break-it`. The bundled workflow is a tutorial. The current CLI is `openadapt flow record`, `compile`, `replay`. Older `/getting-started/` URLs and the `/start/` alias redirect here.
 - [Qualification evidence](https://docs.openadapt.ai/get-started/what-works-today/): Accepted substrate results, exact environments, and deployment boundaries
-- [Your first workflow](https://docs.openadapt.ai/get-started/first-workflow/): Install the base package, then record, compile, lint, replay, and read the report on your own web app
+- [Author a workflow](https://docs.openadapt.ai/get-started/first-workflow/): A named human records, compiles, lints, replays, and reads the report on your own web app. Authority, not daily operator.
 - [What you get](https://docs.openadapt.ai/get-started/what-you-get/): The workflow bundle, the run report, and what each artifact is for
 - [The Seal](https://docs.openadapt.ai/commercial/seal/): Signed proof of a verified, halted, or reconciling run. `openadapt-flow replay bundle --seal`. Public verify at `https://openadapt.ai/seals/{id}` (synthetic only)
 

mkdocs.yml

@@ -131,7 +131,7 @@ nav:
   - Home: index.md
   - Start:
     - get-started/index.md
-    - Your first workflow: get-started/first-workflow.md
+    - Author a workflow: get-started/first-workflow.md
     - What you get: get-started/what-you-get.md
     - Desktop application: desktop/install.md
   - Build:

scripts/validate_docs.py

@@ -12,14 +12,20 @@
 MKDOCS_FILE = ROOT / "mkdocs.yml"
 
 REQUIRED_PUBLIC_PAGES = {
-    "index.md": ("reference/production-lifecycle.md",),
+    "index.md": (
+        "reference/production-lifecycle.md",
+        "Verified last-mile execution for agents",
+        "calling agent",
+    ),
     "ecosystem/index.md": ("data-openadapt-production-target",),
     "get-started/index.md": (
         "pip install",
         "openadapt quickstart",
         "--break-it",
         "tutorial",
         "first-workflow.md",
+        "claude mcp add openadapt",
+        "Never summarize halt as success",
     ),
     "get-started/what-works-today.md": (
         "Qualification evidence",

tests/test_validate_docs.py

@@ -58,8 +58,8 @@ def test_check_empty_pages_nested(tmp_path):
 def _write_contract_docs(root):
     pages = {
         "index.md": (
-            "# OpenAdapt\n\nShow it a repeated workflow. OpenAdapt compiles it "
-            "into governed, deterministic replay. "
+            "# Verified last-mile execution for agents\n\nThe default reader "
+            "is the calling agent. "
             "[Production status](reference/production-lifecycle.md)"
         ),
         "ecosystem/index.md": (
@@ -83,6 +83,7 @@ def _write_contract_docs(root):
         "get-started/index.md": (
             "# Get started\n\nInstall with `pip install openadapt`, then "
             "`openadapt quickstart` and `openadapt quickstart --break-it`. "
+            "`claude mcp add openadapt`. Never summarize halt as success. "
             "The bundled workflow is a tutorial. Continue in "
             "[Your first workflow](first-workflow.md)."
         ),