Fix recording targets and harden quickstart evidence

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ name: CI
 #       e2e-browser (the GOLDEN TASK first -- the whole free path to VERIFIED,
 #         pinned against tests/golden/tutorial_run.json -- then record ->
 #         compile -> replay in a headless browser; no OS permissions needed, so
-#         it runs on PRs, NOT just nightly),
+#         it runs on PRs, NOT just weekly),
 #       linux-atspi-x11 (real GTK/AT-SPI actuation inside Xvfb + session D-Bus),
 #       wheel (clean-venv wheel install + CLI smoke),
 #       windows-mock (non-injecting Win32 ABI + fake behavior contract).
@@ -44,7 +44,7 @@ name: CI
 #   - wheel
 #   - gate
 # `gate` comes from the separate Validate claims workflow.
-#   (test-matrix remains nightly/explicit release qualification.)
+#   (test-matrix remains weekly/explicit release qualification.)
 on:
   pull_request:
   push:
@@ -65,7 +65,7 @@ concurrency:
 
 jobs:
   # --- Lint + type check (ruff + mypy) -------------------------------------
-  # Runs on PRs (and post-merge/nightly). Deliberately a SEPARATE job from the
+  # Runs on PRs (and post-merge/weekly). Deliberately a SEPARATE job from the
   # required `test` gate: it must NOT be wired as a dependency of `test` (that
   # would leave `test` reporting a compound context and break branch
   # protection, whose required context is exactly `test`). Add `lint` as its
@@ -94,7 +94,7 @@ jobs:
         run: mypy
 
   # --- Supported Python lower bound (required on PRs) ----------------------
-  # The full cross-platform matrix remains post-merge/nightly, but the oldest
+  # The full cross-platform matrix remains post-merge/weekly, but the oldest
   # supported interpreter must install and execute the release-consistency gate
   # before merge. This specifically prevents Python 3.11-only stdlib imports or
   # dependency metadata drift from reaching PyPI unnoticed.
@@ -351,7 +351,7 @@ jobs:
       # when a drift/heal test fails in CI. --ignore=tests/e2e drops the slow
       # browser/OCR end-to-end suite from the fast required gate (it runs in the
       # required `e2e-browser` job instead). The complete suite is repeated
-      # across supported interpreters/OSes nightly and for explicit release
+      # across supported interpreters/OSes weekly and for explicit release
       # qualification. --cov collects coverage into
       # .coverage for the enforced safety floor in the next step.
       - name: Test (fast unit suite)
@@ -390,7 +390,7 @@ jobs:
   # The end-to-end record -> compile -> replay-under-drift suite. It drives a
   # HEADLESS Playwright browser against the bundled MockMed app, so it needs no
   # OS-level input permissions and runs deterministically on a Linux runner --
-  # which is exactly why it is a REQUIRED PR check here, not a nightly-only one.
+  # which is exactly why it is a REQUIRED PR check here, not a weekly-only one.
   # The desktop/Citrix/Parallels legs under tests/e2e self-skip when their
   # macOS/VM backends are absent (i.e. on this Linux runner), so running the
   # whole directory exercises every browser scenario and skips the rest.

.github/workflows/quickstart-lifecycle.yml

@@ -49,6 +49,7 @@ jobs:
           --work-dir "runs/lifecycle"
           --install-browser
           --browser-with-deps
+          --source-revision "${{ github.sha }}"
 
       - name: Full lifecycle (macOS / Windows)
         if: runner.os != 'Linux'
@@ -57,6 +58,7 @@ jobs:
           --wheel "lifecycle-dist/*.whl"
           --work-dir "runs/lifecycle"
           --install-browser
+          --source-revision "${{ github.sha }}"
 
       - name: Upload lifecycle evidence
         if: always()

README.md

@@ -149,7 +149,7 @@ governed lifecycle (`openadapt-flow repair`: reviewed diff, replay + fault
 campaigns, human approval, staged canary, one-command rollback). See
 [docs/REPAIR_LIFECYCLE.md](docs/REPAIR_LIFECYCLE.md).
 
-The nightly clean-machine test runs this complete install-to-uninstall journey
+The weekly clean-machine test runs this complete install-to-uninstall journey
 on Linux, macOS, and Windows. See the
 [capability and qualification matrix](docs/PRODUCT_STATUS.md) for the accepted
 scope of each substrate.
@@ -169,25 +169,49 @@ to the browser, and it prints a visible notice when it does. See
 [docs/SURFACES.md](docs/SURFACES.md) for the per-surface first-workflow paths
 and the two remote execution modes.
 
+Install the Capture component together with the runtime for the surface that
+will replay the workflow:
+
+| Workflow surface | Exact install |
+|---|---|
+| Browser | `pip install 'openadapt-flow[browser]'` |
+| Native Windows | `pip install 'openadapt-flow[capture,windows]'` |
+| Native macOS | `pip install 'openadapt-flow[capture,macos]'` |
+| Native Linux | `pip install 'openadapt-flow[capture,linux]'` plus the AT-SPI system packages in [the Linux guide](docs/desktop/LINUX_NATIVE.md) |
+| Network RDP | Recorder: `pip install 'openadapt-flow[capture]'` inside the demonstrated session; runner: `pip install 'openadapt-flow[rdp]'` |
+| Local RDP/Citrix client window | macOS host: `pip install 'openadapt-flow[capture,macos]'`; Windows host: `pip install 'openadapt-flow[capture,windows]'` |
+
 ```bash
 # Browser (Playwright / Chromium): the app is a URL.
 openadapt-flow record --backend web --url https://your.app --out rec
 openadapt-flow compile rec --out bundle --name my-task
 openadapt-flow replay bundle --backend web --url https://your.app
 
-# Native Windows (UI Automation via the in-guest WAA agent).
-openadapt-flow record --backend windows --agent-url http://localhost:5001 \
+# Native Windows: Capture records the local target window. WAA drives replay.
+openadapt-flow record --backend windows --window "Target App" \
   --task "add a patient note" --out rec
+openadapt-flow compile rec --out bundle --name my-task
+openadapt-flow replay bundle --backend windows \
+  --agent-url http://localhost:5001
 
-# Native macOS (accessibility, one app window).
-openadapt-flow record --backend macos --macos-app TextEdit --out rec
+# Native macOS: --macos-app scopes Capture and selects the replay app.
+openadapt-flow record --backend macos --macos-app TextEdit \
+  --macos-window-title notes.txt --out rec
+openadapt-flow compile rec --out bundle --name my-task
+openadapt-flow replay bundle --backend macos --macos-app TextEdit \
+  --macos-window-title notes.txt
 
-# Native Linux (AT-SPI, one exact app window).
-openadapt-flow record --backend linux --linux-app gedit \
-  --linux-window-title "Untitled Document 1" --out rec
+# Native Linux: Capture records the local desktop; AT-SPI selects replay target.
+openadapt-flow record --backend linux --out rec
+openadapt-flow compile rec --out bundle --name my-task
+openadapt-flow replay bundle --backend linux --linux-app gedit \
+  --linux-window-title "Untitled Document 1"
 
-# RDP remote display (pixel-only vision ladder over the network session).
-openadapt-flow record --backend rdp --rdp-host 10.0.0.5 --out rec
+# Network RDP: run record inside the demonstrated remote session. The host is
+# a replay target, so it is supplied only when the runner connects.
+openadapt-flow record --backend rdp --out rec
+openadapt-flow compile rec --out bundle --name my-task
+openadapt-flow replay bundle --backend rdp --rdp-host 10.0.0.5
 
 # Citrix / VDI (one exact local Citrix Workspace window).
 openadapt-flow record --backend citrix \
@@ -196,14 +220,23 @@ openadapt-flow record --backend citrix \
   --rdp-window-title "Ward A" \
   --rdp-readiness-text "Appointments" \
   --out rec
+openadapt-flow compile rec --out bundle --name my-task
+openadapt-flow replay bundle --backend citrix \
+  --rdp-window "Citrix Viewer" \
+  --rdp-window-title "Ward A" \
+  --rdp-readiness-text "Appointments"
 ```
 
 `--backend web` is browser-first (the app is a `--url`). For
-`windows`, `macos`, `linux`, `rdp`, and `citrix` the capture has no field identity, so the
-target is the app window or host: `--agent-url` for Windows, `--macos-app`,
-`--linux-app` plus `--linux-window-title`, and `--rdp-host` (or a configured
-exact `rdp_window` / `rdp_window_title` for Citrix Workspace). Pass the same `--backend`
-plus target flags to `replay`, or drive a real deployment with
+`windows`, `macos`, `linux`, `rdp`, and `citrix`, the Capture component records
+local screen, mouse, keyboard, timing, and available action-time structure.
+`--macos-app` / `--macos-window-title` scope the macOS Capture window.
+`--window` / `--window-title` scope a Windows-hosted local capture, and
+`--rdp-window` / `--rdp-window-title` bind a local RDP or Citrix client window
+to both capture and replay. In contrast, `--agent-url`, `--linux-app`,
+`--linux-window-title`, and `--rdp-host` name replay targets that the local
+Capture session cannot control. `record` refuses those flags instead of
+ignoring them; pass them to `replay` or `run`. Drive a real deployment with
 `openadapt-flow run bundle --config deploy.yaml`, which reads the backend,
 effects, actuation, durable, and policy sections from one config. Recorded
 parameter values are the defaults, and `--param` overrides them at replay.

claims.yaml

@@ -70,8 +70,8 @@ claims:
         registry. Desktop and remote-display workflows use the separately scoped
         acceptance and code-qualified claims below.
       - >-
-        The full record->compile->replay e2e runs in the post-merge/nightly
-        full suite; the fast required PR gate covers the replayer + demo units.
+        The full record->compile->replay browser suite runs in the required
+        e2e-browser PR gate and repeats in the weekly compatibility matrix.
 
   # -------------------------------------------------- deterministic $0 replay
   - id: deterministic-zero-model-replay