# 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

```yaml
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`.
