feat: installer-first get-started funnel plus dev.to crosspost and weekly metrics scripts

.gitignore

@@ -9,6 +9,10 @@ _site_check/
 # Tidy tool patterns (contains sensitive strings)
 tidy/patterns
 
+# Weekly growth metrics output (scripts/metrics_weekly.py)
+/reports/
+
+
 # Never-publish workspace material (strategy, prospect research, counsel packs,
 # personal contact details). Created ad hoc; must never reach a remote.
 .private/

docs/get-started/first-workflow.md

@@ -15,17 +15,27 @@ and watch the run heal or halt under drift:
 
 ## Prerequisites and install
 
-- **Python 3.10-3.12.** The engine declares `requires-python >=3.10,<3.13`.
-  Check yours with `python --version` (on some systems `python3 --version`).
 - **macOS, Linux, or Windows.** This walkthrough selects the Playwright-driven
   browser capability, so it has no OS-specific steps. Its matching Chromium
   provisions automatically on the first web action; native, RDP, and Citrix
   paths do not install it.
-- **Use a virtual environment.** It keeps the install isolated and avoids the
-  stale-package problems a shared or Conda base environment causes.
 
-Install the CLI for your shell — the quoting around `openadapt[browser]`
-differs per shell, and getting it wrong is the most common first failure:
+**Recommended: install with uv.** The first command installs
+[uv](https://docs.astral.sh/uv/) if it is missing; the second provisions a
+suitable Python, installs OpenAdapt with browser support as a persistent
+`openadapt` command, and runs a short environment check:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/OpenAdaptAI/openadapt-flow/main/scripts/install.sh | sh
+```
+
+**Manual path: pip in a virtual environment.** If you prefer to manage the
+environment yourself — or your team standardizes on pip — use the tabs below.
+The engine declares `requires-python >=3.10,<3.13`; check yours with
+`python --version` (on some systems `python3 --version`). The quoting around
+`openadapt[browser]` differs per shell, and getting it wrong is the most common
+first failure:
 
 === "macOS / Linux (bash, zsh)"
 
@@ -36,7 +46,9 @@ differs per shell, and getting it wrong is the most common first failure:
 
     The quotes matter: unquoted square brackets are glob characters in zsh
     (`no matches found`) and can misbehave in bash. Single or double quotes
-    both work here.
+    both work here. A virtual environment keeps the install isolated and
+    avoids the stale-package problems a shared or Conda base environment
+    causes.
 
 === "Windows PowerShell"
 
@@ -75,14 +87,6 @@ differs per shell, and getting it wrong is the most common first failure:
     The built-in driver uses X11; Wayland requires an operator-approved XDG
     portal session.
 
-Or use the installer script from the landing page, which installs
-[uv](https://docs.astral.sh/uv/) if needed and sets up a persistent
-`openadapt` command:
-
-```bash
-curl -fsSL https://openadapt.ai/install.sh | sh -s -- browser
-```
-
 !!! tip "No app to record against yet?"
     You do not need your own target to try the loop. The engine bundles
     **MockMed**, a synthetic demo clinic app (fake data only):

docs/get-started/index.md

@@ -12,16 +12,41 @@ runs the program, and verifies the saved result.
 
 ![OpenAdapt records, compiles, and replays a demonstrated workflow](../assets/showcase/demo.gif)
 
-## First success: two commands
+See it working before you install anything:
+
+- **[Hosted demo](https://app.openadapt.ai/demo)** — recorded demonstrations,
+  verified replays, and fail-safe halts on real footage.
+- **[Template gallery](https://openadapt.ai/templates)** — ready-to-adapt
+  workflow templates.
+- **[Blog](https://blog.openadapt.ai)** — guides, updates, and automation
+  recipes.
+
+## First success: install, then run
 
 You need no account, target application, API key, or operating-system
-automation permission:
+automation permission.
+
+**Recommended: install with uv.** The first command installs
+[uv](https://docs.astral.sh/uv/) if it is missing. The second installs
+OpenAdapt with browser support as a persistent `openadapt` command and runs a
+short environment check. Both are safe to re-run; they upgrade in place:
 
 ```bash
-python -m pip install --upgrade 'openadapt[browser]'
+curl -LsSf https://astral.sh/uv/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/OpenAdaptAI/openadapt-flow/main/scripts/install.sh | sh
+```
+
+**Manual path: pip.** If you prefer to manage your own environment, create a
+virtual environment, then run:
+
+```bash
+pip install 'openadapt[browser]'
 openadapt quickstart
 ```
 
+Shell-specific quoting notes are in
+[Your first workflow](first-workflow.md#prerequisites-and-install).
+
 The command records the bundled synthetic MockMed task, compiles its observed
 [effect contract](../reference/glossary.md#effect-contract), certifies it with
 the shipped clinical-write [policy](../reference/glossary.md#policy), and runs
@@ -49,6 +74,10 @@ openadapt flow visualize openadapt-quickstart/bundle --out graph.html
 openadapt flow lint openadapt-quickstart/bundle
 ```
 
+When you move from the tutorial to your own work, OpenAdapt qualifies each
+workflow against its real environment. Qualification means we test your
+workflow against real failures before it runs.
+
 After the first run, choose the path that matches your goal:
 
 | Goal | Next guide |

docs/llms.txt

@@ -3,9 +3,9 @@
 > 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 zero model 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/): Install the CLI and run the complete demo journey in about five minutes
+- [Get started](https://docs.openadapt.ai/get-started/): Install with the uv installer script or pip, then run the complete demo journey in about five minutes
 - [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/): Prerequisites, install, then record, compile, lint, replay, and read the report on your own web app
+- [Your first workflow](https://docs.openadapt.ai/get-started/first-workflow/): Installer-first setup, 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
 
 ## Desktop app

pyproject.toml

@@ -23,6 +23,8 @@ llm = [
 dev = [
     "pytest>=9.0.3",
     "pytest-mock>=3.12",
+    # Used by scripts/crosspost_devto.py and scripts/metrics_weekly.py.
+    "httpx>=0.27",
 ]
 
 [tool.hatch.build.targets.wheel]

scripts/README.md

@@ -0,0 +1,85 @@
+# Operational scripts
+
+Standalone maintenance and growth scripts for the docs repository. Unless a
+script says otherwise, install the dev environment first:
+
+```bash
+uv sync --locked --extra dev
+```
+
+## Growth scripts
+
+### `crosspost_devto.py` — mirror blog posts to dev.to
+
+Reads the blog RSS feed (`https://blog.openadapt.ai/index.xml`; the Hugo
+config points its RSS entry there) and creates one dev.to article per post
+that is not on the account yet. Every article sets `canonical_url` to the
+original blog URL so search engines keep ranking the blog first.
+
+- Dry-run is ON by default and prints exactly what would be posted.
+- Idempotent: it lists existing articles via `GET /api/articles/me/all` and
+  skips any post whose canonical URL already exists.
+- The API key comes from the `DEVTO_API_KEY` environment variable and is
+  never written to disk or logs.
+
+```bash
+# Preview against the live feed (no key needed):
+uv run python scripts/crosspost_devto.py
+
+# Preview against a local fixture:
+uv run python scripts/crosspost_devto.py --feed tests/fixtures/sample_feed.xml
+
+# Post for real:
+DEVTO_API_KEY=<key> uv run python scripts/crosspost_devto.py --apply
+
+# Post at most one article per run:
+DEVTO_API_KEY=<key> uv run python scripts/crosspost_devto.py --apply --limit 1
+```
+
+Run it after publishing a blog post, or as part of the weekly routine below.
+
+### `metrics_weekly.py` — weekly growth report
+
+Collects one week's growth snapshot and writes
+`reports/growth-metrics-YYYY-WW.md`:
+
+| Source | Metrics |
+|---|---|
+| GitHub API | stars and forks for `OpenAdaptAI/OpenAdapt`, `openadapt-flow`, `openadapt-capture` |
+| HN Algolia | story hits mentioning "OpenAdapt", summed points and comments |
+| pypistats.org | downloads over the last 7 days for `openadapt` and `openadapt-flow` |
+| Blog sitemap | number of individual blog posts |
+
+The table layout is deterministic (fixed row and column order, no timestamps),
+so consecutive weeks diff cleanly. Failed sources render as `n/a` instead of
+stopping the run. `reports/` is gitignored; keep the files wherever you archive
+weekly numbers.
+
+```bash
+uv run python scripts/metrics_weekly.py                 # current ISO week
+uv run python scripts/metrics_weekly.py --week 2026-W34 # specific week
+uv run python scripts/metrics_weekly.py --stdout        # print, do not write
+```
+
+No API key is required. Setting `GH_TOKEN` raises the GitHub rate limit only;
+it is never logged.
+
+**Weekly cadence:** run both scripts once per week, e.g. Monday 09:00 UTC,
+right before the Monday docs sync:
+
+```cron
+0 9 * * 1 cd /path/to/openadapt-ops && uv sync --locked --extra dev --quiet && uv run python scripts/metrics_weekly.py >> reports/cron.log 2>&1 && DEVTO_API_KEY=<key> uv run python scripts/crosspost_devto.py --apply >> reports/cron.log 2>&1
+```
+
+This repository intentionally ships no cron workflow for these scripts; wire
+the schedule in your own runner when the weekly review owns one.
+
+## Guard and generator scripts
+
+The remaining scripts validate or generate the published site:
+`validate_docs.py` (product-doc contract plus strict build), `sync_readmes.py`
+and `aggregate_changelog.py` / `generate_whats_new.py` (content sync feeding
+`docs/packages/`, `docs/changelog.md`, and `docs/whats-new.md`),
+`check_published_version_claims.py` (release-claim registry),
+`check_production_readiness.py` and the `database_backup_*` /
+`sweep_*` scripts (production operations). Each carries its own usage docstring.