# Host-level systemd units on PIHA — declaration only.
#
# These are NOT docker-compose services, so they do not belong in services.yaml (whose
# entries the supervisor matches against world-state service keys; adding a non-container
# entry there would drift forever as missing_service). Nothing reads this file: it exists so
# the units installed outside the compose pipeline are written down in the repo rather than
# living only on the node and in a runbook.
#
# This is the "shadow-deploy family" the multiagent recon flags in its open question 5
# (kb/subsystems/recon-multiagent.md) — units installed outside GitOps drift detection.
# kb-mail-sync joins that list knowingly, not by oversight. When question 5 is settled, this
# file is the inventory to settle it against.
#
# Installation and activation are always operator steps. A `git pull` never starts a timer.

host: piha

systemd_units:
  kb-ingest:
    unit: kb-ingest.timer
    service: kb-ingest.service
    source: jobs/documents-ingest/systemd/
    schedule: "0/2:00:00"          # every 2 h — see the note in the .timer file
    runs_as: oskar
    environment_file: /opt/homelab/kb/.env
    log_path: /opt/homelab/logs/kb-ingest/
    metrics: /opt/homelab/state/node-exporter/kb-ingest.prom
    state: active                  # installed and enabled since 2026-07-30
    description: >
      Cyclic KB ingest: paperless adapter, chunk+embed, summarize, embed summaries, and
      (since 2026-08-06) the mail body stage that drains the unchunked-envelope queue
      mail-imap-sync fills. Both embed stages are gated on an Ollama@SOLARIA probe.

  kb-mail-sync:
    unit: kb-mail-sync.timer
    service: kb-mail-sync.service
    source: jobs/mail-imap-sync/systemd/
    schedule: hourly
    runs_as: oskar
    environment_file: /opt/homelab/kb/.env
    log_path: /opt/homelab/logs/kb-mail-sync/
    metrics: /opt/homelab/state/node-exporter/kb-mail-sync.prom
    state: declared                # NOT installed, NOT enabled — operator activates
    runbook: kb/runbooks/mail-sync-run.md
    description: >
      Incremental IMAP fetch for gmail (\All) and fastmail (INBOX, Archive, Sent) into the
      .eml archive and the envelope table. Network-bound, no GPU — which is why it lives on
      PIHA (24/7) and is decoupled from the embedding stages on SOLARIA (~16 h/day off).