diff --git a/docs/agents.txt b/docs/agents.txt new file mode 100644 index 0000000..cfed266 --- /dev/null +++ b/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. diff --git a/docs/get-started/first-workflow.md b/docs/get-started/first-workflow.md index 5d2dc96..ca3098e 100644 --- a/docs/get-started/first-workflow.md +++ b/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 diff --git a/docs/get-started/index.md b/docs/get-started/index.md index a2613b5..5d8f588 100644 --- a/docs/get-started/index.md +++ b/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.
-- [__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. diff --git a/docs/index.md b/docs/index.md index fc6a5e1..950c8ca 100644 --- a/docs/index.md +++ b/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

-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.

-[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.
-- [__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) diff --git a/docs/llms.txt b/docs/llms.txt index 9399b96..a1329bb 100644 --- a/docs/llms.txt +++ b/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) diff --git a/mkdocs.yml b/mkdocs.yml index 15fc40e..ccee499 100644 --- a/mkdocs.yml +++ b/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: diff --git a/scripts/validate_docs.py b/scripts/validate_docs.py index 261dbff..527f559 100644 --- a/scripts/validate_docs.py +++ b/scripts/validate_docs.py @@ -12,7 +12,11 @@ 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", @@ -20,6 +24,8 @@ "--break-it", "tutorial", "first-workflow.md", + "claude mcp add openadapt", + "Never summarize halt as success", ), "get-started/what-works-today.md": ( "Qualification evidence", diff --git a/tests/test_validate_docs.py b/tests/test_validate_docs.py index 174fb1a..15e5c0b 100644 --- a/tests/test_validate_docs.py +++ b/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)." ),