docs: refresh README for the openadapt-ops rename and docs pipeline

README.md

@@ -1,48 +1,94 @@
-# openadapt-maintenance
+# openadapt-ops
 
-Automated documentation generator for the OpenAdapt ecosystem. Syncs READMEs, aggregates changelogs, and generates digest pages using LLM.
+Documentation source and ops automation for the OpenAdapt ecosystem. This
+repository is the source of truth for the public product documentation at
+[docs.openadapt.ai](https://docs.openadapt.ai), and it holds the tooling that
+builds, validates, and publishes that site.
 
-> **Lifecycle: Internal.** This repository is the publishing infrastructure and
-> source for the public OpenAdapt documentation; it is not an end-user package.
+> **Lifecycle: Internal.** This repository is publishing and operations
+> infrastructure, not an end-user package. It was formerly named
+> `openadapt-maintenance` and is now `OpenAdaptAI/openadapt-ops`.
 
 > **Source of truth:** This repository's `docs/` tree and `mkdocs.yml` own
 > `docs.openadapt.ai`. `OpenAdapt/docs`, `OpenAdapt/mkdocs.yml`, and
 > `openadapt-gitbook` are noncanonical historical trees and must not deploy to
 > the production docs domain. See
 > [`docs/reference/documentation-governance.md`](docs/reference/documentation-governance.md).
 
-## Quick Start
+## About OpenAdapt
 
-```bash
-# Install dependencies
-uv sync
-
-# Sync all READMEs into docs/
-python scripts/sync_readmes.py
+OpenAdapt is a governed demonstration compiler. Record a GUI workflow once,
+compile it, and replay it deterministically with zero model calls on the
+healthy path. When the screen drifts, it re-resolves or proposes a governed
+repair, verifies real effects, and halts rather than guesses. Every execution
+substrate is first-class (web, native Windows, native macOS, Linux, RDP, and
+Citrix/VDI), local-first with an optional managed cloud, and open-core under
+MIT. The flagship code lives at
+[github.com/OpenAdaptAI/openadapt](https://github.com/OpenAdaptAI/openadapt).
 
-# Aggregate changelogs
-python scripts/aggregate_changelog.py
+## What is in this repository
 
-# Generate What's New (optional: set ANTHROPIC_API_KEY for LLM summary)
-python scripts/generate_whats_new.py
+- **`docs/`** and **`mkdocs.yml`**: the curated MkDocs Material site published
+  to [docs.openadapt.ai](https://docs.openadapt.ai). Curated product pages own
+  the navigation.
+- **`scripts/`**: the documentation pipeline. Mechanical sync steps
+  (`sync_readmes.py`, `aggregate_changelog.py`) are deterministic and make no
+  API calls. LLM-enhanced steps (`generate_whats_new.py`,
+  `build_architecture.py`) are optional and degrade gracefully without an API
+  key. `validate_docs.py` gates the site.
+- **`tidy/`**: a CLI for scanning and scrubbing sensitive patterns from git
+  history and build artifacts (GitHub Releases, Actions, PyPI, and GHCR). See
+  [`tidy/README.md`](tidy/README.md).
+- **`repos.yml`**: the list of ecosystem repositories the pipeline reads from.
 
-# Build and preview the docs site
-uv run mkdocs serve
-```
+## Build the docs locally
 
-## Adding a New Repo
+```bash
+# Install dependencies
+uv sync --extra dev
 
-Add an entry to `repos.yml` — no code changes needed.
+# Preview the site with live reload
+uv run mkdocs serve
 
-## Architecture
+# Build the site in strict mode (the same gate CI uses)
+uv run mkdocs build --strict
 
-- **Mechanical sync** (sync_readmes, aggregate_changelog): deterministic, no API calls
-- **LLM-enhanced** (generate_whats_new, build_architecture): optional, gracefully degrades without API key
-- **MkDocs Material**: builds to static site, deployable on GitHub Pages
+# Validate the docs contract (empty-page check plus an mkdocs build)
+uv run python scripts/validate_docs.py
+```
 
 ## Tests
 
 ```bash
 uv sync --extra dev
-uv run pytest tests/ -v
+uv run pytest tests/ -q
 ```
+
+## Continuous integration and publishing
+
+- **`.github/workflows/ci.yml`** runs on every pull request and on push to
+  `main`. It installs locked dependencies, runs the test suite, validates the
+  documentation contract, and builds the site with `mkdocs build --strict`.
+- **`.github/workflows/sync.yml`** builds and deploys the site to GitHub Pages,
+  served at `docs.openadapt.ai`. It runs when:
+  - a push to `main` touches `docs/**`, `mkdocs.yml`, or the workflow itself,
+    which builds and deploys this repository's docs as-is;
+  - a sub-repository dispatches a `repo-updated` event (see
+    [`.github/workflows/trigger.yml`](.github/workflows/trigger.yml)) so its
+    README and changelog pages re-sync here;
+  - the weekly schedule or a manual run performs a full cross-repo rebuild.
+
+  Every path validates and builds in strict mode before deploying, so a failing
+  gate blocks publication.
+
+## Adding a new repository
+
+Add an entry to `repos.yml`. No code changes are needed.
+
+## Links
+
+- Live documentation: [docs.openadapt.ai](https://docs.openadapt.ai)
+- Flagship repository:
+  [github.com/OpenAdaptAI/openadapt](https://github.com/OpenAdaptAI/openadapt)
+- Documentation governance:
+  [`docs/reference/documentation-governance.md`](docs/reference/documentation-governance.md)