diff --git a/docs/LEGACY_FREEZE.md b/docs/LEGACY_FREEZE.md new file mode 100644 index 00000000..33f8905a --- /dev/null +++ b/docs/LEGACY_FREEZE.md @@ -0,0 +1,22 @@ +--- +title: Legacy freeze notice +description: Historical docs URL. The current first run is openadapt quickstart and openadapt flow. +canonical: https://docs.openadapt.ai/get-started/ +redirect_to: /get-started/ +hide: + - navigation + - toc +--- + +# Legacy freeze notice + +This URL is historical. It described an older codebase freeze. The current first run is: + +```bash +pip install openadapt +openadapt quickstart +``` + +That records a demonstration, compiles a program, and replays it. Continue at [Get started](/get-started/). + +[Continue to Get started](/get-started/){ .md-button .md-button--primary } diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 00000000..a127a485 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,15 @@ +--- +title: Architecture moved +description: The current compiler model lives under Concepts, not a package-first architecture page. +canonical: https://docs.openadapt.ai/concepts/ +redirect_to: /concepts/ +hide: + - navigation + - toc +--- + +# Architecture moved + +The current compiler model is under [Concepts](/concepts/). OpenAdapt records a GUI workflow, compiles it, and replays the program. Start with [the demonstration compiler](/concepts/demonstration-compiler/) or the [product components](/ecosystem/) catalog. + +[Continue to Concepts](/concepts/){ .md-button .md-button--primary } diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 00000000..3c2cca89 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,22 @@ +--- +title: CLI moved +description: The current command surface is openadapt flow. See the CLI reference. +canonical: https://docs.openadapt.ai/reference/cli/ +redirect_to: /reference/cli/ +hide: + - navigation + - toc +--- + +# CLI moved + +The current command surface is `openadapt flow`. Every verb is in the [openadapt flow CLI](/reference/cli/) reference. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the verbs for a first workflow. The local tutorial is on [Get started](/get-started/). + +[Continue to the CLI reference](/reference/cli/){ .md-button .md-button--primary } diff --git a/docs/ecosystem/index.md b/docs/ecosystem/index.md index e257ff1f..e096fec4 100644 --- a/docs/ecosystem/index.md +++ b/docs/ecosystem/index.md @@ -47,8 +47,8 @@ Flow accepts its recording. | Repository | Lifecycle | Public role | |---|---|---| -| [openadapt-ml](https://github.com/OpenAdaptAI/openadapt-ml) | **Research** | Optional VLM training, inference, and demonstration-conditioning work. The healthy compiler path does not require it. | -| [openadapt-evals](https://github.com/OpenAdaptAI/openadapt-evals) | **Research** | GUI workflow and demonstration-conditioning evaluation infrastructure. | +| [openadapt-ml](https://github.com/OpenAdaptAI/openadapt-ml) | **Research** | Optional model-training research. Recording, compiling, and replaying a workflow does not use it. | +| [openadapt-evals](https://github.com/OpenAdaptAI/openadapt-evals) | **Research** | GUI workflow evaluation research. The compiler path does not depend on it. | | [openadapt-grounding](https://github.com/OpenAdaptAI/openadapt-grounding) | **Research** | UI grounding mechanisms and model adapters. | | [openadapt-retrieval](https://github.com/OpenAdaptAI/openadapt-retrieval) | **Research** | Demonstration retrieval mechanisms. | diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md new file mode 100644 index 00000000..c9701d53 --- /dev/null +++ b/docs/getting-started/index.md @@ -0,0 +1,22 @@ +--- +title: Getting started moved +description: Install OpenAdapt and run the current record, compile, replay tutorial. +canonical: https://docs.openadapt.ai/get-started/ +redirect_to: /get-started/ +hide: + - navigation + - toc +--- + +# Getting started moved + +This URL is from an older docs tree. Start at [Get started](/get-started/). + +```bash +pip install openadapt +openadapt quickstart +``` + +`openadapt quickstart` records a demonstration, compiles it, and replays the program. For your own app, use `openadapt flow record`, `compile`, and `replay`. + +[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 new file mode 100644 index 00000000..68488632 --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,22 @@ +--- +title: Installation moved +description: Install OpenAdapt with pip, then run the current tutorial. +canonical: https://docs.openadapt.ai/get-started/ +redirect_to: /get-started/ +hide: + - navigation + - toc +--- + +# Installation moved + +Install the current package, then run the tutorial: + +```bash +pip install openadapt +openadapt quickstart +``` + +The same `openadapt` command drives `openadapt flow record`, `compile`, and `replay`. Details are on [Get started](/get-started/). + +[Continue to Get started](/get-started/){ .md-button .md-button--primary } diff --git a/docs/getting-started/permissions.md b/docs/getting-started/permissions.md new file mode 100644 index 00000000..21c4ae95 --- /dev/null +++ b/docs/getting-started/permissions.md @@ -0,0 +1,22 @@ +--- +title: Permissions moved +description: Grant screen recording and accessibility permissions in the Desktop install guide. +canonical: https://docs.openadapt.ai/desktop/install/ +redirect_to: /desktop/install/ +hide: + - navigation + - toc +--- + +# Permissions moved + +OS permission steps now live in [Desktop app: install and first run](/desktop/install/). Grant Screen Recording and Accessibility before you record, or the capture comes out blank. + +The command-line first run does not need those permissions: + +```bash +pip install openadapt +openadapt quickstart +``` + +[Continue to the Desktop install guide](/desktop/install/){ .md-button .md-button--primary } diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 9fa05009..484cd83f 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -1,6 +1,6 @@ --- title: Quick Start moved -description: The current OpenAdapt quickstart uses the deterministic demonstration compiler. +description: Record a GUI workflow, compile it, and replay the program with openadapt flow. canonical: https://docs.openadapt.ai/get-started/ redirect_to: /get-started/ hide: @@ -10,10 +10,21 @@ hide: # Quick Start moved -The current quickstart is at [Get started](/get-started/). +The current first run is at [Get started](/get-started/). -It uses the canonical `openadapt quickstart` command to record, compile, check, -and replay a bundled synthetic workflow locally. It does not use the legacy -model-training path. +```bash +pip install openadapt +openadapt quickstart +``` -[Continue to the current quickstart →](/get-started/){ .md-button .md-button--primary } +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 +``` + +[Continue to Get started](/get-started/){ .md-button .md-button--primary } diff --git a/docs/legacy/freeze.md b/docs/legacy/freeze.md new file mode 100644 index 00000000..714c6872 --- /dev/null +++ b/docs/legacy/freeze.md @@ -0,0 +1,20 @@ +--- +title: Legacy freeze notice +description: Historical docs URL. The current first run is openadapt quickstart and openadapt flow. +canonical: https://docs.openadapt.ai/get-started/ +redirect_to: /get-started/ +hide: + - navigation + - toc +--- + +# Legacy freeze notice + +This URL is historical. The current product compiles a demonstrated workflow into a program you can inspect and replay: + +```bash +pip install openadapt +openadapt quickstart +``` + +[Continue to Get started](/get-started/){ .md-button .md-button--primary } diff --git a/docs/llms.txt b/docs/llms.txt index 2736c8c0..f29cfc86 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -3,7 +3,7 @@ > 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. ## Get started -- [Get started](https://docs.openadapt.ai/get-started/): Run `pip install openadapt`, then `openadapt quickstart` for a complete local, effect-verified tutorial +- [Get started](https://docs.openadapt.ai/get-started/): Run `pip install openadapt`, then `openadapt quickstart` for a complete local, effect-verified tutorial. The current CLI is `openadapt flow record`, `compile`, `replay`. Older `/getting-started/` and package-mirror URLs 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 - [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/packages/capture.md b/docs/packages/capture.md new file mode 100644 index 00000000..6dc680c4 --- /dev/null +++ b/docs/packages/capture.md @@ -0,0 +1,22 @@ +--- +title: openadapt-capture documentation moved +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-capture documentation moved + +Native capture is a product component. Drive it through `openadapt flow record` on a native, RDP, or Citrix backend. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/evals.md b/docs/packages/evals.md new file mode 100644 index 00000000..3a598a39 --- /dev/null +++ b/docs/packages/evals.md @@ -0,0 +1,22 @@ +--- +title: openadapt-evals is Research +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-evals is Research + +This repository is Research evaluation infrastructure. The compiler path does not depend on it. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/grounding.md b/docs/packages/grounding.md new file mode 100644 index 00000000..e58032e3 --- /dev/null +++ b/docs/packages/grounding.md @@ -0,0 +1,22 @@ +--- +title: openadapt-grounding is Research +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-grounding is Research + +This repository is Research. Recording, compiling, and replaying a workflow does not use it. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/index.md b/docs/packages/index.md new file mode 100644 index 00000000..ea5fd12b --- /dev/null +++ b/docs/packages/index.md @@ -0,0 +1,22 @@ +--- +title: Package catalog moved +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# Package catalog moved + +Package pages from the older docs tree now live in one catalog. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/ml.md b/docs/packages/ml.md new file mode 100644 index 00000000..9023c9c2 --- /dev/null +++ b/docs/packages/ml.md @@ -0,0 +1,22 @@ +--- +title: openadapt-ml is Research +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-ml is Research + +This repository is Research. It is not required to record, compile, or replay a workflow. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt-agent.md b/docs/packages/openadapt-agent.md index c1e61c91..a478b4c9 100644 --- a/docs/packages/openadapt-agent.md +++ b/docs/packages/openadapt-agent.md @@ -1,6 +1,6 @@ --- title: openadapt-agent documentation moved -description: OpenAdapt package documentation now lives in the canonical product and component guide. +description: Agent is a governed bridge to exact Flow bundles. The current command is openadapt flow. canonical: https://docs.openadapt.ai/ecosystem/ redirect_to: /ecosystem/ hide: @@ -10,7 +10,8 @@ hide: # openadapt-agent documentation moved -The current product and component guide lives at -[Package and repository lifecycle](/ecosystem/). +Agent is a governed bridge from MCP clients and Agent Skills to exact Flow bundles. It does not replace `openadapt flow record`, `compile`, and `replay`. -[Continue to the current guide →](/ecosystem/){ .md-button .md-button--primary } +See the [product catalog](/ecosystem/). + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt-bootstrap.md b/docs/packages/openadapt-bootstrap.md new file mode 100644 index 00000000..538ad1c0 --- /dev/null +++ b/docs/packages/openadapt-bootstrap.md @@ -0,0 +1,22 @@ +--- +title: openadapt-bootstrap is Research +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-bootstrap is Research + +This repository is Research. It is not required to record, compile, or replay a workflow. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt-capture.md b/docs/packages/openadapt-capture.md index 59ed0286..ceaa03f0 100644 --- a/docs/packages/openadapt-capture.md +++ b/docs/packages/openadapt-capture.md @@ -1,6 +1,6 @@ --- title: openadapt-capture documentation moved -description: OpenAdapt package documentation now lives in the canonical product and component guide. +description: Native capture feeds openadapt flow. The current command is openadapt flow record. canonical: https://docs.openadapt.ai/ecosystem/ redirect_to: /ecosystem/ hide: @@ -10,7 +10,8 @@ hide: # openadapt-capture documentation moved -The current product and component guide lives at -[Package and repository lifecycle](/ecosystem/). +Native screen, mouse, and keyboard capture is a product component. You reach it through `openadapt flow record` on a native, RDP, or Citrix backend, or through Desktop. The extra is `openadapt[capture,...]` when you install a native driver. -[Continue to the current guide →](/ecosystem/){ .md-button .md-button--primary } +See the [product catalog](/ecosystem/) and [Get started](/get-started/). + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt-desktop.md b/docs/packages/openadapt-desktop.md index 4830acf0..7a58982d 100644 --- a/docs/packages/openadapt-desktop.md +++ b/docs/packages/openadapt-desktop.md @@ -1,6 +1,6 @@ --- title: openadapt-desktop documentation moved -description: OpenAdapt package documentation now lives in the canonical product and component guide. +description: Desktop is the local cockpit for the same record, compile, replay loop as openadapt flow. canonical: https://docs.openadapt.ai/ecosystem/ redirect_to: /ecosystem/ hide: @@ -10,7 +10,8 @@ hide: # openadapt-desktop documentation moved -The current product and component guide lives at -[Package and repository lifecycle](/ecosystem/). +Desktop is the local cockpit for the same engine as `openadapt flow`. It records a workflow, compiles it, and replays the program. It does not collect training data for a model. -[Continue to the current guide →](/ecosystem/){ .md-button .md-button--primary } +Install and first-run steps are in [Desktop app: install and first run](/desktop/install/). Component status is in the [product catalog](/ecosystem/). + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt-evals.md b/docs/packages/openadapt-evals.md new file mode 100644 index 00000000..50c49c19 --- /dev/null +++ b/docs/packages/openadapt-evals.md @@ -0,0 +1,22 @@ +--- +title: openadapt-evals is Research +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-evals is Research + +This repository is Research. Use [Get started](/get-started/) for the compiler path. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt-flow.md b/docs/packages/openadapt-flow.md index 1526ece3..c101b5e5 100644 --- a/docs/packages/openadapt-flow.md +++ b/docs/packages/openadapt-flow.md @@ -1,6 +1,6 @@ --- title: openadapt-flow documentation moved -description: OpenAdapt package documentation now lives in the canonical product and component guide. +description: openadapt-flow is the compiler. End users install openadapt and run openadapt flow. canonical: https://docs.openadapt.ai/ecosystem/ redirect_to: /ecosystem/ hide: @@ -10,7 +10,8 @@ hide: # openadapt-flow documentation moved -The current product and component guide lives at -[Package and repository lifecycle](/ecosystem/). +`openadapt-flow` is the demonstration compiler. End users install `openadapt` and run `openadapt flow record`, `compile`, and `replay`. Engine contributors clone the flow repository. -[Continue to the current guide →](/ecosystem/){ .md-button .md-button--primary } +The product catalog is at [Package and repository lifecycle](/ecosystem/). The first run is on [Get started](/get-started/). + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt-grounding.md b/docs/packages/openadapt-grounding.md new file mode 100644 index 00000000..60fba12b --- /dev/null +++ b/docs/packages/openadapt-grounding.md @@ -0,0 +1,22 @@ +--- +title: openadapt-grounding is Research +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-grounding is Research + +This repository is Research. Grounding for production replay lives in the compiler. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt-ml.md b/docs/packages/openadapt-ml.md new file mode 100644 index 00000000..a9bbcd4f --- /dev/null +++ b/docs/packages/openadapt-ml.md @@ -0,0 +1,22 @@ +--- +title: openadapt-ml is Research +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-ml is Research + +This repository is Research model-training work. The current first run does not train a model. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt-privacy.md b/docs/packages/openadapt-privacy.md index 413ee6a0..ee0c4b1a 100644 --- a/docs/packages/openadapt-privacy.md +++ b/docs/packages/openadapt-privacy.md @@ -1,6 +1,6 @@ --- title: openadapt-privacy documentation moved -description: OpenAdapt package documentation now lives in the canonical product and component guide. +description: Privacy is optional sanitization. The current command surface is openadapt flow. canonical: https://docs.openadapt.ai/ecosystem/ redirect_to: /ecosystem/ hide: @@ -10,7 +10,8 @@ hide: # openadapt-privacy documentation moved -The current product and component guide lives at -[Package and repository lifecycle](/ecosystem/). +Privacy is optional PII/PHI sanitization for configured logs and artifact egress. The current command surface is `openadapt flow`. -[Continue to the current guide →](/ecosystem/){ .md-button .md-button--primary } +See the [product catalog](/ecosystem/). + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt-retrieval.md b/docs/packages/openadapt-retrieval.md new file mode 100644 index 00000000..b89f1209 --- /dev/null +++ b/docs/packages/openadapt-retrieval.md @@ -0,0 +1,22 @@ +--- +title: openadapt-retrieval is Research +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-retrieval is Research + +This repository is Research retrieval work. Start at [Get started](/get-started/) for the compiler path. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt-types.md b/docs/packages/openadapt-types.md index 96402b67..43380c8e 100644 --- a/docs/packages/openadapt-types.md +++ b/docs/packages/openadapt-types.md @@ -1,6 +1,6 @@ --- title: openadapt-types documentation moved -description: OpenAdapt package documentation now lives in the canonical product and component guide. +description: Shared schemas for contributors. The current command surface is openadapt flow. canonical: https://docs.openadapt.ai/ecosystem/ redirect_to: /ecosystem/ hide: @@ -10,7 +10,8 @@ hide: # openadapt-types documentation moved -The current product and component guide lives at -[Package and repository lifecycle](/ecosystem/). +Types are shared interoperability schemas. Contributors and integrators use them. The current command surface is `openadapt flow`. -[Continue to the current guide →](/ecosystem/){ .md-button .md-button--primary } +See the [product catalog](/ecosystem/). + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt-viewer.md b/docs/packages/openadapt-viewer.md new file mode 100644 index 00000000..ecf15c4e --- /dev/null +++ b/docs/packages/openadapt-viewer.md @@ -0,0 +1,22 @@ +--- +title: openadapt-viewer is Research +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-viewer is Research + +This repository is Research. Inspect a run from the report the compiler writes. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/openadapt.md b/docs/packages/openadapt.md index 2f17c706..76b9274d 100644 --- a/docs/packages/openadapt.md +++ b/docs/packages/openadapt.md @@ -1,6 +1,6 @@ --- title: OpenAdapt package documentation moved -description: OpenAdapt package documentation now lives in the canonical product and component guide. +description: Install openadapt and use openadapt flow. Package details live in the product catalog. canonical: https://docs.openadapt.ai/ecosystem/ redirect_to: /ecosystem/ hide: @@ -10,13 +10,14 @@ hide: # OpenAdapt package documentation moved -The product and package guide now lives at -[Package and repository lifecycle](/ecosystem/). The public installation path -is: +The public install is the launcher. After that, the command is `openadapt flow`: ```bash pip install openadapt openadapt flow --help ``` -[Continue to the current guide →](/ecosystem/){ .md-button .md-button--primary } +The first local result is `openadapt quickstart`. Package roles are in the +[product components catalog](/ecosystem/). + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/privacy.md b/docs/packages/privacy.md new file mode 100644 index 00000000..8ad75833 --- /dev/null +++ b/docs/packages/privacy.md @@ -0,0 +1,22 @@ +--- +title: openadapt-privacy documentation moved +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-privacy documentation moved + +Privacy tooling is optional sanitization for configured egress. The current command surface is `openadapt flow`. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/retrieval.md b/docs/packages/retrieval.md new file mode 100644 index 00000000..32672ab0 --- /dev/null +++ b/docs/packages/retrieval.md @@ -0,0 +1,22 @@ +--- +title: openadapt-retrieval is Research +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-retrieval is Research + +This repository is Research. Start at [Get started](/get-started/) for the compiler path. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/packages/viewer.md b/docs/packages/viewer.md new file mode 100644 index 00000000..1c652a4f --- /dev/null +++ b/docs/packages/viewer.md @@ -0,0 +1,22 @@ +--- +title: openadapt-viewer is Research +description: OpenAdapt package documentation now lives in the product and component guide. The current CLI is openadapt flow. +canonical: https://docs.openadapt.ai/ecosystem/ +redirect_to: /ecosystem/ +hide: + - navigation + - toc +--- + +# openadapt-viewer is Research + +This repository is Research visualization work. Inspect a compiled run from the report the compiler writes. + +```bash +pip install openadapt +openadapt flow --help +``` + +Record, compile, and replay are the current verbs. See [Get started](/get-started/) for the first run, or the [product components](/ecosystem/) catalog for how the packages fit. + +[Continue to the current guide](/ecosystem/){ .md-button .md-button--primary } diff --git a/docs/reference/documentation-governance.md b/docs/reference/documentation-governance.md index 4efc4285..a6a571a8 100644 --- a/docs/reference/documentation-governance.md +++ b/docs/reference/documentation-governance.md @@ -40,3 +40,8 @@ Public docs must: expanding them. 6. Keep generated repository material out of top-level navigation; package and research topology belongs under Ecosystem or Reference. +7. Publish `openadapt flow record`, `compile`, and `replay` (or + `openadapt quickstart`) as the current first run. Do not publish + capture-then-train or a model-training CLI as current product + instructions. Research repositories stay listed as Research. Retired + URLs from the old docs tree keep a Flow-first redirect. diff --git a/scripts/sync_readmes.py b/scripts/sync_readmes.py index 7c77b316..3a15a1bb 100644 --- a/scripts/sync_readmes.py +++ b/scripts/sync_readmes.py @@ -2,6 +2,8 @@ import datetime import pathlib +import re + import yaml import requests from jinja2 import Environment, FileSystemLoader @@ -60,6 +62,13 @@ def sync(repos=None, docs_dir=None, templates_dir=None): ) out_path = docs_dir / doc_page + if out_path.exists() and re.search( + r"^redirect_to:\s+", out_path.read_text(), flags=re.MULTILINE + ): + # Curated Flow-first redirects own these URLs. A README mirror + # would republish capture-then-train copy as current product. + print(f"Skipping {name} (canonical redirect stub at {out_path})") + continue out_path.parent.mkdir(parents=True, exist_ok=True) out_path.write_text(rendered) results.append({"name": name, "path": str(out_path), "size": len(readme)}) diff --git a/scripts/validate_docs.py b/scripts/validate_docs.py index 9eba9c48..7824c75f 100644 --- a/scripts/validate_docs.py +++ b/scripts/validate_docs.py @@ -106,6 +106,64 @@ "openadapt", } +# Old docs.openadapt.ai URLs that taught capture-then-train or mirrored a +# research README as if it were the product. Each file must keep serving a +# Flow-first redirect so a crawler that still holds the URL drops the old +# snippet. Do not put these in the nav. +RETIRED_REDIRECTS = { + "architecture.md": "/concepts/", + "cli.md": "/reference/cli/", + "getting-started/index.md": "/get-started/", + "getting-started/installation.md": "/get-started/", + "getting-started/permissions.md": "/desktop/install/", + "getting-started/quickstart.md": "/get-started/", + "LEGACY_FREEZE.md": "/get-started/", + "legacy/freeze.md": "/get-started/", + "packages/capture.md": "/ecosystem/", + "packages/evals.md": "/ecosystem/", + "packages/grounding.md": "/ecosystem/", + "packages/index.md": "/ecosystem/", + "packages/ml.md": "/ecosystem/", + "packages/openadapt-bootstrap.md": "/ecosystem/", + "packages/openadapt-evals.md": "/ecosystem/", + "packages/openadapt-grounding.md": "/ecosystem/", + "packages/openadapt-ml.md": "/ecosystem/", + "packages/openadapt-retrieval.md": "/ecosystem/", + "packages/openadapt-viewer.md": "/ecosystem/", + "packages/privacy.md": "/ecosystem/", + "packages/retrieval.md": "/ecosystem/", + "packages/viewer.md": "/ecosystem/", +} + +# Phrases that describe the retired train-a-VLM happy path as current product. +# Auto-generated changelog pages may quote a historical PR title; everything +# else must not. +FORBIDDEN_TRAIN_PATH_PHRASES = ( + "openadapt train", + "openadapt capture start", + "openadapt capture stop", + "openadapt capture view", + "qwen3vl", + "training_output/", + "pip install openadapt-ml", + "from openadapt_ml", + "AgentPolicy", + "Learn a Policy", + "Learn an agent policy", + "Collect a Demonstration", + "generative RPA", + "Generative RPA", + "LMM-on-the-desktop", + "LMM on the desktop", + "demo-conditioned AI agents", + "legacy model-training path", +) + +TRAIN_PATH_ALLOWLIST = { + "changelog.md", + "whats-new.md", +} + def check_empty_pages(docs_dir=None): """Check for empty or stub-only doc pages.""" @@ -274,6 +332,54 @@ def check_product_docs_contract(docs_dir=None, mkdocs_file=None): return issues +def check_train_path_not_current_product(docs_dir=None): + """Fail if current-product pages still teach capture-then-train.""" + docs_dir = pathlib.Path(docs_dir or DOCS_DIR) + issues = [] + for md_file in sorted(docs_dir.rglob("*.md")): + if not md_file.is_file(): + continue + relative = md_file.relative_to(docs_dir).as_posix() + if relative in TRAIN_PATH_ALLOWLIST: + continue + text = md_file.read_text() + for phrase in FORBIDDEN_TRAIN_PATH_PHRASES: + if phrase in text: + issues.append( + f"Retired capture-then-train copy in {relative}: {phrase!r}" + ) + return issues + + +def check_retired_redirects(docs_dir=None): + """Keep retired train-path and package-mirror URLs on a Flow-first redirect.""" + docs_dir = pathlib.Path(docs_dir or DOCS_DIR) + issues = [] + for relative, dest in sorted(RETIRED_REDIRECTS.items()): + page = docs_dir / relative + if not page.is_file(): + issues.append( + f"Missing Flow-first redirect for retired route: {relative}" + ) + continue + meta = _frontmatter(page.read_text()) + if meta.get("redirect_to") != dest: + issues.append( + f"Retired route {relative} must redirect_to {dest}; " + f"found: {meta.get('redirect_to')!r}" + ) + packages = docs_dir / "packages" + if packages.is_dir(): + for page in sorted(packages.glob("*.md")): + meta = _frontmatter(page.read_text()) + if meta.get("redirect_to") != "/ecosystem/": + relative = page.relative_to(docs_dir).as_posix() + issues.append( + f"Package page {relative} must redirect_to: /ecosystem/" + ) + return issues + + def run_mkdocs_build(strict=False): """Run mkdocs build and return (success, output). @@ -306,6 +412,9 @@ def validate(): contract_issues = check_product_docs_contract() issues.extend(contract_issues) + issues.extend(check_train_path_not_current_product()) + issues.extend(check_retired_redirects()) + # Run mkdocs build success, output = run_mkdocs_build(strict=True) if not success: diff --git a/tests/test_sync_readmes.py b/tests/test_sync_readmes.py index 09fab1c3..1a83aef0 100644 --- a/tests/test_sync_readmes.py +++ b/tests/test_sync_readmes.py @@ -104,3 +104,33 @@ def test_sync_configured_repos_are_page_free(tmp_path, mocker): repos = load_repos() results = sync(repos=repos, docs_dir=tmp_path, templates_dir=ROOT / "templates") assert results == [] + + +def test_sync_does_not_overwrite_a_redirect_stub(tmp_path, mocker): + """A curated Flow-first redirect must survive README sync.""" + mocker.patch( + "sync_readmes.fetch_readme", + return_value="# openadapt-ml\n\nopenadapt train start --capture my-task\n", + ) + stub = tmp_path / "packages" / "openadapt-ml.md" + stub.parent.mkdir(parents=True) + stub.write_text( + "---\nredirect_to: /ecosystem/\n---\n\n# openadapt-ml is Research\n" + ) + before = stub.read_text() + + results = sync( + repos=[ + { + "name": "openadapt-ml", + "github": "OpenAdaptAI/openadapt-ml", + "doc_page": "packages/openadapt-ml.md", + "category": "core", + } + ], + docs_dir=tmp_path, + templates_dir=ROOT / "templates", + ) + + assert results == [] + assert stub.read_text() == before diff --git a/tests/test_validate_docs.py b/tests/test_validate_docs.py index 3a2d35c7..e0d706bf 100644 --- a/tests/test_validate_docs.py +++ b/tests/test_validate_docs.py @@ -7,7 +7,12 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "scripts")) -from validate_docs import check_empty_pages, check_product_docs_contract +from validate_docs import ( + check_empty_pages, + check_product_docs_contract, + check_retired_redirects, + check_train_path_not_current_product, +) def test_product_catalog_binds_all_admitted_targets_to_live_state(): @@ -324,3 +329,53 @@ def test_product_docs_contract_rejects_competing_install_identity(tmp_path): issues = check_product_docs_contract(docs_dir, mkdocs_file) assert any("Competing end-user install identity" in issue for issue in issues) + + +def test_train_path_copy_is_rejected(tmp_path): + docs_dir = tmp_path / "docs" + docs_dir.mkdir() + (docs_dir / "get-started").mkdir() + (docs_dir / "get-started" / "index.md").write_text( + "# Get started\n\nopenadapt train start --capture my-task\n" + ) + + issues = check_train_path_not_current_product(docs_dir) + + assert any( + "Retired capture-then-train copy" in issue + and "openadapt train" in issue + for issue in issues + ) + + +def test_train_path_allowlist_skips_changelog(tmp_path): + docs_dir = tmp_path / "docs" + docs_dir.mkdir() + (docs_dir / "changelog.md").write_text( + "# Changelog\n\n- restore openadapt train for a historical note\n" + ) + + assert check_train_path_not_current_product(docs_dir) == [] + + +def test_real_docs_have_no_train_path_copy(): + root = pathlib.Path(__file__).resolve().parent.parent + assert check_train_path_not_current_product(root / "docs") == [] + + +def test_real_docs_keep_retired_flow_redirects(): + root = pathlib.Path(__file__).resolve().parent.parent + assert check_retired_redirects(root / "docs") == [] + + +def test_retired_redirect_missing_file_is_an_issue(tmp_path): + docs_dir = tmp_path / "docs" + docs_dir.mkdir() + + issues = check_retired_redirects(docs_dir) + + assert any( + "Missing Flow-first redirect for retired route: getting-started/quickstart.md" + in issue + for issue in issues + )