Correct installation and managed-service guidance

configs/release-compatibility.json

@@ -1,4 +1,4 @@
 {
   "console_repository": "https://gitlab.inf.ethz.ch/OU-PERRIG/yimin/debuglet/debuglet-dashboard",
-  "console_revision": "fa18d06a39faaa9e2375bc39318b101a7b2112ff"
+  "console_revision": "49f6ff6248000081287418d9d2c1d3f4a5cdc2bd"
 }

docs/operations/executor-onboarding.md

@@ -227,7 +227,10 @@ Self-service enrollment is disabled by default. It requires native TLS with
 client certificates, an explicitly configured certificate issuer and public
 connection addresses. Back up and upgrade an existing dispatcher database using
 the release's normal database upgrade procedure before starting the new binary.
-This build requires dispatcher schema 14 even if enrollment remains disabled.
+The dispatcher requires a database schema supported by the selected package even
+if enrollment remains disabled. Check the existing database with that package's
+`debuglet-dispatcher -config /path/to/dispatcher.toml -check-database` command;
+an incompatible schema is refused with the explicit upgrade instructions.
 A source merge does not migrate the running service. Schedule deployment
 separately: preserve the current package, configuration and a consistent database
 backup; stop the dispatcher; run the selected package's explicit database upgrade;

docs/operations/external-pilot.md

@@ -68,8 +68,10 @@ commands, the output or error text, and any deviation from the documents.
    Approve the printed code in a browser, adding `--no-browser` on a shell-only
    machine ([CLI access](authentication.md#approve-a-cli-or-headless-host)), or
    use the [account-key login](../cli.md#use-an-account-key-connection) if the
-   project names it. For a private CA, set `SSL_CERT_FILE` to its certificate
-   first; `connect` has no certificate option
+   project names it. If the API uses a private CA, add
+   `--ca-file /path/to/api-ca.crt` to `dbl connect`; the saved connection retains
+   that absolute path, so keep the file available. A publicly trusted HTTPS API
+   uses system trust, even when native executor control uses a private CA
    ([client trust](remote-deployment.md#client-trust-and-account-access)). Run
    `dbl --dispatcher NAME version --server` and
    `dbl --dispatcher NAME --output json nodes`, and record the server version

docs/operations/remote-deployment.md

@@ -3,8 +3,13 @@
 A networked deployment has one dispatcher and one or more executors on Linux amd64 hosts. Every role runs the same Debuglet release. Use TLS, authenticate users, and keep the local-development profile disabled. Running a second dispatcher, against the same database or a separate one, is unsupported, and the dispatcher does not detect one at startup. To recover from a dispatcher outage, restart the dispatcher as described in [dispatcher outage](dispatcher-outage.md); [backup and restore](backup-restore.md) covers generated local TEST state.
 
 Use the full release bundle for the bundled samples. The native daemons accept
-operator-supplied configuration; `dbl up`, `dbl executor up`, and `dbl service
-install` generate local loopback profiles and do not provision this deployment.
+operator-supplied configuration. `dbl up`, `dbl executor up`, and the default
+`dbl service install` generate local loopback profiles. For an account-owned
+executor, `dbl executor join` followed by `dbl service install --enrolled-state`
+preserves its native TLS enrollment; follow the
+[persistent executor setup](executor-onboarding.md#run-persistently-on-linux).
+Use the [deployment guide](../../deploy/README.md) to provision the dispatcher
+and other host-administered roles.
 
 ## Required topology
 
@@ -112,15 +117,17 @@ disable client-certificate verification to bypass missing enrollment.
 
 ## Client trust and account access
 
-The published v0.2.0 CLI uses account-key login. For this profile with a private
-CA on Linux, set `SSL_CERT_FILE` to its public certificate before using `dbl`.
+Current packages save private API trust with `dbl connect --ca-file`; keep that
+public CA file available at its saved absolute path. For a publicly trusted API,
+omit this option, even if native executor control uses a private CA. The published
+v0.2.0 CLI instead uses `SSL_CERT_FILE=/path/to/api-ca.crt` for private trust.
+The following example uses current commands on an account-key deployment.
 Each participant registers an independent account once and retains the private
 account key, recovery code and saved session. This flow does not perform browser
 GitHub login; managed deployments may use a different account policy.
 
 ```sh
-export SSL_CERT_FILE=/path/to/ca.crt
-dbl connect https://dispatcher.example:9000 --name research
+dbl connect https://dispatcher.example:9000 --name research --ca-file /path/to/api-ca.crt
 dbl --dispatcher research login --register alice
 dbl --dispatcher research nodes
 dbl --dispatcher research run --sample hello --executor OTHER_EXECUTOR_UUID --wait --allow-remote-test

docs/operations/services.md

@@ -19,7 +19,18 @@ sudo dbl service status --role executor
 
 Use `dbl drain --role executor` before planned maintenance and `dbl drain --role executor --resume` when it is ready again. Service commands need administrator privileges.
 
-The service owns its role-specific SQLite state and retains it across restart. A database is not automatically migrated or safe to reuse across arbitrary package versions. Back up state and follow the [database upgrade procedure](../../deploy/README.md#upgrading-a-database) before upgrading.
+The service owns its role-specific SQLite state and retains it across restart.
+A database is not automatically migrated or safe to reuse across arbitrary
+package versions.
+
+Reinstalling a managed role requires the same package version and source revision
+as its retained installation record, including after normal uninstall.
+Changing the package of an existing generated managed role is not supported by
+`dbl service install`. The
+[Ansible database-upgrade procedure](../../deploy/README.md#upgrading-a-database)
+for host-administered daemons does not upgrade this managed installation record.
+Keep its package and private
+state for recovery; do not purge retained state to bypass a version refusal.
 
 For an enrolled executor, supply `--enrolled-state` on every install or reinstall.
 Its configuration supplies the dispatcher addresses, so endpoint override flags
@@ -34,6 +45,11 @@ fallback configuration, a local executor and a dispatcher receive no capabilitie
 Separate isolated worker processes drop the daemon's capabilities before running
 guest code. The default trusted in-process execution shares the daemon process.
 
+The generated managed units do not delegate writable cgroups. They support the
+trusted execution profile; selecting `isolation.profile = "shared"` also requires
+a separately configured delegated service with the
+[shared-profile host setup](guest-isolation.md#required-host-setup).
+
 The installed record retains the unit's capability choice so older services
 remain stoppable and removable. Reinstalling preserves the enrollment files;
 changing the saved counter mode and reinstalling the same package updates the

docs/versions.md

@@ -15,17 +15,16 @@ Use the same reviewed package version for the CLI, dispatcher, and executors in
 
 ## Tested combinations
 
-Evidence is scoped to the named revision and fixture. The successful
-[CI run for main `46ee1637`](https://github.com/netsec-ethz/debuglet/actions/runs/36621972902)
-checks the current source baseline below; it does not publish a release or
-establish compatibility for later changes. Check the candidate's own CI when
-selecting another revision.
+The [CI workflow](../.github/workflows/ci.yml) checks the combinations below.
+Evidence is scoped to the exact revision and fixture: check the selected
+candidate's own completed CI run. A successful run does not publish a release or
+establish compatibility for later changes.
 
 | Component | Combination exercised | Evidence and limit |
 | --- | --- | --- |
 | Platform | Linux amd64 on the `ubuntu-24.04` CI runner and the pinned CI tools image | [CI definition](../.github/workflows/ci.yml), [CI images](development/ci-images.md). Other host/architecture combinations have no native package support. |
 | Packages | Same-candidate full bundle and separate CLI, dispatcher and executor packages | Package lane installs twice, verifies each role inventory and runs `--help`; full-bundle runtime checks run in the demo/local lanes. Split packages exist in source/CI; published v0.2.0 contains only the full bundle. |
-| CLI and Go client | Same-source clients and dispatcher; HTTP contract 1.10 | Test, demo and local lanes. A displayed binary version does not negotiate API features. |
+| CLI and Go client | Same-source clients and dispatcher; HTTP contract 1.22 | Test, demo and local lanes. Use `dbl version --server` to inspect the selected server's contract; a displayed binary version does not negotiate API features. |
 | Dispatcher and executor | Same-package peers; control protocol 3 with binding and lease enforcement. Published v0.2.0 executor against the candidate dispatcher in the loopback TEST fixture | Local and compatibility lanes. The released-peer fixture checks registration, work and reconnect; it does not establish mixed-release TLS/enrollment or new optional features. |
 | Guests | `debuglet-go-wasi-imports-v1`, frozen compatibility guest and packaged Go samples | [Guest compatibility gate](debuglets.md#compatibility), compatibility lane. C/Rust guest packages remain experimental. |
 | State | State created by the same package; recognized historical SQLite schemas upgraded explicitly | [State reference](operations/configuration.md#stored-state), storagecheck tests. This is not a cross-package foreground-state migration promise. |