commit 1eddaca1ad2b461e97d75862ba196940c97560a3
Author: Jeena <hello@jeena.net>
Date:   Thu Mar 12 11:38:18 2026 +0000

    docs: Add backlog
    
    Document planned user stories to guide implementation of the update checker.

diff --git a/BACKLOG.md b/BACKLOG.md
new file mode 100644
index 0000000..8d03b45
--- /dev/null
+++ b/BACKLOG.md
@@ -0,0 +1,91 @@
+# Backlog: check-for-updates
+
+## US-01 - Parse Uptime Status Page
+
+As a maintainer, I want the script to fetch and parse the services listed on `https://uptime.jeena.net/status/everything` so that I have a normalized list of hosted services to check.
+
+Acceptance criteria:
+- Given the status page is reachable, the script extracts service name and URL for each monitored service.
+- Parsed services are normalized for consistent URL handling (scheme and trailing slash).
+- Failures to fetch or parse are reported with a clear error message and non-zero exit.
+
+## US-02 - Service Configuration Mapping
+
+As a maintainer, I want to provide a config file that maps services to upstream sources and version detection strategies so that the script can work reliably across heterogeneous services.
+
+Acceptance criteria:
+- The script accepts a `--config` CLI argument and reads a YAML/JSON/TOML file.
+- Each config entry supports: service name, URL, upstream type, repo identifier, and version strategy.
+- Invalid config formats are rejected with a clear error message.
+
+## US-03 - Version Detection Framework
+
+As a maintainer, I want a reusable framework of version detection strategies so that different services can report their running version reliably.
+
+Acceptance criteria:
+- The script supports a registry of detection strategies.
+- At least one strategy uses common version endpoints (e.g., `/version`, `/health`, `/api/version`).
+- The script records "unknown" when no version can be detected.
+
+## US-04 - Service-Specific Version Strategies
+
+As a maintainer, I want service-specific version detection for common tools (e.g., Gitea/Forgejo/Nextcloud/Miniflux) so that versions are detected accurately where possible.
+
+Acceptance criteria:
+- At least one named strategy queries a known service API endpoint.
+- Strategies can be selected per service via config.
+- If the service endpoint fails, the result is marked unknown without crashing the run.
+
+## US-05 - Upstream Release Lookup
+
+As a maintainer, I want to query upstream release APIs (GitHub and Codeberg) so that I can compare current and latest versions.
+
+Acceptance criteria:
+- The script can fetch the latest release for GitHub repositories.
+- The script can fetch the latest release for Codeberg repositories.
+- If no releases are available, the script can fall back to the latest tag.
+
+## US-06 - Version Normalization and Comparison
+
+As a maintainer, I want version strings normalized and compared consistently so that update checks are accurate.
+
+Acceptance criteria:
+- Versions are normalized to handle leading "v" and common tag formats.
+- Semantic versions are compared using a proper parser.
+- Unparseable versions are flagged and still reported.
+
+## US-07 - Update Report Output
+
+As a maintainer, I want the script to print only services with updates by default, and optionally all services, so that I can focus on actionable results.
+
+Acceptance criteria:
+- Default output includes only services where latest > running.
+- `--all` prints all services including up-to-date and unknown versions.
+- Output includes service name, running version, latest version, and upstream URL.
+
+## US-08 - CLI and Runtime Options
+
+As a maintainer, I want a simple CLI with timeouts and user-agent settings so that the script works reliably in different environments.
+
+Acceptance criteria:
+- The script supports `--timeout` and `--user-agent` flags.
+- Defaults are documented in `--help` output.
+- Invalid arguments produce a helpful error message.
+
+## US-09 - Resilience and Errors
+
+As a maintainer, I want network failures and API errors handled gracefully so that one bad service does not break the whole run.
+
+Acceptance criteria:
+- Network timeouts and HTTP errors are logged per service.
+- The script continues processing remaining services after a failure.
+- The final exit code is non-zero only for total failure (e.g., cannot fetch service list).
+
+## US-10 - Output Formatting and Exit Codes
+
+As a maintainer, I want consistent output formatting and exit codes so that this script can be used in cron jobs or CI.
+
+Acceptance criteria:
+- The script exits with code 0 when it completes a run.
+- The script exits with code 1 on unrecoverable setup failures.
+- Output is stable across runs for the same inputs.