Phase 6: write important school events to the Home Assistant calendar

Add the Home Assistant REST calendar client and the idempotent sync that
writes important school events to Sam's Home Assistant calendar (FR-8). The
school stays read-only; the only write is to the calendar (rule 7).

- internal/calendar: HA REST client (states, create_event, get_events,
  delete_event) and the sync that selects important future events, adopts an
  existing event by its description marker, records the HA event id on the
  item, and records every attempt.
- internal/store: migration 003 (items.ha_event_uid, items.ha_pushed_at and
  the append-only calendar_pushes table), candidates, mark-synced and the
  push log.
- internal/parse: a school event is important; a routine class period is not.
- cmd/school: `school calendar entities|status|push|events`.
- web: an "Add to calendar" item action and a fail-loud calendar banner, so a
  failed write is never swallowed (FR-12).
- scripts/calendar-push.sh, Makefile target, env example, docs and tests.

The target is configurable (SCHOOL_HA_CALENDAR_ENTITY). Home Assistant has no
non-Google writable calendar today, so the entity is asked on AUD-110.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

internal/config/config.go

@@ -43,6 +43,52 @@ type Config struct {
 	// Location is the family timezone. Due dates and briefs are wall-clock, so
 	// this must be the family's zone, not the container default of UTC.
 	Location *time.Location
+	// Calendar is the Home Assistant calendar target for important school
+	// events (AGENTS.md §4 FR-8).
+	Calendar CalendarConfig
+}
+
+// CalendarConfig points at Sam's Home Assistant calendar. Every value comes
+// from the environment (environment.d); the token never reaches git, the
+// database or the logs (AGENTS.md §10 rule 3, AUD-110).
+//
+// Environment variables:
+//
+//	SCHOOL_HA_URL                base URL, for example http://192.168.20.30:8123
+//	SCHOOL_HA_TOKEN              long-lived access token (secret)
+//	SCHOOL_HA_CALENDAR_ENTITY    calendar entity id, for example calendar.school
+//	SCHOOL_HA_INSECURE           true to skip TLS verification (internal CA)
+//	SCHOOL_HA_TIMEOUT            per-request timeout, default 20s
+//
+// Calendar writing stays off until all three of URL, token and entity are set,
+// so the service still starts before the calendar is configured.
+type CalendarConfig struct {
+	BaseURL  string
+	Token    string
+	EntityID string
+	Insecure bool
+	Timeout  time.Duration
+}
+
+// Enabled reports whether the calendar target is fully configured.
+func (c CalendarConfig) Enabled() bool {
+	return c.BaseURL != "" && c.Token != "" && c.EntityID != ""
+}
+
+// Missing lists the environment variables that are still unset, in the order
+// the operator should set them. An empty result means the target is usable.
+func (c CalendarConfig) Missing() []string {
+	var out []string
+	if c.BaseURL == "" {
+		out = append(out, "SCHOOL_HA_URL")
+	}
+	if c.Token == "" {
+		out = append(out, "SCHOOL_HA_TOKEN")
+	}
+	if c.EntityID == "" {
+		out = append(out, "SCHOOL_HA_CALENDAR_ENTITY")
+	}
+	return out
 }
 
 // DefaultTimezone is the family timezone used when SCHOOL_TIMEZONE is unset.
@@ -90,6 +136,7 @@ func Load() (*Config, error) {
 		return nil, fmt.Errorf("SCHOOL_TIMEZONE: %w", err)
 	}
 	cfg.Location = loc
+	cfg.Calendar = loadCalendar()
 
 	return cfg, nil
 }
@@ -100,6 +147,7 @@ func Load() (*Config, error) {
 type DBConfig struct {
 	DBPath   string
 	Location *time.Location
+	Calendar CalendarConfig
 }
 
 // LoadDB reads the database path and the family timezone only.
@@ -111,9 +159,29 @@ func LoadDB() (*DBConfig, error) {
 	return &DBConfig{
 		DBPath:   env("SCHOOL_DB_PATH", "/data/school.db"),
 		Location: loc,
+		Calendar: loadCalendar(),
 	}, nil
 }
 
+// loadCalendar reads the Home Assistant calendar target. It never fails: an
+// empty value simply leaves the target disabled, so the service boots before
+// the calendar is configured and the calendar commands fail loudly instead.
+func loadCalendar() CalendarConfig {
+	timeout := 20 * time.Second
+	if v := strings.TrimSpace(os.Getenv("SCHOOL_HA_TIMEOUT")); v != "" {
+		if d, err := time.ParseDuration(v); err == nil && d > 0 {
+			timeout = d
+		}
+	}
+	return CalendarConfig{
+		BaseURL:  strings.TrimRight(strings.TrimSpace(os.Getenv("SCHOOL_HA_URL")), "/"),
+		Token:    strings.TrimSpace(os.Getenv("SCHOOL_HA_TOKEN")),
+		EntityID: strings.TrimSpace(os.Getenv("SCHOOL_HA_CALENDAR_ENTITY")),
+		Insecure: envBool("SCHOOL_HA_INSECURE", false),
+		Timeout:  timeout,
+	}
+}
+
 func env(key, fallback string) string {
 	if v := strings.TrimSpace(os.Getenv(key)); v != "" {
 		return v