docs(ops): add controlled auto-update schedules

README.md

@@ -839,6 +839,12 @@ curl -fsS http://127.0.0.1:8090/api/update
 ./scripts/foundrygate-auto-update --apply
 ```
 
+For controlled schedules, use the reviewed examples in:
+
+- [docs/examples/foundrygate-auto-update.service](./docs/examples/foundrygate-auto-update.service)
+- [docs/examples/foundrygate-auto-update.timer](./docs/examples/foundrygate-auto-update.timer)
+- [docs/examples/foundrygate-auto-update.cron](./docs/examples/foundrygate-auto-update.cron)
+
 ## Community And Security
 
 FoundryGate now includes the core public community-health files expected for a public open-source repo:

RELEASES.md

@@ -65,6 +65,23 @@ The repo also includes [publish-dry-run](./.github/workflows/publish-dry-run.yml
 
 The npm or TypeScript package should stay separate from the Python gateway core. It is meant for CLI-facing integrations, not for rewriting the service runtime.
 
+## Scheduled Deployment Examples
+
+FoundryGate now includes a conservative helper-driven update path for controlled environments. The recommended examples live in:
+
+- [docs/examples/foundrygate-auto-update.service](./docs/examples/foundrygate-auto-update.service)
+- [docs/examples/foundrygate-auto-update.timer](./docs/examples/foundrygate-auto-update.timer)
+- [docs/examples/foundrygate-auto-update.cron](./docs/examples/foundrygate-auto-update.cron)
+
+Use these only after you have already validated the manual path:
+
+```bash
+./scripts/foundrygate-update-check
+./scripts/foundrygate-auto-update
+```
+
+Keep `allow_major: false` unless you are intentionally allowing major-version rollouts through the scheduled helper.
+
 ## What Belongs In Release Notes
 
 - New providers or routing behavior changes

docs/ONBOARDING.md

@@ -112,3 +112,31 @@ Planned state:
 - scheduled use of `foundrygate-auto-update --apply` in controlled environments
 
 This remains opt-in. FoundryGate does not self-schedule or mutate the checkout over HTTP.
+
+### Controlled scheduling examples
+
+Use scheduling only after you are comfortable with the manual path:
+
+```bash
+./scripts/foundrygate-update-check
+./scripts/foundrygate-auto-update
+```
+
+Recommended `systemd` path:
+
+1. review [examples/foundrygate-auto-update.service](./examples/foundrygate-auto-update.service)
+2. review [examples/foundrygate-auto-update.timer](./examples/foundrygate-auto-update.timer)
+3. install them under `/etc/systemd/system/`
+4. enable the timer only after `auto_update.enabled: true` is set deliberately
+
+Minimal flow:
+
+```bash
+sudo install -m 644 docs/examples/foundrygate-auto-update.service /etc/systemd/system/foundrygate-auto-update.service
+sudo install -m 644 docs/examples/foundrygate-auto-update.timer /etc/systemd/system/foundrygate-auto-update.timer
+sudo systemctl daemon-reload
+sudo systemctl enable --now foundrygate-auto-update.timer
+sudo systemctl list-timers foundrygate-auto-update.timer
+```
+
+Cron remains possible for simpler hosts. The example is in [examples/foundrygate-auto-update.cron](./examples/foundrygate-auto-update.cron), but `systemd` timers are usually the safer default because they provide visibility and persistence.

docs/PUBLISHING.md

@@ -51,3 +51,18 @@ The real publish flow stays tag-driven through [release-artifacts](../.github/wo
 - Dry-run workflows should never require production credentials.
 - Real release publication should use GitHub environments and trusted publishing instead of long-lived secrets where possible.
 - PyPI publication should remain opt-in until the package workflow is stable across several releases.
+
+## Controlled Update Scheduling
+
+Release publishing and deployment updates should stay separate concerns.
+
+Publishing creates a tagged release. Applying that release on a host should remain a deliberate operator action or a tightly controlled scheduled helper.
+
+If you want scheduled update application:
+
+- keep `auto_update.enabled: true` explicit in `config.yaml`
+- keep `allow_major: false` unless you are ready to absorb breaking changes automatically
+- prefer the reviewed examples in [examples/foundrygate-auto-update.service](./examples/foundrygate-auto-update.service) and [examples/foundrygate-auto-update.timer](./examples/foundrygate-auto-update.timer)
+- use the cron example in [examples/foundrygate-auto-update.cron](./examples/foundrygate-auto-update.cron) only when `systemd` timers are not practical
+
+The helper still calls the normal update command. It does not bypass your service restart, health checks, or update guardrails.

docs/examples/foundrygate-auto-update.cron

@@ -0,0 +1,3 @@
+# Example cron entry for controlled FoundryGate auto-update checks.
+# Runs every day at 03:30 and only applies updates that the runtime marks as eligible.
+30 3 * * * foundrygate /usr/local/bin/foundrygate-auto-update --apply >>/var/log/foundrygate-auto-update.log 2>&1

docs/examples/foundrygate-auto-update.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=Apply eligible FoundryGate updates
+Documentation=https://github.com/typelicious/FoundryGate
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+User=foundrygate
+Group=foundrygate
+WorkingDirectory=/opt/foundrygate
+EnvironmentFile=/opt/foundrygate/.env
+ExecStart=/usr/local/bin/foundrygate-auto-update --apply
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/foundrygate /opt/foundrygate
+PrivateTmp=true

docs/examples/foundrygate-auto-update.timer

@@ -0,0 +1,12 @@
+[Unit]
+Description=Run the FoundryGate auto-update helper on a schedule
+Documentation=https://github.com/typelicious/FoundryGate
+
+[Timer]
+OnCalendar=*-*-* 03:30:00
+RandomizedDelaySec=15m
+Persistent=true
+Unit=foundrygate-auto-update.service
+
+[Install]
+WantedBy=timers.target