docs: run a job by hand through systemd-run

deploy/README.md

@@ -15,6 +15,17 @@ does the work: accounts, venv, env files, units, timers, and migrating an older
 runs one as its timer does. State is under `/var/lib/session-ops/<job>/`, copies of a
 run under its `runs/` for 14 days.
 
+`session-ops run` does not read the job's env files: its unit loads them, as root. By
+hand, give it the account and env files its drop-in sets, in
+`/etc/systemd/system/session-ops@<job>.service.d/job.conf`:
+
+```bash
+systemd-run --pipe --wait -p User=sessionops \
+  -p EnvironmentFile=/etc/session-ops/store-versions.env \
+  -p StateDirectory=session-ops/store-versions -p StateDirectoryMode=0711 -p UMask=0077 \
+  /opt/session-ops/.venv/bin/session-ops run store-versions --dry-run
+```
+
 ## Install
 
 Needs systemd 252+, Python 3.11+ at `/usr/bin/python3`, `git`, and nginx with certbot.

deploy/env/expiry.toml.example

@@ -8,7 +8,7 @@
 
 # Only for a Claude Code token installed before token-expiry first ran: it otherwise
 # dates a token from the day it first saw it. Ignored once that token is replaced.
-# The fingerprint is printed by `session-ops run token-expiry --dry-run`.
+# The fingerprint is printed by a dry run of token-expiry: see docs/jobs/token-expiry.md.
 #[issued.CLAUDE_CODE_OAUTH_TOKEN]
 #fingerprint = "3f2a9c01b4de"
 #date = 2025-11-20

docs/jobs/crowdin-duplicates.md

@@ -8,7 +8,7 @@ for a plural string, is what gets exported. A slot is (string, locale, plural ca
 | --- | --- |
 | Runs | `session-ops-queue.timer`, Mon–Fri from 10:00 Australia/Melbourne, last |
 | Secrets | `/etc/session-ops/crowdin.env`: a read-only `CROWDIN_API_TOKEN` and the channel's webhook |
-| Dry run | `session-ops run crowdin-duplicates --dry-run -- --locales de` |
+| Dry run | `session-ops run crowdin-duplicates --dry-run -- --locales de`. On the host, through `systemd-run` as in [deploy/README.md](../../deploy/README.md). |
 | Re-run | `systemctl start session-ops@crowdin-duplicates.service` |
 | Logs | `journalctl -u session-ops@crowdin-duplicates -n 50 --no-pager` |
 

docs/jobs/crowdin-sync.md

@@ -18,8 +18,8 @@ commit just pushed:
 | --- | --- |
 | Runs | `session-ops-queue.timer`, Mon–Fri from 10:00 Australia/Melbourne, after `zendesk-digest` |
 | Secrets | `/etc/session-ops/crowdin.env`: a read-only `CROWDIN_API_TOKEN` and `CROWDIN_DISCORD_WEBHOOK_URL` for the summary; `/etc/session-ops/publish.env` and the GitHub App key, to publish |
-| Dry run | `session-ops run crowdin-sync --dry-run`: everything but the push, with each platform's diff in the journal |
-| Re-run | `systemctl start session-ops@crowdin-sync.service`; one target with `session-ops run crowdin-sync -- --only ios` |
+| Dry run | `session-ops run crowdin-sync --dry-run`: everything but the push, with each platform's diff in the journal. On the host, through `systemd-run` as in [deploy/README.md](../../deploy/README.md). |
+| Re-run | `systemctl start session-ops@crowdin-sync.service`; one target with `session-ops run crowdin-sync -- --only ios`. On the host, through `systemd-run` as in [deploy/README.md](../../deploy/README.md). |
 | Logs | `journalctl -u session-ops@crowdin-sync -n 100 --no-pager`; the run's downloads, parsed JSON and validation report under `/var/lib/session-ops/crowdin-sync/runs/`, for 14 days |
 
 One process, in order:

docs/jobs/github-prs-digest.md

@@ -9,7 +9,7 @@ has a reason to already know about:
 | --- | --- |
 | Runs | `session-ops-queue.timer`, Mon–Fri from 10:00 Australia/Melbourne, first in the queue |
 | Secrets | `/etc/session-ops/github-prs.env`: `GITHUB_PRS_TOKEN` with no scopes at all, and the channel's webhook |
-| Dry run | `session-ops run github-prs-digest --dry-run`; `uv run github-prs-digest --dry-run` from a checkout |
+| Dry run | `session-ops run github-prs-digest --dry-run`; `uv run github-prs-digest --dry-run` from a checkout. On the host, through `systemd-run` as in [deploy/README.md](../../deploy/README.md). |
 | Re-run | `systemctl start session-ops@github-prs-digest.service` |
 | Logs | `journalctl -u session-ops@github-prs-digest -n 50 --no-pager` |
 

docs/jobs/release-stats.md

@@ -7,7 +7,7 @@ public releases API, as two CSV files.
 | --- | --- |
 | Runs | on demand only: `systemctl start session-ops@release-stats.service` |
 | Secrets | none; `/etc/session-ops/alerts.env` for its failures |
-| Dry run | `session-ops run release-stats --dry-run` prints the CSVs and writes nothing |
+| Dry run | `session-ops run release-stats --dry-run` prints the CSVs and writes nothing. On the host, through `systemd-run` as in [deploy/README.md](../../deploy/README.md). |
 | Logs | `journalctl -u session-ops@release-stats -n 50 --no-pager`, which carries both CSVs |
 
 The files land in `/var/lib/session-ops/release-stats/runs/<stamp>/` and are pruned

docs/jobs/snode-list.md

@@ -13,7 +13,7 @@ bundles it, as the list a new client falls back on when it cannot reach them:
 | --- | --- |
 | Runs | `session-ops-queue.timer`, Mon–Fri from 10:00 Australia/Melbourne, after `crowdin-sync` |
 | Secrets | `/etc/session-ops/publish.env` and the GitHub App key, installed on the three repos above; `CROWDIN_DISCORD_WEBHOOK_URL` from `crowdin.env` for the summary |
-| Dry run | `session-ops run snode-list --dry-run` |
+| Dry run | `session-ops run snode-list --dry-run`. On the host, through `systemd-run` as in [deploy/README.md](../../deploy/README.md). |
 | Re-run | `systemctl start session-ops@snode-list.service` |
 | Logs | `journalctl -u session-ops@snode-list -n 50 --no-pager` |
 

docs/jobs/store-versions.md

@@ -8,7 +8,7 @@ highest GitHub release, and posts as they diverge and come back.
 | Runs | `session-ops@store-versions.timer`, every 5 minutes |
 | Secrets | `/etc/session-ops/store-versions.env`: `STORE_VERSIONS_DISCORD_WEBHOOK_URL` |
 | Tags | `/etc/session-ops/store-versions.toml`, from [`store-versions.toml.example`](../../deploy/env/store-versions.toml.example); without it nobody is tagged |
-| Dry run | `session-ops run store-versions --dry-run` prints every version and what it would post |
+| Dry run | `session-ops run store-versions --dry-run` prints every version and what it would post. On the host, through `systemd-run` as in [deploy/README.md](../../deploy/README.md), so it gets the env file |
 | Logs | `journalctl -u session-ops@store-versions -n 50 --no-pager` |
 
 | Platform | GitHub | Store | Warns when the store is |

docs/jobs/token-expiry.md

@@ -9,7 +9,7 @@ as Crowdin's, counts from 00:00 UTC that day.
 | Runs | `session-ops@token-expiry.timer`, daily at 09:00 Melbourne |
 | Secrets | `/etc/session-ops/alerts.env`: `ALERT_DISCORD_WEBHOOK_URL`; `github-prs.env` and `zendesk.env` for the tokens it checks |
 | Dates | `/etc/session-ops/expiry.toml`, from [`expiry.toml.example`](../../deploy/env/expiry.toml.example) |
-| Dry run | `session-ops run token-expiry --dry-run` prints each token's expiry and the alert it would post |
+| Dry run | `session-ops run token-expiry --dry-run` prints each token's expiry and the alert it would post. On the host, through `systemd-run` as in [deploy/README.md](../../deploy/README.md). |
 | Logs | `journalctl -u session-ops@token-expiry -n 50 --no-pager` |
 
 | Token | Expiry from |

docs/jobs/zendesk-digest.md

@@ -6,7 +6,7 @@ Claude reviews the Zendesk tickets awaiting a reply — `new` and `open`, no app
 | --- | --- |
 | Runs | `session-ops-queue.timer`, Mon–Fri from 10:00 Australia/Melbourne, after `github-prs-digest`: `zendesk-resolve-reviews --apply`, then `zendesk-triage` |
 | Secrets | `/etc/session-ops/zendesk.env`: the Zendesk API token, the triage channel's webhook, and the Claude Code CLI login of the `zendesk` account |
-| Dry run | `session-ops run zendesk-digest --dry-run`; `uv run zendesk-triage --window-hours 72 --dry-run` from a checkout |
+| Dry run | `session-ops run zendesk-digest --dry-run`; `uv run zendesk-triage --window-hours 72 --dry-run` from a checkout. On the host, through `systemd-run` as in [deploy/README.md](../../deploy/README.md). |
 | Re-run | `systemctl start session-ops@zendesk-digest.service` |
 | Logs | `journalctl -u session-ops@zendesk-digest -n 50 --no-pager` |