Clarify executor onboarding and first measurements

README-install.md

@@ -8,24 +8,26 @@ operator-supplied candidate until a compatible signed release is published.
 
 ## Install with apt on Ubuntu 24.04 amd64
 
-Use this route when your operator supplies a published apt repository, its
-OpenPGP key fingerprint and an exact Debian package version. Verify the key
+The official public apt channel is not yet published. Use this route only when
+your operator supplies a published apt repository, its OpenPGP key fingerprint
+and an exact Debian package version. Verify the key
 through an independent trusted channel, then install the operator's keyring and
 repository configuration with `Signed-By` scoped to that keyring. Follow the
-complete [apt setup procedure](docs/operations/apt-repository.md); no official
-live repository URL or production signing key is implied by this guide.
+complete [apt setup procedure](docs/operations/apt-repository.md).
 
 ```sh
 sudo apt-get update
 sudo apt-get install debuglet=DEBIAN_VERSION_PROVIDED_BY_OPERATOR
-dbl --output json version
-dbl demo
+/usr/bin/dbl --output json version
+/usr/bin/dbl demo
 ```
 
 The `debuglet` package selects the matching full payload, including the CLI,
-executor, dispatcher and bundled samples. Installation stages software; choose
-account setup, executor enrollment and service activation explicitly. Upgrades
-retain payloads referenced by managed services. Follow the [Debian lifecycle
+executor, dispatcher and bundled samples. Installation creates a missing
+`debuglet` system account and the parent state directories. Account registration,
+executor enrollment and service activation remain explicit. Use `/usr/bin/dbl`
+to avoid selecting an older tar installation on `PATH`. Upgrades retain payloads
+referenced by managed services. Follow the [Debian lifecycle
 procedure](docs/operations/debian.md) to drain, back up, replace and resume an
 existing service. Tar installation remains available below.
 
@@ -59,6 +61,20 @@ service account, or restart an existing service; follow [executor
 setup](docs/operations/executor-onboarding.md) or [managed
 services](docs/operations/services.md) next.
 
+For a system-wide candidate used by a managed service, run this command instead
+of the user-local installation above, with the same trusted inputs:
+
+```sh
+sudo env DEBUGLET_VERSION=VERSION_PROVIDED_BY_OPERATOR \
+  DEBUGLET_RELEASE_DIR="$HOME/Downloads/debuglet-candidate" \
+  DEBUGLET_ALLOW_UNSIGNED=1 DEBUGLET_PREFIX=/usr/local \
+  sh "$HOME/Downloads/bootstrap.sh"
+/usr/local/bin/dbl --output json version
+```
+
+Tar installation leaves service-account creation to the
+[persistent executor setup](docs/operations/executor-onboarding.md#run-persistently-on-linux).
+
 ## Install a signed release
 
 Once your operator identifies an exact published version with signed assets,

README.md

@@ -39,6 +39,7 @@ The versioned guides in [`docs/`](docs/README.md) are published at the [document
 | Need | Start here |
 | --- | --- |
 | Install and run a local demo | [Install Debuglet](README-install.md) |
+| Run a first console measurement | [HTTP check and two-executor comparison](docs/measurements.md#run-your-first-measurement) |
 | Use the CLI | [CLI reference](docs/cli.md) |
 | Write a Go application client | [Go client library](docs/client.md) |
 | Write a debuglet | [Write a debuglet](docs/debuglets.md) |

docs/README.md

@@ -4,6 +4,7 @@ This directory is the versioned source for the [Debuglet documentation site](htt
 
 ## Use Debuglet
 
+- [Run your first measurement](measurements.md#run-your-first-measurement) — use the console to check an HTTP endpoint, read its result and compare two executors.
 - [CLI reference](cli.md) — commands, local demo, and scriptable workflows.
 - [Go client library](client.md) — submit debuglets and read results from an application.
 - [Reusable and coordinated measurements](measurements.md) — saved profiles, retries and experiments across executors.
@@ -28,6 +29,7 @@ This directory is the versioned source for the [Debuglet documentation site](htt
 - [Configuration reference](operations/configuration.md)
 - [Run Debuglet across hosts](operations/remote-deployment.md)
 - [Add your executor](operations/executor-onboarding.md) — console enrollment, shell-only setup and persistent installation.
+- [Debian installation and updates](operations/debian.md) — apt packages, explicit service activation and retained rollback payloads.
 - [Managed services](operations/services.md)
 - [Data retention, export and deletion](operations/data-retention.md)
 - [Chain payments](operations/payments.md) — modes, the supported Sui Testnet profile, startup validation, transfers and enablement.

docs/measurements.md

@@ -1,9 +1,74 @@
-# Reusable measurements and deliberate retries
-
-HTTP API 1.12 adds saved profiles, durable batch details, linked retries and TCP
-listener readiness. These operations use the same account ownership checks as
-run output. The companion console exposes the catalogue, profiles, measurement
-history and editable new requests.
+# Run and reuse measurements
+
+## Run your first measurement
+
+Use this walkthrough on a deployment whose operator confirms compatible console,
+dispatcher and executor versions and provides the console URL.
+
+Ask the operator for a health endpoint they own that returns a small **HTTP 200**
+response and is permitted from the chosen executor. For example,
+`https://service.example/health` is a placeholder: replace it with that endpoint's
+complete URL, including the correct scheme, port and path. A public website is
+not a guaranteed test target. The console cannot inspect the operator's private
+destination and port restrictions in advance.
+
+1. Sign in and open **New measurement**. Choose **HTTP timing & status** and
+   enter the approved URL in **HTTP target**. Leave **Response time threshold**
+   empty for this first check.
+2. Under **Vantage point**, select an executor marked **Available** and
+   **TEST · no wallet**. Open **Node details** to check its identity and reported
+   capabilities. Availability does not prove that your target is permitted or
+   reachable.
+3. Choose **Review measurement**. Check the executor, endpoint, **Permitted
+   destinations**, timeout and bandwidth. Keep the immediate start and default
+   limits if the deployment accepts them, then choose **Run with TEST**.
+4. On the run page, wait for **All program output received.** Inspect
+   **Measurement results** for **Checks passed**, **HTTP status** `200`,
+   **Time** and **Response body**. Check the **Raw program output** JSON too:
+   its `schema` is `debuglet.measurement.v1`, `template` is `http`, and `ok` and
+   the check's `ok` should be `true`. Keep the run ID from **Run details**;
+   **Download output** saves the received program output.
+
+TEST needs no wallet. If the dispatcher enforces TEST allowances, your account
+also needs enough operator-granted units; signing up does not grant them
+automatically. See [TEST allowances](operations/configuration.md#dispatcher-usage-allowances).
+
+The template preserves `http://` or `https://` as entered; HTTPS uses TLS. It
+makes one GET request and requires a 2xx response. It does not follow redirects.
+**Time** measures the whole HTTP check, including connection setup, TLS when
+used, request transmission and reading the response body. Service processing
+contributes to it; this is not a pure network round-trip time (RTT).
+
+An **exited** state means execution ended, not that the check passed. A parsed
+result can appear before all output arrives. Confirm the result, execution state
+and output completeness separately; **All program output received.** alone
+does not mean success.
+
+| What you see | Next step |
+| --- | --- |
+| No available executor, **Offline** or **Maintenance** | Wait for readiness or ask the operator; the list refreshes automatically. |
+| Target denied by the operator network policy | Ask for a permitted endpoint or an executor whose policy permits it. Changing HTTP to HTTPS does not grant permission; do not bypass the policy. |
+| **Checks failed** with HTTP 3xx | Use the final URL only if the operator approves it. A redirect fails the template's 2xx expectation. |
+| Output still arriving, incomplete or completeness unconfirmed | Wait while output arrives; reload if completeness is unconfirmed. Keep incomplete output marked as incomplete rather than inferring success. |
+
+## Compare two executors
+
+1. Open **Grouped measurement**, choose **Compare HTTP responses**, and enter
+   the same approved **HTTP target**. Confirm that both operators permit it.
+2. Under **Choose your nodes**, select two available TEST executors. Keep the
+   same timeout, bandwidth and response threshold for both. Choose **Review
+   group**, check both participants and their permitted destinations, then
+   **Submit group with TEST**.
+3. On **Grouped measurement**, open **Details and output** for each participant.
+   Check its complete output and result as above, then compare HTTP status,
+   response size and time alongside the executor and run IDs. **Export group
+   results** saves a snapshot; it can still contain running participants or
+   incomplete output.
+
+These are two independent HTTP probes in one submission. They do not wait for a
+synchronized start, and one sample per executor does not establish a stable
+latency difference. For coordinated programs, see
+[Coordinate a batch of debuglets](#coordinate-a-batch-of-debuglets).
 
 ## Save and apply a profile
 

docs/operations/debian.md

@@ -1,10 +1,10 @@
 # Debian packages
 
-The initial apt target is **Ubuntu 24.04 amd64**. Install the `debuglet` package
-from a reviewed signed repository following [repository setup](apt-repository.md).
+The initial apt target is **Ubuntu 24.04 amd64**. The official public apt channel
+is not yet published. When your operator supplies a reviewed signed repository,
+install the `debuglet` package following [repository setup](apt-repository.md).
 Use the independently supplied OpenPGP fingerprint and a dedicated `Signed-By`
-keyring; an archive checksum alone does not establish trust. No official live
-repository URL is assumed by these instructions.
+keyring; an archive checksum alone does not establish trust.
 
 `debuglet` selects the commands `/usr/bin/dbl`, `/usr/bin/debuglet-executor` and
 `/usr/bin/debuglet-dispatcher`. Its exact dependency is a separately named
@@ -26,43 +26,46 @@ read-only removal guard; it adds no background process.
 ## Enrollment and activation
 
 Use `/usr/bin/dbl` explicitly if an older tar-installed command appears earlier
-on `PATH`. Follow [executor onboarding](executor-onboarding.md) to register,
-establish trust and join using the service account. Joining creates the named
-executor's state directory under `/var/lib/debuglet/executors`. Install and
-activate that enrolled executor explicitly with the documented service command.
+on `PATH`. Follow [persistent executor onboarding](executor-onboarding.md#run-persistently-on-linux)
+with `dbl_cli=/usr/bin/dbl`; skip its tar-only account setup. Join with `sudo`
+to create the named executor's private state under `/var/lib/debuglet/executors`.
+The service installer assigns that state to the `debuglet` account. Install,
+start and check the enrolled service explicitly with the documented commands.
 Dispatcher and local demo setup remain explicit as described in
 [services](services.md).
 
 ## Updates and rollback
 
-An apt update stages a new full payload and switches the three command links.
+Installing a newer `debuglet` version stages a full payload and switches the
+three command links. `apt-get update` alone only refreshes repository metadata.
 It leaves running and stopped managed services on their previously recorded
 absolute payload paths. Even `apt upgrade` does not restart, enroll, migrate or
-replace a managed service. Inspect the selected payload with:
+replace a managed service. Select the exact operator-approved version and inspect
+its payload before maintenance:
 
 ```sh
+sudo apt-get update
+sudo apt-get install debuglet=DEBIAN_VERSION_PROVIDED_BY_OPERATOR
 dpkg-query -W -f='${Version}\n' debuglet
 candidate=$(dirname "$(dirname "$(readlink -f /usr/bin/dbl)")")
-printf '%s\n' "$candidate"
+replacement_cli="$candidate/bin/dbl"
+"$replacement_cli" --output json version
 ```
 
-For an enrolled executor, follow the [release rollout](release-rollout.md):
-drain it, create and verify an offline backup of its complete identity, keys,
-trust, configuration, database, outputs and service records, then use the
-verified replacement command while the unit is stopped and disabled:
-
-```sh
-sudo /usr/bin/dbl service install --role executor --name worker \
-  --enrolled-state /var/lib/debuglet/executors/worker \
-  --replace-package "$candidate" --start=false --enable=false
-```
-
-Use the recorded instance name instead of `worker`. Replacement preserves its
-service account, state paths and identity. Check compatibility and explicitly
-resume using the rollout procedure. Rollback selects a retained older payload
-with the same replacement command and is subject to database compatibility;
-an apt downgrade alone does not roll back a service or a database. Existing
-dispatcher replacement limits are unchanged; see the rollout documentation.
+For an enrolled executor, use the
+[controlled replacement procedure](services.md#replace-an-enrolled-executors-package)
+with this candidate; its tar staging command is unnecessary. Use the recorded
+instance name throughout. The procedure requires a drain with `joined: true`
+and `enabled: false`, a verified private offline backup of the complete state,
+identity and service records, and retention of the previous payload. Replacement
+preserves the account, state paths and identity; it does not migrate or enroll
+again. Explicitly resume after success, check readiness and the connected version,
+then complete a permitted TEST measurement.
+
+Rollback uses the replacement-capable CLI to select a retained older payload and
+requires compatible state; an apt downgrade alone does not roll back a service
+or database. The linked procedure covers interrupted replacement, rollback and
+unsupported dispatcher replacement.
 
 Release `v1.2.3` has Debian version `1.2.3-1`; prerelease `v1.2.3-rc.1` becomes
 `1.2.3~rc.1-1`, which sorts before the final release. Development versions such