# Upstream discovery for operator review

Run `scripts/watch-upstream-releases.py` on an operator machine from a **full
source checkout** with a private, persistent `--state` path. The sparse
development worktree does not contain `apps/` and cannot discover manifests.
`--offline` validates source coverage without network or state writes.
The watcher fails before changing state if no manifests or supported feeds are
present, so a sparse checkout cannot report an empty successful scan.

The prepared user-service and timer in `scripts/systemd/` run one bounded scan
hourly. Leave them disabled until the combined source is reviewed and the
operator has configured the private environment file with an absolute
`ARCHY_UPSTREAM_WATCHER` path in that full checkout. Alternatively,
`--interval-minutes 60` runs the same scan under an existing supervisor.
With an authenticated operator GitHub token, each hourly run checks every
eligible explicit `app.upstream` source with at most four concurrent requests;
the current source has 58 eligible feeds. Without a token, each run checks at
most four sources and prints `degraded_no_github_token`, so reduced coverage is
visible. Individual source or rate-limit failures appear in
`degraded_sources` without erasing prior observations. `internal` and `manual`
sources are excluded.

The JSON output contains only newly observed release tags and published GitHub
advisory IDs. The mode-0600 state file retains last-seen IDs and a durable
`pending_review` queue. A failed or rate-limited source does not clear prior
observations. Do not place credentials in arguments or logs; if a GitHub token
is needed, provide it through the operator's private environment.

These notices are **untrusted review leads**. An upstream release or advisory
does not change an installed image, an app manifest, or the card's installable
Update button. Review the source, assess any affected versions and migrations,
build and verify the candidate, then publish a signed Archipelago catalog
entry through the normal release process. Only that reviewed catalog can
advertise an installable update. No automatic installation is enabled.