flynn/docs/operations/OPERATOR_PACK.md

Operator Pack Runbook

This runbook documents the setup and operating model for Flynn's Operator Pack.

What It Configures

When enabled in flynn setup Automation, Operator Pack preconfigures:

• backup.enabled: true with cron schedule and output notifications.
• automation.heartbeat.enabled: true with output notifications.
• automation.daily_briefing.enabled: true with scheduled briefing output.
• automation.minio_sync.enabled: true with a default knowledge sync task (optional during setup).

Setup prompts for:

• Output routing: channel and peer (for backup + heartbeat + daily briefing + minio sync notifications).
• Backup cron schedule.
• Daily briefing cron schedule.
• Include/skip default MinIO sync task.

Recommended Baseline

backup:
  enabled: true
  schedule: "0 2 * * *"
  notify:
    channel: telegram
    peer: "123456789"

automation:
  heartbeat:
    enabled: true
    interval: "5m"
    notify:
      channel: telegram
      peer: "123456789"
    notify_cooldown: "30m"
  daily_briefing:
    enabled: true
    schedule: "0 8 * * *"
    output:
      channel: telegram
      peer: "123456789"
  minio_sync:
    enabled: true
    interval: "6h"
    run_on_start: true
    notify:
      channel: telegram
      peer: "123456789"
    tasks:
      - prefix: "knowledge/"
        namespace_base: "global/knowledge/minio"
        mode: append
        max_objects: 20
        max_chars_per_object: 8000
        force: false

Verification Checklist

1. Run flynn doctor --strict and verify zero failures/warnings.
2. Confirm heartbeat route is valid for the configured channel/peer.
3. Confirm backup cron and daily briefing cron schedules match operator expectations.
4. If using MinIO ingestion, confirm extractor dependencies via doctor output (MinIO ingest extractors).

Troubleshooting: Daily Briefing Calendar/Tasks Blocked

If the daily briefing reports Calendar or Tasks as blocked with insufficient permissions, re-run OAuth for both services to refresh scopes/tokens:

1. flynn gcal-auth
2. flynn gtasks-auth

Equivalent unified form:

1. flynn google-auth --service gcal
2. flynn google-auth --service gtasks

Expected scopes after re-auth:

• Calendar: https://www.googleapis.com/auth/calendar.readonly
• Tasks: https://www.googleapis.com/auth/tasks.readonly

Notes

• Heartbeat notification noise is controlled by automation.heartbeat.notify_cooldown (default 30m).
• If notify_cooldown is invalid, Flynn falls back to 30m and logs a warning.
• Re-running setup Automation detects an existing Operator Pack and asks whether to reconfigure.
• For context-pressure observability, monitor audit events session.checkpoint and session.auto_compact.