\
- --bundle bundle \
- --out bundle-v2
-```
-
-`teach` writes `bundle-v2` only if the correction is promoted. The shipped
-deterministic reference inducer covers the optional-dialog correction class; it
-does not generalize arbitrary UI changes. An underdetermined or safety-weakening
-correction is refused and the original bundle remains halting.
-
-## Move from demo to deployment
-
-Follow [Run a deployment](../guides/run-a-deployment.md) to seal the exact
-bundle, certify it, run a dry check, and start the governed run. A failed
-certification exits `2` and names each violated requirement. Close those gaps
-before another attempt. Do not promote a bundle because the sample application
-passed; complete the [security and deployment review](../guides/security-review.md)
-for the real environment.
-
-## Where to go next
-
-To compile several recordings of the same task, read
-[Induce a program](../guides/induce-a-program.md). A task that starts in one
-application and finishes in another is two recordings. Don't record them as
-one. Sequence the compiled bundles with `compose`, or after each child is
-admitted, with a process parent:
+Claude Code and Cursor can talk to OpenAdapt over MCP after `openadapt` is
+on this machine. ChatGPT.com can't. Don't send a hosted chat your
+passwords.
```bash
-openadapt flow compose \
- --child intake=./intake-bundle \
- --child posting=./posting-bundle \
- --handoff intake.patient_id=posting.patient_id \
- --out composed
-```
-
-`visualize composed` draws those two children and the `patient_id` handoff.
-Each child stays its own compiled program:
-
-```mermaid
-flowchart TD
- n0(["intake
web"])
- n1(["posting
linux"])
- n2{{"End of declared steps"}}
- n0 --> n1
- n1 --> n2
- n0 -->|patient_id| n1
+claude mcp add openadapt -- \
+ uvx --from 'openadapt-agent[tutorial]' openadapt-agent \
+ serve --allow-run
```
-See [Sequence work across two applications](../guides/compose-multi-application.md)
-and [Read a compiled program](../concepts/program-visualizer.md).
-[Durable runs](../concepts/durable-runtime.md) explains how an operator can
-resume from the last verified checkpoint after a halt.
-
-
-
-- [__Author a workflow__](first-workflow.md)
-
- Record a read-only task with test data, review it, supervise its first
- replay, and inspect the report.
-
-- [__What you get__](what-you-get.md)
-
- The bundle, the run report, and what each artifact is for.
-
-- [__Read a compiled program__](../concepts/program-visualizer.md)
-
- The program map, a composed parent, and a process parent.
-
-- [__Qualification evidence__](what-works-today.md)
+`--allow-run` is an explicit opt-in. Halt, refused, timeout, and error come
+back as those outcomes. Never summarize halt as success.
- Accepted substrate results, exact environments, and deployment boundaries.
+The machine contract is in [agents.txt](../agents.txt).
-- [__Core concepts__](../concepts/index.md)
+## Next
- Understand the compiler model before you deploy it for real work.
+Author one real read-only task on your own app in
+[Author a workflow](first-workflow.md). Start with a lookup that doesn't
+change business data.
-
+More Desktop setup is in [Install Desktop](../desktop/install.md).
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
index 87566a4..a67198c 100644
--- a/docs/getting-started/index.md
+++ b/docs/getting-started/index.md
@@ -1,6 +1,6 @@
---
title: Getting started moved
-description: Install OpenAdapt and run the current record, compile, replay tutorial.
+description: Install OpenAdapt on this computer, then continue at Get started.
canonical: https://docs.openadapt.ai/get-started/
redirect_to: /get-started/
hide:
@@ -10,14 +10,15 @@ hide:
# Getting started moved
-This URL is from an older docs tree. Start at [Get started](/get-started/).
+This URL is from an older docs tree. Install first, then continue at
+[Get started](/get-started/).
```bash
-pip install openadapt
-openadapt quickstart
-openadapt quickstart --break-it
+python -m pip install --upgrade openadapt
```
-`openadapt quickstart` records a demonstration, compiles it, and replays the program. `--break-it` is the halt demo. For your own app, use `openadapt flow record`, `compile`, and `replay`.
+The bundled tutorial (`openadapt quickstart`, then optionally
+`openadapt quickstart --break-it`) is optional. For your own app, see
+[Author a workflow](/get-started/first-workflow/).
[Continue to Get started](/get-started/){ .md-button .md-button--primary }
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 6848863..3a8bc14 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -1,6 +1,6 @@
---
title: Installation moved
-description: Install OpenAdapt with pip, then run the current tutorial.
+description: Install OpenAdapt with Desktop or pip, then continue at Get started.
canonical: https://docs.openadapt.ai/get-started/
redirect_to: /get-started/
hide:
@@ -10,13 +10,13 @@ hide:
# Installation moved
-Install the current package, then run the tutorial:
+Install the current package, then continue at
+[Get started](/get-started/). Tutorial is optional.
```bash
-pip install openadapt
-openadapt quickstart
+python -m pip install --upgrade openadapt
```
-The same `openadapt` command drives `openadapt flow record`, `compile`, and `replay`. Details are on [Get started](/get-started/).
+Desktop works too: [openadapt.ai/download](https://openadapt.ai/download).
[Continue to Get started](/get-started/){ .md-button .md-button--primary }
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index 484cd83..ba6a2e2 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -1,6 +1,6 @@
---
title: Quick Start moved
-description: Record a GUI workflow, compile it, and replay the program with openadapt flow.
+description: Install OpenAdapt on this computer, then continue at Get started.
canonical: https://docs.openadapt.ai/get-started/
redirect_to: /get-started/
hide:
@@ -10,21 +10,13 @@ hide:
# Quick Start moved
-The current first run is at [Get started](/get-started/).
+The current first run is install, then [Get started](/get-started/).
```bash
-pip install openadapt
-openadapt quickstart
+python -m pip install --upgrade openadapt
```
-That records a bundled demonstration, compiles a program, and replays it locally. A healthy run makes no model API call.
-
-To record your own application:
-
-```bash
-openadapt flow record --backend web --url https://your.app --out rec
-openadapt flow compile rec --out bundle --name my-task
-openadapt flow replay bundle --url https://your.app --headed
-```
+Desktop works too: [openadapt.ai/start](https://openadapt.ai/start).
+Tutorial is optional.
[Continue to Get started](/get-started/){ .md-button .md-button--primary }
diff --git a/docs/index.md b/docs/index.md
index 950c8ca..443bec4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -15,7 +15,7 @@ no model calls. Uncertainty escalates. Humans audit. Computer-use agents are
the user of OpenAdapt. They are not the executor inside it.
-[Call it from an agent](get-started/index.md){ .md-button .md-button--primary }
+[Install OpenAdapt](get-started/index.md){ .md-button .md-button--primary }
[See how the compiler works](concepts/demonstration-compiler.md){ .md-button }
[Author a workflow](get-started/first-workflow.md){ .md-button }
@@ -158,10 +158,9 @@ report determine its outcome.
-- [__Call it from an agent__](get-started/index.md)
+- [__Install OpenAdapt__](get-started/index.md)
- `claude mcp add openadapt`, then `openadapt quickstart --break-it`.
- Never summarize halt as success.
+ Desktop or pip on this computer. Tutorial is optional.
- [__Author a workflow__](get-started/first-workflow.md)
diff --git a/docs/llms.txt b/docs/llms.txt
index a1329bb..0bbeaab 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -4,7 +4,7 @@
## Get started
- [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.
+- [Get started](https://docs.openadapt.ai/get-started/): Install with Desktop or `python -m pip install --upgrade openadapt`. Tutorial (`openadapt quickstart`, optionally `openadapt quickstart --break-it`) is optional. Local coding agents can `claude mcp add openadapt` later. Never summarize halt as success. Older `/getting-started/` URLs and the `/start/` alias redirect here. The current CLI after install is `openadapt flow record`, `compile`, `replay`.
- [Qualification evidence](https://docs.openadapt.ai/get-started/what-works-today/): Accepted substrate results, exact environments, and deployment boundaries
- [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
diff --git a/docs/start/index.md b/docs/start/index.md
index 0a8580e..12046ff 100644
--- a/docs/start/index.md
+++ b/docs/start/index.md
@@ -1,6 +1,6 @@
---
title: Start moved
-description: Install OpenAdapt and run the current record, compile, replay tutorial.
+description: Install OpenAdapt on this computer, then continue at Get started.
canonical: https://docs.openadapt.ai/get-started/
redirect_to: /get-started/
search:
@@ -12,12 +12,15 @@ hide:
# Start moved
-This URL is an alias. The walkthrough is [Get started](/get-started/).
+This URL is an alias. Install first. The walkthrough is
+[Get started](/get-started/).
```bash
-pip install openadapt
-openadapt quickstart
-openadapt quickstart --break-it
+python -m pip install --upgrade openadapt
```
-The bundled workflow is a tutorial. [Continue to Get started](/get-started/){ .md-button .md-button--primary }
+Desktop works too: [openadapt.ai/start](https://openadapt.ai/start). The
+bundled tutorial (`openadapt quickstart`, then optionally
+`openadapt quickstart --break-it`) is optional.
+
+[Continue to Get started](/get-started/){ .md-button .md-button--primary }
diff --git a/scripts/vendor_design_tokens.py b/scripts/vendor_design_tokens.py
index d046cea..27cb5ec 100644
--- a/scripts/vendor_design_tokens.py
+++ b/scripts/vendor_design_tokens.py
@@ -21,6 +21,8 @@
import json
import os
import sys
+import urllib.error
+import urllib.parse
import urllib.request
from pathlib import Path
@@ -29,24 +31,64 @@
PROVENANCE_PATH = VENDOR_DIR / "provenance.json"
TIMEOUT_SECONDS = 30
+USER_AGENT = "openadapt-ops-vendor-design-tokens"
+API_ROOT = "https://api.github.com"
+
+
+class FetchError(RuntimeError):
+ """A canonical-file fetch failed. --check must not treat this as a match."""
def sha256(payload: bytes) -> str:
return hashlib.sha256(payload).hexdigest()
+def github_token() -> str | None:
+ return os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+
+
+def contents_url(repository: str, path: str, ref: str) -> str:
+ return (
+ f"{API_ROOT}/repos/{repository}/contents/{path}"
+ f"?ref={urllib.parse.quote(ref, safe='')}"
+ )
+
+
def fetch(url: str, accept: str) -> bytes:
- request = urllib.request.Request(url, headers={"Accept": accept})
- token = os.environ.get("GITHUB_TOKEN")
- if token and url.startswith("https://api.github.com/"):
+ headers = {"Accept": accept, "User-Agent": USER_AGENT}
+ request = urllib.request.Request(url, headers=headers)
+ token = github_token()
+ if token and url.startswith(f"{API_ROOT}/"):
request.add_header("Authorization", f"Bearer {token}")
- with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:
- return response.read()
+ try:
+ with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:
+ return response.read()
+ except urllib.error.HTTPError as exc:
+ raise FetchError(f"GET {url} -> HTTP {exc.code}") from exc
+ except urllib.error.URLError as exc:
+ raise FetchError(f"GET {url} -> {exc.reason}") from exc
+ except TimeoutError as exc:
+ raise FetchError(f"GET {url} -> timed out") from exc
+
+
+def fetch_canonical(provenance: dict, entry: dict) -> bytes:
+ # openadapt-web is private, so raw.githubusercontent.com 404s in Actions.
+ # A repo-scoped GITHUB_TOKEN cannot authenticate that host. Use the
+ # Contents API the same way openadapt-desktop does (PR 154).
+ token = github_token()
+ if token:
+ url = contents_url(
+ provenance["canonical_repository"],
+ entry["canonical_path"],
+ provenance["canonical_branch"],
+ )
+ return fetch(url, "application/vnd.github.raw")
+ return fetch(entry["raw_url"], "text/plain")
def canonical_commit(provenance: dict) -> str:
url = (
- f"https://api.github.com/repos/{provenance['canonical_repository']}"
+ f"{API_ROOT}/repos/{provenance['canonical_repository']}"
f"/commits/{provenance['canonical_branch']}"
)
return json.loads(fetch(url, "application/vnd.github+json"))["sha"]
@@ -76,7 +118,11 @@ def main() -> int:
f"{entry['canonical_path']} instead."
)
- canonical = fetch(entry["raw_url"], "text/plain")
+ try:
+ canonical = fetch_canonical(provenance, entry)
+ except FetchError as exc:
+ print(f"{name}: {exc}", file=sys.stderr)
+ return 1
canonical_digest = sha256(canonical)
if arguments.write:
diff --git a/tests/test_vendor_design_tokens.py b/tests/test_vendor_design_tokens.py
new file mode 100644
index 0000000..f2f15b6
--- /dev/null
+++ b/tests/test_vendor_design_tokens.py
@@ -0,0 +1,110 @@
+"""Fail-closed fetch for the online half of the design-token guard.
+
+``tests/test_design_tokens.py`` is the offline half. This file covers
+``scripts/vendor_design_tokens.py`` without hitting the network: a mocked
+HTTP 404 must exit non-zero, and a token must send the request to the
+GitHub Contents API rather than raw.githubusercontent.com.
+"""
+
+from __future__ import annotations
+
+import io
+import sys
+import urllib.error
+from email.message import Message
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "scripts"))
+
+import vendor_design_tokens as vendor # noqa: E402
+
+
+CI_WORKFLOW = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
+VENDOR_DIR = ROOT / "docs" / "stylesheets" / "vendor" / "openadapt-web"
+
+
+class FakeResponse:
+ def __init__(self, body: bytes) -> None:
+ self._body = body
+
+ def read(self) -> bytes:
+ return self._body
+
+ def __enter__(self) -> FakeResponse:
+ return self
+
+ def __exit__(self, *args: object) -> None:
+ return None
+
+
+def _http_error(url: str, code: int) -> urllib.error.HTTPError:
+ return urllib.error.HTTPError(
+ url, code, "Not Found", Message(), io.BytesIO(b"")
+ )
+
+
+def test_fetch_raises_on_http_404(mocker) -> None:
+ url = (
+ "https://api.github.com/repos/OpenAdaptAI/openadapt-web"
+ "/contents/styles/tokens.json?ref=main"
+ )
+ mocker.patch.object(
+ vendor.urllib.request,
+ "urlopen",
+ side_effect=_http_error(url, 404),
+ )
+ with pytest.raises(vendor.FetchError, match="HTTP 404"):
+ vendor.fetch(url, "application/vnd.github.raw")
+
+
+def test_check_returns_nonzero_when_canonical_fetch_404s(
+ monkeypatch, mocker, capsys
+) -> None:
+ monkeypatch.setenv("GITHUB_TOKEN", "test-token")
+ monkeypatch.setattr(sys, "argv", ["vendor_design_tokens.py", "--check"])
+
+ def fake_urlopen(request, timeout=None):
+ raise _http_error(request.full_url, 404)
+
+ mocker.patch.object(vendor.urllib.request, "urlopen", side_effect=fake_urlopen)
+
+ assert vendor.main() == 1
+ captured = capsys.readouterr()
+ assert "HTTP 404" in captured.err
+ assert "Vendored design tokens match" not in captured.out
+ assert "/contents/styles/tokens.json" in captured.err
+
+
+def test_check_uses_contents_api_when_token_is_set(monkeypatch, mocker) -> None:
+ monkeypatch.setenv("GITHUB_TOKEN", "test-token")
+ monkeypatch.setattr(sys, "argv", ["vendor_design_tokens.py", "--check"])
+ requested: list[str] = []
+ authed: list[bool] = []
+
+ def fake_urlopen(request, timeout=None):
+ url = request.full_url
+ requested.append(url)
+ authed.append(request.has_header("Authorization"))
+ if "raw.githubusercontent.com" in url:
+ raise _http_error(url, 404)
+ if "/contents/styles/tokens.json" in url:
+ return FakeResponse((VENDOR_DIR / "tokens.json").read_bytes())
+ if "/contents/styles/tokens.css" in url:
+ return FakeResponse((VENDOR_DIR / "tokens.css").read_bytes())
+ raise _http_error(url, 404)
+
+ mocker.patch.object(vendor.urllib.request, "urlopen", side_effect=fake_urlopen)
+
+ assert vendor.main() == 0
+ assert any("/contents/styles/tokens.json" in url for url in requested)
+ assert any("/contents/styles/tokens.css" in url for url in requested)
+ assert not any("raw.githubusercontent.com" in url for url in requested)
+ assert all(authed)
+
+
+def test_ci_job_still_runs_check_and_reads_private_web_with_admin_token() -> None:
+ assert "python scripts/vendor_design_tokens.py --check" in CI_WORKFLOW
+ assert "secrets.ADMIN_TOKEN || github.token" in CI_WORKFLOW