{
  "openapi": "3.1.0",
  "info": {
    "title": "Marplanner HTTP API",
    "version": "1.0.0",
    "description": "Household planning API served by the Marplanner backend. Everything under `/api/*` requires the `mp_device_key` device cookie minted by `POST /api/auth/provision` (the plugin-management subtree `/api/plugins*` also admits an integration bearer key); `/health` is public. This document is generated from the zod route schemas in `src/server/openapi/` (`npm run generate:openapi`)."
  },
  "components": {
    "securitySchemes": {
      "deviceKeyCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "mp_device_key",
        "description": "The minted `*` device key (an `mpk-…` value). Set HttpOnly+Secure+SameSite=Lax at provisioning; never readable by client JS and never echoed in any response body.\n"
      },
      "integrationKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Existing raw-header integration credential whose live scopes include `*`."
      }
    },
    "schemas": {
      "ActivePeriodResult": {
        "type": "object",
        "properties": {
          "activeId": {
            "$ref": "#/components/schemas/PeriodId"
          }
        },
        "required": [
          "activeId"
        ],
        "additionalProperties": false
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "Assignment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "memberId": {
            "type": "string"
          },
          "weekdays": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "mon",
                "tue",
                "wed",
                "thu",
                "fri",
                "sat",
                "sun"
              ]
            }
          },
          "active": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "memberId",
          "weekdays",
          "active"
        ],
        "additionalProperties": false
      },
      "AssignmentReplace": {
        "type": "object",
        "properties": {
          "memberIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Full replacement set; each MUST be an active member (FR-006). Atomic replace."
          }
        },
        "required": [
          "memberIds"
        ],
        "additionalProperties": false
      },
      "AssignmentUpsert": {
        "type": "object",
        "properties": {
          "weekdays": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "mon",
                "tue",
                "wed",
                "thu",
                "fri",
                "sat",
                "sun"
              ]
            }
          },
          "active": {
            "type": "boolean",
            "default": true
          }
        },
        "required": [
          "weekdays"
        ],
        "additionalProperties": false,
        "description": "Upsert (create-or-edit) the one logical assignment row for (routineId, memberId) — reactivation reuses the existing row (FR-005). memberId MUST be an active child at write time (INV-01/FR-001).\n"
      },
      "AuthForbidden": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "const": "forbidden"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "credential_invalid",
              "scope_denied"
            ]
          }
        },
        "required": [
          "error",
          "message",
          "code"
        ],
        "additionalProperties": false
      },
      "AuthUnauthorized": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "const": "unauthorized"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "credential_invalid"
            ]
          }
        },
        "required": [
          "error",
          "message",
          "code"
        ],
        "additionalProperties": false
      },
      "AutoPrintTrigger": {
        "anyOf": [
          {
            "type": "string",
            "enum": [
              "morning_complete"
            ]
          },
          {
            "type": "null"
          }
        ]
      },
      "BackupListItem": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string"
          },
          "type": {
            "$ref": "#/components/schemas/BackupType"
          },
          "createdAt": {
            "type": "integer"
          },
          "sizeBytes": {
            "type": "integer"
          }
        },
        "required": [
          "filename",
          "type",
          "createdAt",
          "sizeBytes"
        ],
        "additionalProperties": false
      },
      "BackupListResponse": {
        "type": "object",
        "properties": {
          "backups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BackupListItem"
            }
          },
          "dbGeneration": {
            "type": "integer"
          },
          "lastBackupError": {
            "type": [
              "string",
              "null"
            ]
          },
          "lastPruneError": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "backups",
          "dbGeneration",
          "lastBackupError",
          "lastPruneError"
        ],
        "additionalProperties": false
      },
      "BackupType": {
        "type": "string",
        "enum": [
          "scheduled",
          "snapshot",
          "pre-restore",
          "upload"
        ]
      },
      "BackupsError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "BirthDate": {
        "type": "object",
        "properties": {
          "month": {
            "type": "integer",
            "minimum": 1,
            "maximum": 12
          },
          "day": {
            "type": "integer",
            "minimum": 1,
            "maximum": 31,
            "description": "calendar-valid for the month (app layer)"
          },
          "year": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "present only when known; null = no age, never invented (MEMBERS-AC-07)"
          }
        },
        "required": [
          "month",
          "day"
        ],
        "description": "Month/day always present when set; year optional. Feb 29 allowed with a null year.\n"
      },
      "BlockInstance": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/BlockType"
          },
          "scope": {
            "$ref": "#/components/schemas/BlockScope"
          },
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "failed"
            ]
          },
          "data": {
            "description": "Frozen block data, present for successful blocks."
          },
          "error": {
            "type": "string"
          },
          "index": {
            "type": "integer",
            "minimum": 1,
            "description": "1-based position in the member's full effective block order at generation; omitted blocks leave gaps (e.g. [1, 3]). Not a stable identity."
          },
          "title": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "params": {
            "$ref": "#/components/schemas/BlockParams"
          }
        },
        "required": [
          "type",
          "scope",
          "status"
        ],
        "additionalProperties": false
      },
      "BlockOrderInstance": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "params": {
            "$ref": "#/components/schemas/BlockParams"
          }
        },
        "required": [
          "type"
        ],
        "additionalProperties": false
      },
      "BlockParams": {
        "type": "object",
        "properties": {
          "level": {
            "type": "string",
            "enum": [
              "L1",
              "L2",
              "L3",
              "L4"
            ]
          },
          "difficulty": {
            "type": "string"
          },
          "language": {
            "type": "string",
            "description": "validated against corpus availability (FR-009)"
          },
          "count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 6,
            "description": "phonics only: how many words to print."
          }
        },
        "additionalProperties": false,
        "description": "Closed per-instance params (mirrors settings.ts ALLOWED_PARAM_KEYS; unknown keys are rejected 400 by validateParams —  fold closed this schema to match)."
      },
      "BlockScope": {
        "type": "string",
        "enum": [
          "shared",
          "member"
        ]
      },
      "BlockType": {
        "type": "string",
        "enum": [
          "calendar",
          "chores",
          "shotgun",
          "message",
          "streak",
          "today",
          "weather",
          "meals",
          "birthday",
          "reminders",
          "dadJoke",
          "wordOfDay",
          "animalFact",
          "numberFact",
          "onThisDay",
          "quoteOfDay",
          "trivia",
          "riddle",
          "wouldYouRather",
          "wordSearch",
          "drawingPrompt",
          "streakText",
          "weatherText",
          "phonics"
        ]
      },
      "BoardChore": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "completed": {
            "type": "boolean"
          },
          "icon": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "completed",
          "icon"
        ],
        "additionalProperties": false
      },
      "BoardColumn": {
        "type": "object",
        "properties": {
          "memberId": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "dayPeriods": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BoardDayPeriod"
            }
          },
          "streak": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Consecutive qualifying days ending at the most recent one (FR-013). Present (a number, possibly 0) ONLY when the requested date is today; null for any other date — the suppression (FR-014, INV-09) is enforced server-side, not left to the client to hide.\n"
          },
          "todayProgress": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "completed": {
                    "type": "integer"
                  },
                  "total": {
                    "type": "integer"
                  }
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Same today-only suppression as streak (FR-014)."
          }
        },
        "required": [
          "memberId",
          "displayName",
          "dayPeriods",
          "streak",
          "todayProgress"
        ],
        "additionalProperties": false,
        "description": "One active child's column (FR-017/FR-018)."
      },
      "BoardDayPeriod": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "morning",
              "afternoon",
              "evening",
              "night"
            ]
          },
          "labelKey": {
            "type": "string",
            "description": "i18n key, not display text (DAY-PERIODS-INV-04)."
          },
          "chores": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BoardChore"
            }
          }
        },
        "required": [
          "id",
          "labelKey",
          "chores"
        ],
        "additionalProperties": false,
        "description": "One of the four fixed periods, always present even when chores is empty (DAY-PERIODS-AC-05)."
      },
      "Briefing": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "memberId": {
            "type": "string"
          },
          "date": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/BriefingStatus"
          },
          "payload": {
            "$ref": "#/components/schemas/BriefingPayload"
          },
          "createdAt": {
            "type": "integer"
          },
          "updatedAt": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "memberId",
          "date",
          "status",
          "payload",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "BriefingHistoryEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "date": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/BriefingStatus"
          },
          "updatedAt": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "date",
          "status",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "BriefingHistoryResponse": {
        "type": "object",
        "properties": {
          "today": {
            "type": "string",
            "description": "household-timezone business date (YYYY-MM-DD)."
          },
          "entries": {
            "maxItems": 30,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BriefingHistoryEntry"
            }
          }
        },
        "required": [
          "today",
          "entries"
        ],
        "additionalProperties": false
      },
      "BriefingPayload": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "type": "integer",
            "enum": [
              1,
              2
            ]
          },
          "member": {
            "$ref": "#/components/schemas/MemberIdentitySnapshot"
          },
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD household-tz business date"
          },
          "blocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BlockInstance"
            }
          }
        },
        "required": [
          "schemaVersion",
          "member",
          "date",
          "blocks"
        ],
        "additionalProperties": false,
        "allOf": [
          {
            "if": {
              "properties": {
                "schemaVersion": {
                  "const": 1
                }
              },
              "required": [
                "schemaVersion"
              ]
            },
            "then": {
              "properties": {
                "blocks": {
                  "items": {
                    "properties": {
                      "type": {
                        "enum": [
                          "calendar",
                          "reminders",
                          "chores",
                          "meals",
                          "weather"
                        ]
                      }
                    }
                  }
                }
              }
            },
            "else": {
              "properties": {
                "blocks": {
                  "items": {
                    "properties": {
                      "type": {
                        "enum": [
                          "shotgun",
                          "message",
                          "streak",
                          "today",
                          "weather",
                          "meals",
                          "birthday",
                          "reminders",
                          "dadJoke",
                          "wordOfDay",
                          "animalFact",
                          "numberFact",
                          "onThisDay",
                          "quoteOfDay",
                          "trivia",
                          "riddle",
                          "wouldYouRather",
                          "wordSearch",
                          "drawingPrompt",
                          "streakText",
                          "weatherText",
                          "phonics"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "BriefingPreviewRendering": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "rendering"
            ]
          }
        },
        "required": [
          "status"
        ],
        "additionalProperties": false
      },
      "BriefingPrintResponse": {
        "type": "object",
        "properties": {
          "jobId": {
            "type": "string"
          },
          "enqueued": {
            "type": "boolean",
            "description": "false when a job for this briefing was already waiting and was reused."
          }
        },
        "required": [
          "jobId",
          "enqueued"
        ],
        "additionalProperties": false
      },
      "BriefingReadResultV2": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "generated": {
                "type": "boolean",
                "const": false
              }
            },
            "required": [
              "generated"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "generated": {
                "type": "boolean",
                "const": true
              },
              "briefing": {
                "$ref": "#/components/schemas/Briefing"
              },
              "printedStatus": {
                "$ref": "#/components/schemas/PrintedStatus"
              }
            },
            "required": [
              "generated",
              "briefing",
              "printedStatus"
            ],
            "additionalProperties": false
          }
        ],
        "description": "Pure read result with derived printed status for generated briefings."
      },
      "BriefingSchedule": {
        "type": "object",
        "properties": {
          "memberId": {
            "type": "string"
          },
          "weekdays": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Weekday"
            }
          }
        },
        "required": [
          "memberId",
          "weekdays"
        ],
        "additionalProperties": false
      },
      "BriefingScheduleInput": {
        "type": "object",
        "properties": {
          "weekdays": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Weekday"
            }
          }
        },
        "required": [
          "weekdays"
        ],
        "additionalProperties": false
      },
      "BriefingStatus": {
        "type": "string",
        "enum": [
          "pending",
          "ready",
          "partial",
          "failed",
          "render-failed"
        ]
      },
      "BuildInfo": {
        "type": "object",
        "properties": {
          "sha": {
            "type": [
              "string",
              "null"
            ]
          },
          "subject": {
            "description": "First line of the commit message.",
            "type": [
              "string",
              "null"
            ]
          },
          "builtAt": {
            "format": "date-time",
            "description": "Build time; null for a server running from source.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "sha",
          "subject",
          "builtAt"
        ],
        "additionalProperties": false,
        "description": "The commit a server or client bundle was built from; unknown parts are null."
      },
      "CalendarGatedAssignmentInput": {
        "type": "object",
        "properties": {
          "memberId": {
            "type": "string",
            "minLength": 1,
            "pattern": "\\S"
          },
          "weekdays": {
            "maxItems": 0,
            "type": "array",
            "items": {}
          }
        },
        "required": [
          "memberId"
        ],
        "additionalProperties": false
      },
      "CapabilityResponse": {
        "type": "object",
        "properties": {
          "registered": {
            "type": "boolean",
            "description": "always true on 200 — the calling session's key is now print-capable (FR-021, ADR-035)"
          }
        },
        "required": [
          "registered"
        ],
        "additionalProperties": false
      },
      "CelebrationSettings": {
        "type": "object",
        "properties": {
          "sound": {
            "type": "boolean",
            "description": "Play the fanfare with a completion celebration. Household-wide; reduced motion does not mute it."
          }
        },
        "required": [
          "sound"
        ],
        "additionalProperties": false,
        "description": "Household completion-celebration settings. Default `{ sound: true }`."
      },
      "Chore": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "routineId": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "sortOrder": {
            "type": "integer",
            "minimum": 0
          },
          "active": {
            "type": "boolean"
          },
          "icon": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "routineId",
          "name",
          "sortOrder",
          "active",
          "icon"
        ],
        "additionalProperties": false
      },
      "ChoreEditInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "routineId": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "icon": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": false,
        "description": "name, routineId (move to a different routine, FR-019), and/or active."
      },
      "ChoreInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "icon": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "ChoreOrderInput": {
        "type": "object",
        "properties": {
          "choreIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Full ordered list of the routine's active chore ids (atomic replace, FR-005/FR-006)."
          }
        },
        "required": [
          "choreIds"
        ],
        "additionalProperties": false
      },
      "ClaimResponse": {
        "type": "object",
        "properties": {
          "job": {
            "$ref": "#/components/schemas/PrintJob"
          },
          "leaseToken": {
            "type": "string"
          },
          "leaseExpiresAt": {
            "type": "integer"
          }
        },
        "required": [
          "job",
          "leaseToken",
          "leaseExpiresAt"
        ],
        "additionalProperties": false
      },
      "ClientLogBatch": {
        "type": "object",
        "properties": {
          "entries": {
            "type": "array",
            "items": {
              "description": "Each raw entry is validated independently; invalid entries and entries beyond the first 100 are dropped and counted. ClientLogEntryInput describes an admissible entry."
            }
          }
        },
        "required": [
          "entries"
        ],
        "additionalProperties": false
      },
      "ClientLogEntryInput": {
        "type": "object",
        "properties": {
          "level": {
            "$ref": "#/components/schemas/ClientLogLevel"
          },
          "component": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "message": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "data": {
            "description": "Arbitrary structured diagnostic values; bounded and redacted at ingest."
          },
          "eventTime": {
            "type": "integer",
            "description": "Client-claimed epoch ms; advisory only (received_at is authoritative)."
          }
        },
        "required": [
          "level",
          "component",
          "message"
        ],
        "additionalProperties": false
      },
      "ClientLogIngestResult": {
        "type": "object",
        "properties": {
          "accepted": {
            "type": "integer"
          },
          "dropped": {
            "type": "integer"
          }
        },
        "required": [
          "accepted",
          "dropped"
        ],
        "additionalProperties": false
      },
      "ClientLogLevel": {
        "type": "string",
        "enum": [
          "debug",
          "info",
          "warn",
          "error"
        ]
      },
      "ClientLogPage": {
        "type": "object",
        "properties": {
          "rows": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ClientLogRow"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "rows",
          "nextCursor"
        ],
        "additionalProperties": false
      },
      "ClientLogRow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "eventId": {
            "type": "string"
          },
          "eventTime": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "receivedAt": {
            "type": "integer"
          },
          "level": {
            "$ref": "#/components/schemas/ClientLogLevel"
          },
          "component": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "description": "Redacted, bounded JSON text exactly as stored, or null.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "eventId",
          "eventTime",
          "receivedAt",
          "level",
          "component",
          "message",
          "data"
        ],
        "additionalProperties": false
      },
      "CompletionInput": {
        "type": "object",
        "properties": {
          "memberId": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          }
        },
        "required": [
          "memberId",
          "date"
        ],
        "additionalProperties": false
      },
      "ConditionKey": {
        "type": "string",
        "enum": [
          "clear",
          "mostlyClear",
          "partlyCloudy",
          "overcast",
          "fog",
          "drizzle",
          "freezingDrizzle",
          "rain",
          "freezingRain",
          "snow",
          "snowGrains",
          "rainShowers",
          "snowShowers",
          "thunderstorm",
          "thunderstormHail",
          "unknown"
        ],
        "description": "Closed union from the single shared WMO map (WEATHER-INV-06)."
      },
      "ContributionIds": {
        "type": "array",
        "items": {
          "type": "string",
          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
        },
        "uniqueItems": true
      },
      "ControllerErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "machine code identifying which controller-degradation state this 502 represents — `controller_unavailable`, `controller_rejected`, or `controller_unreachable` (the three `NetworkDeviceController*Error` classes in src/server/modules/network-devices/index.ts, mapped via src/server/routes/network-devices.ts). Unlike the shared ErrorResponse, both fields are ALWAYS present on this response — every 502-mapped error class carries its own `code`."
          }
        },
        "required": [
          "error",
          "code"
        ],
        "additionalProperties": false
      },
      "CorpusLanguageUnavailableErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "corpus_language_unavailable"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "CreateMemberRequest": {
        "type": "object",
        "properties": {
          "displayName": {
            "type": "string",
            "minLength": 1
          },
          "colorKey": {
            "description": "Optional explicit key. If omitted, choose the first unused active-member key in palette order, or active-member count modulo ten after exhaustion. Archived members do not reserve keys. An explicit key that another active member holds is rejected (400) while any key is still unused.",
            "$ref": "#/components/schemas/MemberColorKey"
          },
          "role": {
            "type": "string",
            "enum": [
              "parent",
              "child"
            ],
            "description": "admin is rejected (MEMBERS-AC-01)"
          },
          "birthDate": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/BirthDate"
              },
              {
                "type": "null"
              }
            ],
            "description": "optional birth date; null or absent = no birth date set."
          },
          "celebration": {
            "description": "Optional; omitted stores `{ \"preset\": \"confetti\" }`.",
            "$ref": "#/components/schemas/MemberCelebration"
          }
        },
        "required": [
          "displayName",
          "role"
        ],
        "additionalProperties": false
      },
      "DailyBriefingSettingsInput": {
        "type": "object",
        "properties": {
          "generationTime": {
            "type": "string",
            "description": "strict 24h HH:MM"
          },
          "autoPrintTrigger": {
            "$ref": "#/components/schemas/AutoPrintTrigger"
          }
        },
        "additionalProperties": false
      },
      "DailyBriefingSettingsSnapshot": {
        "type": "object",
        "properties": {
          "generationTime": {
            "type": "string",
            "description": "strict 24h HH:MM"
          },
          "autoPrintTrigger": {
            "$ref": "#/components/schemas/AutoPrintTrigger"
          },
          "updatedAt": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "epoch-ms; null when no row exists yet"
          }
        },
        "required": [
          "generationTime",
          "autoPrintTrigger",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "DailyBriefingSettingsView": {
        "type": "object",
        "properties": {
          "generationTime": {
            "type": "string"
          },
          "autoPrintTrigger": {
            "$ref": "#/components/schemas/AutoPrintTrigger"
          },
          "blockOrder": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BlockOrderInstance"
            }
          },
          "memberBlockSettings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MemberBlockSettings"
            }
          },
          "memberSchedules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BriefingSchedule"
            },
            "description": "stored weekday pause schedules; members without one run every day (FR-023)."
          }
        },
        "required": [
          "generationTime",
          "autoPrintTrigger",
          "blockOrder",
          "memberBlockSettings",
          "memberSchedules"
        ],
        "additionalProperties": false
      },
      "DailyMessage": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "memberId": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD (household-local)"
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "stored verbatim."
          },
          "createdAt": {
            "type": "integer"
          },
          "updatedAt": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "memberId",
          "date",
          "text",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "DailyMessageUpsert": {
        "type": "object",
        "properties": {
          "memberId": {
            "type": "string",
            "description": "must reference an active members.id."
          },
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD (household-local)"
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "stored byte-for-byte verbatim (AC-07). Blank-after-trim / over-500-char rejection (AC-03/FR-005) is enforced on writes.\n"
          }
        },
        "required": [
          "memberId",
          "date",
          "text"
        ],
        "additionalProperties": false
      },
      "DayPeriod": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/PeriodId"
          },
          "labelKey": {
            "type": "string",
            "description": "i18n translation key (INV-04); never user-editable free text.",
            "example": "dayPeriod.morning"
          },
          "start": {
            "type": "string",
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Local start boundary HH:MM (the only stored boundary; end is derived).",
            "example": "05:00"
          },
          "sortOrder": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3,
            "description": "Canonical cycle position (morning=0 … night=3)."
          }
        },
        "required": [
          "id",
          "labelKey",
          "start",
          "sortOrder"
        ],
        "additionalProperties": false
      },
      "DeviceCredential": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "device",
              "integration",
              "bootstrap"
            ]
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "integer",
            "description": "epoch ms"
          },
          "expiresAt": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "epoch ms; null = no expiry"
          },
          "state": {
            "type": "string",
            "enum": [
              "active",
              "revoked",
              "expired"
            ]
          },
          "current": {
            "type": "boolean",
            "description": "the credential this request authenticated with"
          },
          "configuredBootstrap": {
            "type": "boolean",
            "description": "the bootstrap row MP_BOOTSTRAP_KEY names; startup re-activates it, so revoking it is refused"
          }
        },
        "required": [
          "id",
          "kind",
          "label",
          "createdAt",
          "expiresAt",
          "state",
          "current",
          "configuredBootstrap"
        ],
        "additionalProperties": false,
        "description": "An API credential without its key or key hash."
      },
      "DeviceCredentialError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "credential_not_found",
              "invalid_label",
              "configured_bootstrap"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "DeviceCredentialLabelRequest": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          }
        },
        "required": [
          "label"
        ],
        "additionalProperties": false,
        "description": "Trimmed before storing; 1 to 80 characters after trimming."
      },
      "DeviceCredentialList": {
        "type": "object",
        "properties": {
          "credentials": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeviceCredential"
            }
          }
        },
        "required": [
          "credentials"
        ],
        "additionalProperties": false
      },
      "DeviceCredentialRevokeResult": {
        "type": "object",
        "properties": {
          "credential": {
            "$ref": "#/components/schemas/DeviceCredential"
          },
          "revoked": {
            "type": "boolean",
            "description": "false when it was already revoked"
          }
        },
        "required": [
          "credential",
          "revoked"
        ],
        "additionalProperties": false
      },
      "DryRunInput": {
        "type": "object",
        "properties": {
          "memberId": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD, household-local strict calendar date."
          }
        },
        "required": [
          "memberId",
          "date"
        ],
        "additionalProperties": false,
        "description": "POST /api/reminders/{id}/dry-run body (handler-enforced allow-list, #397)."
      },
      "DryRunReason": {
        "type": "string",
        "enum": [
          "no_assigned_events",
          "matched_but_unassigned",
          "query_miss"
        ],
        "description": "The 3 mutually-exclusive reasons a calendar_gated rule would NOT emit (present iff wouldEmit=false), computed from up to 3 getEvents probes A/B/C. Precedence: no_assigned_events (probe A empty) -> matched_but_unassigned (probe C non-empty, gate probe B empty) -> query_miss (probe C empty) — matched_but_unassigned is checked BEFORE query_miss so it is reachable (finding #2).\n"
      },
      "DryRunResult": {
        "type": "object",
        "properties": {
          "wouldEmit": {
            "type": "boolean"
          },
          "reason": {
            "$ref": "#/components/schemas/DryRunReason"
          }
        },
        "required": [
          "wouldEmit"
        ],
        "description": "The verdict: would this calendar_gated rule emit for (memberId, date), and if not, why. wouldEmit=true iff the gate probe (member's assigned events matching the query) is non-empty; reason is present iff wouldEmit=false.\n"
      },
      "DumpInternalError": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "const": 500
          },
          "error": {
            "type": "string",
            "const": "Internal Server Error"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "statusCode",
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "EditDeviceRequest": {
        "type": "object",
        "properties": {
          "alias": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "memberId": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": false,
        "description": "The MAC is NOT editable — no property for it exists (INV-02)."
      },
      "EditStartRequest": {
        "type": "object",
        "properties": {
          "start": {
            "type": "string",
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
            "example": "11:30"
          }
        },
        "required": [
          "start"
        ],
        "additionalProperties": false
      },
      "EffectiveSettings": {
        "type": "object",
        "properties": {
          "locale": {
            "$ref": "#/components/schemas/LocaleObject"
          },
          "celebration": {
            "$ref": "#/components/schemas/CelebrationSettings"
          },
          "weather": {
            "$ref": "#/components/schemas/WeatherLocation"
          },
          "printer": {
            "$ref": "#/components/schemas/PrinterSettings"
          },
          "printerTransport": {
            "$ref": "#/components/schemas/PrinterTransportSettings"
          }
        },
        "required": [
          "locale",
          "celebration"
        ],
        "additionalProperties": false,
        "description": "Core settings and active plugin-owned settings, with defaults filling unpersisted fields. Weather is omitted while its plugin is inactive."
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable machine-readable error code or English diagnostic."
          },
          "message": {
            "type": "string",
            "description": "English diagnostic (Constitution X)."
          }
        },
        "required": [
          "error"
        ],
        "description": "Generic error envelope. Error bodies never contain `mpk-`/`mpg-` values or raw PINs (SC-004)."
      },
      "EventEditInput": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1
          },
          "allDay": {
            "type": "boolean"
          },
          "startDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "All-day half-open start (required when allDay=true; else null)."
          },
          "endDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "All-day exclusive end; MUST be > startDate (start==end rejected). *(FR-004/05)*"
          },
          "startUtc": {
            "type": "string",
            "format": "date-time",
            "description": "Timed start instant (required when allDay=false; else null). *(ADR-062)*"
          },
          "endUtc": {
            "type": "string",
            "format": "date-time",
            "description": "Timed end instant; MUST be >= startUtc."
          },
          "tzid": {
            "type": "string",
            "description": "IANA timezone the timed event was authored in (required when allDay=false). *(ADR-062)*",
            "example": "Europe/Madrid"
          },
          "rrule": {
            "description": "RFC-5545 RRULE; null = single occurrence. Supported subset: FREQ=DAILY|WEEKLY|MONTHLY|YEARLY with INTERVAL, COUNT, UNTIL, BYDAY, BYMONTHDAY, BYMONTH, WKST; anything else (sub-daily FREQ, BYHOUR/BYMINUTE/BYSECOND, BYSETPOS, BYYEARDAY, BYWEEKNO, a BYMONTH/BYMONTHDAY pair that never occurs) is a 400.",
            "example": "FREQ=WEEKLY;BYDAY=MO",
            "type": [
              "string",
              "null"
            ]
          },
          "exdates": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Excluded occurrences; preserved across an rrule edit (FR-014). Default []."
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 4000
              },
              {
                "type": "null"
              }
            ],
            "description": "Free text about the event; blank or null stores none."
          },
          "location": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 300
              },
              {
                "type": "null"
              }
            ],
            "description": "Where the event takes place; blank or null stores none."
          }
        },
        "additionalProperties": false,
        "description": "Partial edit. The server validates the merged stored state, including date shape, range and recurrence."
      },
      "EventInput": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1
          },
          "allDay": {
            "type": "boolean"
          },
          "startDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "All-day half-open start (required when allDay=true; else null)."
          },
          "endDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "All-day exclusive end; MUST be > startDate (start==end rejected). *(FR-004/05)*"
          },
          "startUtc": {
            "type": "string",
            "format": "date-time",
            "description": "Timed start instant (required when allDay=false; else null). *(ADR-062)*"
          },
          "endUtc": {
            "type": "string",
            "format": "date-time",
            "description": "Timed end instant; MUST be >= startUtc."
          },
          "tzid": {
            "type": "string",
            "description": "IANA timezone the timed event was authored in (required when allDay=false). *(ADR-062)*",
            "example": "Europe/Madrid"
          },
          "rrule": {
            "description": "RFC-5545 RRULE; null = single occurrence. Supported subset: FREQ=DAILY|WEEKLY|MONTHLY|YEARLY with INTERVAL, COUNT, UNTIL, BYDAY, BYMONTHDAY, BYMONTH, WKST; anything else (sub-daily FREQ, BYHOUR/BYMINUTE/BYSECOND, BYSETPOS, BYYEARDAY, BYWEEKNO, a BYMONTH/BYMONTHDAY pair that never occurs) is a 400.",
            "example": "FREQ=WEEKLY;BYDAY=MO",
            "type": [
              "string",
              "null"
            ]
          },
          "exdates": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Excluded occurrences; preserved across an rrule edit (FR-014). Default []."
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 4000
              },
              {
                "type": "null"
              }
            ],
            "description": "Free text about the event; blank or null stores none."
          },
          "location": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 300
              },
              {
                "type": "null"
              }
            ],
            "description": "Where the event takes place; blank or null stores none."
          }
        },
        "required": [
          "title",
          "allDay"
        ],
        "additionalProperties": false,
        "oneOf": [
          {
            "properties": {
              "allDay": {
                "const": true
              }
            },
            "required": [
              "startDate",
              "endDate"
            ],
            "not": {
              "anyOf": [
                {
                  "required": [
                    "startUtc"
                  ]
                },
                {
                  "required": [
                    "endUtc"
                  ]
                },
                {
                  "required": [
                    "tzid"
                  ]
                }
              ]
            }
          },
          {
            "properties": {
              "allDay": {
                "const": false
              }
            },
            "required": [
              "startUtc",
              "endUtc",
              "tzid"
            ],
            "not": {
              "anyOf": [
                {
                  "required": [
                    "startDate"
                  ]
                },
                {
                  "required": [
                    "endDate"
                  ]
                }
              ]
            }
          }
        ],
        "description": "Create payload. Exactly one date shape is required according to allDay; ranges, timezone and recurrence are validated by the service."
      },
      "ExternalSourceErrorCode": {
        "type": "string",
        "enum": [
          "unsafe_url",
          "unavailable",
          "timeout",
          "too_large",
          "invalid_calendar",
          "parse_failed",
          "reconcile_failed"
        ]
      },
      "ExternalSourcePatch": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "enabled"
        ],
        "additionalProperties": false
      },
      "ExternalSourceProvider": {
        "type": "string",
        "enum": [
          "google",
          "microsoft",
          "apple",
          "ics_generic"
        ]
      },
      "ExternalSourcePublic": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "provider": {
            "$ref": "#/components/schemas/ExternalSourceProvider"
          },
          "maskedUrl": {
            "type": "string",
            "description": "Origin plus masked path; no credentials or token."
          },
          "enabled": {
            "type": "boolean"
          },
          "pollIntervalMin": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1440
          },
          "phase": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/SynchronizationPhase"
              },
              {
                "type": "null"
              }
            ]
          },
          "lastAttemptAt": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "format": "int64"
          },
          "lastSuccessAt": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "format": "int64"
          },
          "lastErrorCode": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExternalSourceErrorCode"
              },
              {
                "type": "null"
              }
            ]
          },
          "consecutiveFailures": {
            "type": "integer",
            "minimum": 0
          },
          "lastImportedCount": {
            "type": "integer",
            "minimum": 0
          },
          "lastSkippedCount": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "id",
          "name",
          "provider",
          "maskedUrl",
          "enabled",
          "pollIntervalMin",
          "phase",
          "lastAttemptAt",
          "lastSuccessAt",
          "lastErrorCode",
          "consecutiveFailures",
          "lastImportedCount",
          "lastSkippedCount"
        ],
        "additionalProperties": false
      },
      "ExternalSourcePut": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "provider": {
            "type": "string",
            "description": "Unknown values normalize to ics_generic."
          },
          "feedUrl": {
            "type": "string",
            "format": "uri",
            "description": "Write-only HTTP(S) URL. Raw value is never returned."
          },
          "pollIntervalMin": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1440,
            "default": 15
          }
        },
        "required": [
          "name",
          "provider",
          "feedUrl"
        ],
        "additionalProperties": false
      },
      "FastifyParseErrorResponse": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer",
            "const": 400
          },
          "code": {
            "type": "string",
            "enum": [
              "FST_ERR_CTP_INVALID_JSON_BODY",
              "FST_ERR_CTP_EMPTY_JSON_BODY"
            ]
          },
          "error": {
            "type": "string",
            "enum": [
              "Bad Request"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "statusCode",
          "code",
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "FeedItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "master event id"
          },
          "occurrenceStart": {
            "type": "string",
            "description": "This occurrence's start — an instant (timed) or a YYYY-MM-DD (all-day)."
          },
          "occurrenceEnd": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "local",
              "external"
            ],
            "description": "local household-managed or external imported occurrence"
          },
          "title": {
            "type": "string"
          },
          "allDay": {
            "type": "boolean"
          },
          "tzid": {
            "description": "timed only",
            "type": [
              "string",
              "null"
            ]
          },
          "assignedTo": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Resolved active-member ids (series-level)."
          },
          "decoratedTitle": {
            "description": "Read-time highlight decoration (emoji prefix); never rewrites stored title.",
            "type": [
              "string",
              "null"
            ]
          },
          "provider": {
            "description": "Display-only external provider when source=external; null for local.",
            "type": [
              "string",
              "null"
            ]
          },
          "sourceRef": {
            "description": "Masked external source origin (`protocol//host/***`); null for local.",
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": "string",
            "description": "Plain text about the event — household-authored for local, as the feed sent it for external. Omitted when there is none."
          },
          "location": {
            "type": "string",
            "description": "Where the event takes place; omitted when there is none."
          }
        },
        "required": [
          "id",
          "occurrenceStart",
          "source",
          "title",
          "allDay",
          "assignedTo"
        ],
        "additionalProperties": false,
        "description": "One EXPANDED occurrence (not a master) returned by getEvents."
      },
      "ForbiddenError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "const": "forbidden"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message",
          "code"
        ],
        "additionalProperties": false
      },
      "ForbiddenErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "forbidden"
            ]
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "machine code from the shared auth boundary/capability seam (src/server/auth/boundary.ts + src/server/auth/capability.ts, fix #682) — `credential_invalid` (dead key: revoked/expired) or `scope_denied` (live key, denied on scope grounds) on a 403 from these cross-cutting preHandlers; optional here since older/other 403 emitters may not set it."
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "ForecastCurrent": {
        "type": "object",
        "properties": {
          "conditionKey": {
            "$ref": "#/components/schemas/ConditionKey"
          },
          "tempC": {
            "type": "number"
          },
          "rainPct": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "isDay": {
            "type": "boolean",
            "description": "Absent when the provider omits it."
          },
          "humidityPct": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Relative humidity. Absent when the provider omits it."
          },
          "windKmh": {
            "type": "number",
            "minimum": 0,
            "description": "Absent when the provider omits it."
          },
          "sunrise": {
            "type": "string",
            "description": "Today's sunrise, ISO datetime in household tz. Absent when the provider omits it."
          },
          "sunset": {
            "type": "string",
            "description": "Today's sunset, ISO datetime in household tz. Absent when the provider omits it."
          }
        },
        "required": [
          "conditionKey",
          "tempC",
          "rainPct"
        ],
        "additionalProperties": false
      },
      "ForecastDay": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD in household tz (WEATHER-INV-04)"
          },
          "conditionKey": {
            "$ref": "#/components/schemas/ConditionKey"
          },
          "tempMinC": {
            "type": "number"
          },
          "tempMaxC": {
            "type": "number"
          },
          "rainPct": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          }
        },
        "required": [
          "date",
          "conditionKey",
          "tempMinC",
          "tempMaxC",
          "rainPct"
        ],
        "additionalProperties": false
      },
      "ForecastHour": {
        "type": "object",
        "properties": {
          "time": {
            "type": "string",
            "description": "ISO datetime in household tz"
          },
          "conditionKey": {
            "$ref": "#/components/schemas/ConditionKey"
          },
          "tempC": {
            "type": "number"
          },
          "rainPct": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "isDay": {
            "type": "boolean",
            "description": "Absent when the provider omits it."
          }
        },
        "required": [
          "time",
          "conditionKey",
          "tempC",
          "rainPct"
        ],
        "additionalProperties": false
      },
      "GenerateAllInput": {
        "type": "object",
        "properties": {
          "date": {
            "description": "optional YYYY-MM-DD household-tz business date; defaults to household-tz today.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": false
      },
      "GenerateAllResponse": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "completed"
                ]
              },
              "count": {
                "type": "integer"
              },
              "generated": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "memberId": {
                      "type": "string"
                    },
                    "status": {
                      "$ref": "#/components/schemas/BriefingStatus"
                    }
                  },
                  "required": [
                    "memberId",
                    "status"
                  ]
                }
              }
            },
            "required": [
              "status",
              "count",
              "generated"
            ]
          },
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "already_running"
                ]
              }
            },
            "required": [
              "status"
            ]
          }
        ],
        "description": " US2: routed through the background-jobs scheduler's shared in-flight guard. `already_running` means a same-job run (scheduled, catch-up, or another manual call) was already in flight — no generation happened and no duplicate rows were written.\n"
      },
      "GenerateInput": {
        "type": "object",
        "properties": {
          "memberId": {
            "type": "string"
          },
          "date": {
            "description": "optional YYYY-MM-DD household-tz business date; defaults to household-tz today.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "memberId"
        ],
        "additionalProperties": false
      },
      "GenerateSkippedResponse": {
        "type": "object",
        "properties": {
          "skipped": {
            "type": "boolean",
            "const": true
          },
          "reason": {
            "type": "string",
            "enum": [
              "paused"
            ]
          },
          "memberId": {
            "type": "string"
          },
          "date": {
            "type": "string"
          }
        },
        "required": [
          "skipped",
          "reason",
          "memberId",
          "date"
        ],
        "additionalProperties": false
      },
      "Health": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "const": "ok"
          }
        },
        "required": [
          "status"
        ]
      },
      "HighlightRule": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "emoji": {
            "type": "string"
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "enabled": {
            "type": "boolean"
          },
          "priority": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "id",
          "emoji",
          "keywords",
          "enabled",
          "priority"
        ],
        "additionalProperties": false
      },
      "HighlightRuleCreate": {
        "type": "object",
        "properties": {
          "emoji": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32
          },
          "keywords": {
            "minItems": 1,
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            }
          }
        },
        "required": [
          "emoji",
          "keywords"
        ],
        "additionalProperties": false
      },
      "HighlightRuleOrder": {
        "type": "object",
        "properties": {
          "orderedIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "uniqueItems": true
          }
        },
        "required": [
          "orderedIds"
        ],
        "additionalProperties": false
      },
      "HighlightRulePatch": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "enabled"
        ],
        "additionalProperties": false
      },
      "InternalErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "internal_error"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "JobsListResponse": {
        "type": "object",
        "properties": {
          "jobs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PrintJob"
            }
          }
        },
        "required": [
          "jobs"
        ],
        "additionalProperties": false
      },
      "LiveCacheState": {
        "type": "string",
        "enum": [
          "unconfigured",
          "cold",
          "stale",
          "freshEmpty",
          "fresh"
        ]
      },
      "LiveClient": {
        "type": "object",
        "properties": {
          "mac": {
            "type": "string",
            "description": "canonical lowercase colon-separated"
          },
          "displayName": {
            "type": [
              "string",
              "null"
            ]
          },
          "isBlocked": {
            "type": "boolean"
          }
        },
        "required": [
          "mac",
          "displayName",
          "isBlocked"
        ],
        "additionalProperties": false
      },
      "LiveClientsResponse": {
        "type": "object",
        "properties": {
          "state": {
            "$ref": "#/components/schemas/LiveCacheState"
          },
          "clients": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LiveClient"
            }
          }
        },
        "required": [
          "state",
          "clients"
        ],
        "additionalProperties": false
      },
      "LocaleObject": {
        "type": "object",
        "properties": {
          "timezone": {
            "type": "string",
            "description": "IANA timezone, e.g. Europe/Madrid"
          },
          "language": {
            "type": "string",
            "enum": [
              "es",
              "en"
            ]
          },
          "weekStartDay": {
            "type": "integer",
            "enum": [
              0,
              1
            ]
          }
        },
        "required": [
          "timezone",
          "language",
          "weekStartDay"
        ],
        "additionalProperties": false,
        "description": "The complete canonical locale object — PUT is whole-object replace, so a write MUST carry all three fields (a language-only write would silently reset timezone/weekStartDay to defaults)."
      },
      "MealEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "recurring",
              "oneoff"
            ]
          },
          "mealPlanId": {
            "type": [
              "string",
              "null"
            ]
          },
          "weekday": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Weekday"
              },
              {
                "type": "null"
              }
            ]
          },
          "date": {
            "description": "YYYY-MM-DD (one-off only)",
            "type": [
              "string",
              "null"
            ]
          },
          "slot": {
            "$ref": "#/components/schemas/Slot"
          },
          "recipeId": {
            "type": [
              "string",
              "null"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "kind",
          "mealPlanId",
          "weekday",
          "date",
          "slot",
          "recipeId",
          "note",
          "createdAt"
        ],
        "description": "discriminated: recurring (mealPlanId+weekday) | oneoff (date); content recipeId xor note"
      },
      "MealEntryEditInput": {
        "type": "object",
        "properties": {
          "recipeId": {
            "type": "string",
            "description": "MUST reference an existing recipe (FR-028)"
          },
          "note": {
            "type": "string",
            "minLength": 1
          }
        },
        "additionalProperties": false,
        "description": "Content-only edit (Clarifications): recipeId xor note, still handler-enforced xor. To change date/weekday/slot, delete the entry and add a new one.\n",
        "minProperties": 1,
        "maxProperties": 1
      },
      "MealEntryInput": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "recurring",
              "oneoff"
            ]
          },
          "mealPlanId": {
            "type": "string",
            "description": "MUST reference an existing meal_plan (recurring only)"
          },
          "weekday": {
            "$ref": "#/components/schemas/Weekday"
          },
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD (oneoff only)"
          },
          "slot": {
            "$ref": "#/components/schemas/Slot"
          },
          "recipeId": {
            "type": "string",
            "description": "MUST reference an existing recipe (FR-028)"
          },
          "note": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "kind",
          "slot"
        ],
        "additionalProperties": false,
        "description": "recurring (mealPlanId+weekday, no date) | oneoff (date, no mealPlanId/weekday); content is recipeId xor note"
      },
      "MealPlan": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "active": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "integer"
          },
          "updatedAt": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "name",
          "active",
          "createdAt",
          "updatedAt"
        ],
        "description": "A named recurring menu template. Deactivate-only (no hard delete)."
      },
      "MealPlanEditInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "active": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "minProperties": 1,
        "description": "Rename and/or activate/deactivate; at least one property required."
      },
      "MealPlanInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "example": "Semana normal"
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "Member": {
        "type": "object",
        "properties": {
          "id": {
            "oneOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "string",
                "pattern": "^demo:member:[a-z0-9][a-z0-9-]*$"
              }
            ],
            "description": "Public creation generates UUIDs; the maintained public seed uses stable demo:member identities. Restores preserve those identities."
          },
          "displayName": {
            "type": "string"
          },
          "colorKey": {
            "$ref": "#/components/schemas/MemberColorKey"
          },
          "role": {
            "type": "string",
            "enum": [
              "parent",
              "child"
            ]
          },
          "lifecycle": {
            "type": "string",
            "enum": [
              "active",
              "archived"
            ],
            "description": "archive/restore transitions implemented (MEMBERS-INV-04)"
          },
          "birthDate": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/BirthDate"
              },
              {
                "type": "null"
              }
            ],
            "description": "null/absent when unset (FR-009a clear)."
          },
          "celebration": {
            "description": "Always present, defaults filled in. Archive and restore keep it.",
            "$ref": "#/components/schemas/MemberCelebration"
          },
          "createdAt": {
            "type": "integer"
          },
          "updatedAt": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "displayName",
          "colorKey",
          "role",
          "lifecycle",
          "celebration",
          "createdAt",
          "updatedAt"
        ]
      },
      "MemberBlockSettings": {
        "type": "object",
        "properties": {
          "memberId": {
            "type": "string"
          },
          "blockType": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "weekdays": {
            "anyOf": [
              {
                "minItems": 0,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "mon",
                    "tue",
                    "wed",
                    "thu",
                    "fri",
                    "sat",
                    "sun"
                  ]
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "`null` = all days (no mask). A present array is validated against the canonical mon..sun set — an unknown value is rejected 400, never silently dropped, so the persisted set always round-trips to EXACTLY what was accepted. `[]` (minItems: 0) is a distinct, legitimate third state from `null`: the block is masked out on every weekday, i.e. it never runs — 's generation-time weekday mask must not treat `[]` and `null` as equivalent (P2-3, batch-B review)."
          },
          "params": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/BlockParams"
              },
              {
                "type": "null"
              }
            ]
          },
          "updatedAt": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "memberId",
          "blockType",
          "enabled",
          "weekdays",
          "params",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "MemberBlockSettingsInput": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "weekdays": {
            "anyOf": [
              {
                "minItems": 0,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "mon",
                    "tue",
                    "wed",
                    "thu",
                    "fri",
                    "sat",
                    "sun"
                  ]
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "`null` = all days (no mask). A present array is validated against the canonical mon..sun set — an unknown value is rejected 400, never silently dropped, so the persisted set always round-trips to EXACTLY what was accepted. `[]` (minItems: 0) is a distinct, legitimate third state from `null`: the block is masked out on every weekday, i.e. it never runs — 's generation-time weekday mask must not treat `[]` and `null` as equivalent (P2-3, batch-B review)."
          },
          "params": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/BlockParams"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": false
      },
      "MemberCelebration": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "preset": {
                "type": "string",
                "enum": [
                  "confetti",
                  "stars",
                  "videogames",
                  "soccer",
                  "fairytale"
                ],
                "description": "A fixed set (src/shared/celebration.ts). `confetti` draws coloured paper with no emojis."
              }
            },
            "required": [
              "preset"
            ],
            "additionalProperties": false,
            "description": "A preset; it takes no `emojis`."
          },
          {
            "type": "object",
            "properties": {
              "preset": {
                "type": "string",
                "const": "custom"
              },
              "emojis": {
                "minItems": 1,
                "maxItems": 6,
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "1–6 distinct items, each exactly one emoji."
              }
            },
            "required": [
              "preset",
              "emojis"
            ],
            "additionalProperties": false,
            "description": "The member's own set."
          }
        ],
        "description": "The emoji set of the confetti played when the member finishes a block of chores: a preset, or `custom` with its own emojis."
      },
      "MemberColorKey": {
        "type": "string",
        "enum": [
          "blue",
          "sky",
          "teal",
          "green",
          "lime",
          "amber",
          "orange",
          "red",
          "pink",
          "violet"
        ],
        "description": "Curated screen identity only; never a CSS value or a monochrome print input."
      },
      "MemberIdentitySnapshot": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "displayName"
        ],
        "additionalProperties": false
      },
      "MenuItem": {
        "type": "object",
        "properties": {
          "entryId": {
            "type": "string"
          },
          "slot": {
            "$ref": "#/components/schemas/Slot"
          },
          "label": {
            "type": "string"
          },
          "isTombstone": {
            "type": "boolean"
          },
          "source": {
            "type": "string",
            "enum": [
              "recurring",
              "oneoff"
            ]
          },
          "planId": {
            "description": "The meal plan a recurring item comes from (its recurring entry's mealPlanId); null for a one-off item. Derived on read, never stored.\n",
            "type": [
              "string",
              "null"
            ]
          },
          "recipeId": {
            "type": [
              "string",
              "null"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "entryId",
          "slot",
          "label",
          "isTombstone",
          "source",
          "planId",
          "recipeId",
          "note"
        ]
      },
      "NetworkDeviceErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "machine code; `reselect_required` is the dedicated cache-rotation rejection (AC-03)"
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      },
      "NetworkDevicesListResponse": {
        "type": "object",
        "properties": {
          "devices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RegisteredDevice"
            }
          },
          "cacheState": {
            "$ref": "#/components/schemas/LiveCacheState"
          }
        },
        "required": [
          "devices",
          "cacheState"
        ],
        "additionalProperties": false
      },
      "NotFoundError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "not_found"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "NotFoundErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "not_found"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "OptInInput": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "enabled"
        ],
        "additionalProperties": false
      },
      "OptInState": {
        "type": "object",
        "properties": {
          "memberId": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "memberId",
          "enabled"
        ]
      },
      "OverlapError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "active_overlap"
            ]
          },
          "message": {
            "type": "string",
            "description": "Names the conflicting rule; plain rejection, no resolution UI (deferred)."
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "PeriodId": {
        "type": "string",
        "enum": [
          "morning",
          "afternoon",
          "evening",
          "night"
        ],
        "description": "Stable slug of one of the four fixed periods."
      },
      "PluginCatalogEntry": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/PluginId"
          },
          "label": {
            "type": "string",
            "minLength": 1
          },
          "description": {
            "type": "string",
            "minLength": 1
          },
          "trustTier": {
            "type": "string",
            "const": "first-party"
          },
          "contributions": {
            "$ref": "#/components/schemas/PluginContributionSummary"
          },
          "requirements": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "uniqueItems": true
          },
          "settingsSchema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PluginSettingDescriptor"
            }
          },
          "state": {
            "$ref": "#/components/schemas/PluginState"
          },
          "operation": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PluginOperation"
              },
              {
                "type": "null"
              }
            ]
          },
          "health": {
            "$ref": "#/components/schemas/PluginHealth"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "error": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PluginPublicError"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "label",
          "description",
          "trustTier",
          "contributions",
          "requirements",
          "settingsSchema",
          "state",
          "operation",
          "health",
          "updatedAt",
          "error"
        ],
        "additionalProperties": false
      },
      "PluginCatalogUnavailable": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "const": "plugin_catalog_unavailable"
          },
          "message": {
            "type": "string",
            "const": "The plugin catalog is temporarily unavailable."
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "PluginContributionSummary": {
        "type": "object",
        "properties": {
          "routes": {
            "$ref": "#/components/schemas/ContributionIds"
          },
          "admin": {
            "$ref": "#/components/schemas/ContributionIds"
          },
          "settings": {
            "$ref": "#/components/schemas/ContributionIds"
          },
          "widgets": {
            "$ref": "#/components/schemas/ContributionIds"
          },
          "services": {
            "$ref": "#/components/schemas/ContributionIds"
          },
          "jobs": {
            "$ref": "#/components/schemas/ContributionIds"
          }
        },
        "required": [
          "routes",
          "admin",
          "settings",
          "widgets",
          "services",
          "jobs"
        ],
        "additionalProperties": false
      },
      "PluginHealth": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "healthy",
              "attention"
            ]
          },
          "code": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PluginPublicErrorCode"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "status",
          "code"
        ],
        "additionalProperties": false
      },
      "PluginId": {
        "type": "string",
        "enum": [
          "daily-briefing",
          "printing",
          "weather",
          "time-announcements",
          "backups",
          "network-devices",
          "meals-recipes",
          "reminders",
          "daily-messages"
        ]
      },
      "PluginLifecycleFailed": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "const": "plugin_lifecycle_failed"
          },
          "message": {
            "type": "string",
            "const": "The plugin could not complete the requested lifecycle change."
          },
          "plugin": {
            "$ref": "#/components/schemas/PluginCatalogEntry"
          }
        },
        "required": [
          "code",
          "message",
          "plugin"
        ],
        "additionalProperties": false
      },
      "PluginOperation": {
        "type": "object",
        "properties": {
          "targetState": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ]
          },
          "startedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "targetState",
          "startedAt"
        ],
        "additionalProperties": false
      },
      "PluginPublicError": {
        "type": "object",
        "properties": {
          "code": {
            "$ref": "#/components/schemas/PluginPublicErrorCode"
          },
          "message": {
            "type": "string",
            "enum": [
              "Plugin settings could not be prepared.",
              "Plugin data could not be prepared.",
              "Plugin services could not be started.",
              "Plugin work could not stop safely.",
              "Plugin services could not be stopped.",
              "A plugin contribution failed.",
              "Plugin recovery requires attention."
            ]
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "PluginPublicErrorCode": {
        "type": "string",
        "enum": [
          "settings_initialization_failed",
          "migration_failed",
          "runtime_mount_failed",
          "drain_failed",
          "runtime_unmount_failed",
          "contribution_failed",
          "reconciliation_failed"
        ]
      },
      "PluginSettingDescriptor": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[a-z][A-Za-z0-9]*$"
          },
          "label": {
            "type": "string",
            "minLength": 1
          },
          "valueType": {
            "type": "string",
            "enum": [
              "string",
              "number",
              "boolean",
              "enum",
              "object"
            ]
          },
          "required": {
            "type": "boolean"
          },
          "sensitive": {
            "type": "boolean"
          }
        },
        "required": [
          "key",
          "label",
          "valueType",
          "required",
          "sensitive"
        ],
        "additionalProperties": false
      },
      "PluginState": {
        "type": "string",
        "enum": [
          "active",
          "inactive",
          "errored"
        ]
      },
      "PluginUnavailable": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "const": "plugin_unavailable"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "PrintJob": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "recordKey": {
            "type": "string"
          },
          "outputRef": {
            "type": "string",
            "description": "the producer's artifact reference — the raster is fetched via the producer's registered interface at execute (ADR-041)"
          },
          "targetDate": {
            "type": "string",
            "description": "YYYY-MM-DD household date"
          },
          "memberId": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "pending",
              "claimed",
              "printed",
              "failed",
              "cancelled"
            ]
          },
          "derivedState": {
            "type": "string",
            "enum": [
              "pending",
              "claimed",
              "printed",
              "failed",
              "cancelled",
              "dead-letter",
              "retrying"
            ],
            "description": "read-time refinement (Constitution V)"
          },
          "attempts": {
            "type": "integer",
            "description": "recoverable-failure count (contract retry vocabulary)"
          },
          "failureReason": {
            "type": [
              "string",
              "null"
            ]
          },
          "claimedAt": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "printedAt": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "createdAt": {
            "type": "integer"
          },
          "updatedAt": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "recordKey",
          "outputRef",
          "targetDate",
          "state",
          "derivedState",
          "attempts",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "PrintableRasterMissingErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "printable_raster_missing"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "PrintedStatus": {
        "type": "string",
        "enum": [
          "completed",
          "failed",
          "none",
          "unavailable"
        ],
        "description": "Derived (research D11) — see this file's own `/api/daily-briefing/{memberId}/{date}` GET description for the full derivation. Never stored as Printing's own canonical state."
      },
      "PrinterSettings": {
        "type": "object",
        "properties": {
          "paperWidthDots": {
            "type": "integer",
            "minimum": 1
          }
        },
        "required": [
          "paperWidthDots"
        ],
        "additionalProperties": false,
        "description": "Persisted printer configuration only; it does not assert a connected or capable printer."
      },
      "PrinterTransportSettings": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "deviceId": {
                "type": "string",
                "minLength": 1
              },
              "name": {
                "type": "string",
                "minLength": 1
              },
              "serviceUuid": {
                "type": "string",
                "format": "uuid"
              },
              "characteristicUuid": {
                "type": "string",
                "format": "uuid"
              }
            },
            "required": [
              "deviceId",
              "name",
              "serviceUuid",
              "characteristicUuid"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "deviceId": {
                "type": "string",
                "const": ""
              },
              "name": {
                "type": "string",
                "const": ""
              },
              "serviceUuid": {
                "type": "string",
                "const": ""
              },
              "characteristicUuid": {
                "type": "string",
                "const": ""
              }
            },
            "required": [
              "deviceId",
              "name",
              "serviceUuid",
              "characteristicUuid"
            ],
            "additionalProperties": false,
            "description": "Unconfigured: the default every field falls back to."
          }
        ],
        "description": "Private local transport configuration accepted only while Printing is active; it is not pairing, connectivity, capability, or activity state. Either all four fields are empty (unconfigured) or `deviceId`/`name` are non-empty and both UUIDs are well-formed."
      },
      "PrintingErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "machine code, present on a subset of errors: `printer_capability_missing` (403, FR-021) and `render_failure` (422, FR-017) are the two this contract maps with one; a plain 400 validation error omits it."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      },
      "PrintingPluginInactiveErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "plugin_inactive"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "PrintingStatusResponse": {
        "type": "object",
        "properties": {
          "active": {
            "type": "boolean",
            "description": "current printing-plugin-active state (INV-06); the client-side read FR-013's family-facing hiding gates on (issue 691) — PrintExecutor and the admin nav entry for PrintingManagement both hide when false"
          }
        },
        "required": [
          "active"
        ],
        "additionalProperties": false
      },
      "ProvisionRequest": {
        "type": "object",
        "properties": {
          "label": {
            "description": "Name for the new device key, trimmed, 1 to 80 characters after trimming. Scripts and CLIs send `os.hostname()`.",
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          }
        },
        "additionalProperties": false,
        "description": "Optional. Without a label (no body, or `{}`) the server derives one from the User-Agent as `<Browser> · <OS> · <YYYY-MM-DD>` in the household timezone, or `Device · <YYYY-MM-DD>` without a User-Agent. The User-Agent is a display hint only and never an authorization input.\n"
      },
      "ProvisionResult": {
        "type": "object",
        "properties": {
          "provisioned": {
            "type": "boolean",
            "const": true
          }
        },
        "required": [
          "provisioned"
        ],
        "description": "Success body carries NO raw key — the minted device key is delivered only via Set-Cookie (FR-007). The raw key never appears here or in any error body (SC-004).\n"
      },
      "QueryFields": {
        "minItems": 1,
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "title",
            "description",
            "location"
          ]
        }
      },
      "Quiescing": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "const": "quiescing"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "Recipe": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "ingredients": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "instructions": {
            "type": [
              "string",
              "null"
            ]
          },
          "slots": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Slot"
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "createdAt": {
            "type": "integer"
          },
          "updatedAt": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "name",
          "ingredients",
          "instructions",
          "slots",
          "createdAt",
          "updatedAt"
        ]
      },
      "RecipeDependentCounts": {
        "type": "object",
        "properties": {
          "recurringCount": {
            "type": "integer"
          },
          "oneOffCount": {
            "type": "integer"
          }
        },
        "required": [
          "recurringCount",
          "oneOffCount"
        ],
        "description": "Split dependent counts, advisory pre-delete (AC-06)."
      },
      "RecipeEditInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "ingredients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "instructions": {
            "type": "string"
          },
          "slots": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Slot"
            }
          }
        },
        "additionalProperties": false,
        "minProperties": 1,
        "description": "Partial edit; at least one property required."
      },
      "RecipeInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "example": "Lentejas"
          },
          "ingredients": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "One entry per line; blanks dropped module-side."
          },
          "instructions": {
            "type": "string",
            "description": "Blank-after-trim normalizes to absent."
          },
          "slots": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Slot"
            },
            "description": "Absent/empty means suitable for all slots (picker suggestion only)."
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "RegisterDeviceRequest": {
        "type": "object",
        "properties": {
          "mac": {
            "type": "string",
            "description": "must be present in the CURRENT fresh live cache (AC-03) — otherwise 409 reselect"
          },
          "alias": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "memberId": {
            "description": "must resolve to an ACTIVE member (AC-07)",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "mac",
          "alias"
        ],
        "additionalProperties": false
      },
      "RegisteredDevice": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "mac": {
            "type": "string"
          },
          "alias": {
            "type": "string"
          },
          "memberId": {
            "type": [
              "string",
              "null"
            ]
          },
          "memberLabel": {
            "type": [
              "string",
              "null"
            ]
          },
          "memberInactive": {
            "type": "boolean"
          },
          "isBlocked": {
            "type": "boolean",
            "description": "the local BELIEF mirror (INV-04)"
          },
          "beliefDiverged": {
            "type": "boolean",
            "description": "true when a mirror write failed after controller success (AC-02); cleared by the converging poll"
          },
          "lastSeenAt": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "epoch ms, observation-only (INV-10)"
          },
          "liveStatus": {
            "type": "string",
            "enum": [
              "online",
              "notDetected",
              "unknown"
            ],
            "description": "derived at read time, never persisted (INV-04)"
          }
        },
        "required": [
          "id",
          "mac",
          "alias",
          "memberId",
          "memberLabel",
          "memberInactive",
          "isBlocked",
          "beliefDiverged",
          "lastSeenAt",
          "liveStatus"
        ],
        "additionalProperties": false
      },
      "Reminder": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "scheduled",
              "calendar_gated"
            ],
            "description": "immutable after creation."
          },
          "targetingMode": {
            "type": "string",
            "enum": [
              "apply_to_all",
              "specific"
            ],
            "description": "editable through PATCH (FR-019); kind is immutable."
          },
          "contentType": {
            "$ref": "#/components/schemas/ReminderContentType"
          },
          "text": {
            "type": "string",
            "description": "parent-authored, stored as authored (trimmed). Non-blank for a `text` reminder; an optional, possibly empty, description of an `images` reminder."
          },
          "emojis": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReminderEmojis"
              },
              {
                "type": "null"
              }
            ],
            "description": "the emoji sequence of an `images` reminder; null for `text`."
          },
          "weekdays": {
            "oneOf": [
              {
                "minItems": 1,
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Weekday"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "rule-level weekday set for apply_to_all; null for specific (per-member weekdays live on each assignment). Cross-field discriminant (INV-09).\n"
          },
          "active": {
            "type": "boolean"
          },
          "assignments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReminderAssignment"
            },
            "description": "active assignments embedded in GET reads (the member x weekday matrix source); populated for specific-mode rules, empty array for apply_to_all.\n"
          },
          "query": {
            "type": [
              "string",
              "null"
            ]
          },
          "queryFields": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/QueryFields"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "kind",
          "targetingMode",
          "contentType",
          "text",
          "emojis",
          "weekdays",
          "active",
          "assignments"
        ],
        "additionalProperties": false,
        "description": "Stored discriminated rule. Scheduled specific assignments carry non-empty weekdays; calendar-gated assignments carry empty weekdays and a query. Active-member and uniqueness invariants are enforced by the service.",
        "allOf": [
          {
            "if": {
              "properties": {
                "kind": {
                  "const": "scheduled"
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "properties": {
                "query": {
                  "type": "null"
                },
                "queryFields": {
                  "type": "null"
                },
                "assignments": {
                  "items": {
                    "properties": {
                      "weekdays": {
                        "minItems": 1
                      }
                    }
                  }
                }
              },
              "if": {
                "properties": {
                  "targetingMode": {
                    "const": "apply_to_all"
                  }
                },
                "required": [
                  "targetingMode"
                ]
              },
              "then": {
                "properties": {
                  "weekdays": {
                    "type": "array",
                    "minItems": 1
                  }
                }
              },
              "else": {
                "properties": {
                  "weekdays": {
                    "type": "null"
                  }
                }
              }
            },
            "else": {
              "properties": {
                "weekdays": {
                  "type": "null"
                },
                "query": {
                  "type": "string",
                  "minLength": 1,
                  "pattern": "\\S"
                },
                "queryFields": {
                  "$ref": "#/components/schemas/QueryFields"
                },
                "assignments": {
                  "items": {
                    "properties": {
                      "weekdays": {
                        "maxItems": 0
                      }
                    }
                  }
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "targetingMode": {
                  "const": "apply_to_all"
                }
              },
              "required": [
                "targetingMode"
              ]
            },
            "then": {
              "properties": {
                "assignments": {
                  "maxItems": 0
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "contentType": {
                  "const": "images"
                }
              },
              "required": [
                "contentType"
              ]
            },
            "then": {
              "properties": {
                "emojis": {
                  "$ref": "#/components/schemas/ReminderEmojis"
                }
              }
            },
            "else": {
              "properties": {
                "text": {
                  "minLength": 1,
                  "pattern": "\\S"
                },
                "emojis": {
                  "type": "null"
                }
              }
            }
          }
        ]
      },
      "ReminderAssignment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "memberId": {
            "type": "string"
          },
          "weekdays": {
            "minItems": 0,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Weekday"
            }
          },
          "active": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "memberId",
          "weekdays",
          "active"
        ],
        "additionalProperties": false
      },
      "ReminderAssignmentInput": {
        "type": "object",
        "properties": {
          "memberId": {
            "type": "string",
            "minLength": 1,
            "pattern": "\\S"
          },
          "weekdays": {
            "minItems": 1,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Weekday"
            }
          }
        },
        "required": [
          "memberId",
          "weekdays"
        ],
        "additionalProperties": false
      },
      "ReminderAssignmentSetInput": {
        "type": "object",
        "properties": {
          "assignments": {
            "minItems": 1,
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ReminderAssignmentInput"
                },
                {
                  "$ref": "#/components/schemas/CalendarGatedAssignmentInput"
                }
              ]
            }
          }
        },
        "required": [
          "assignments"
        ],
        "additionalProperties": false,
        "description": "The full desired active assignment set for a specific-mode rule. Applied atomically (last-write-wins, no If-Match/409 — deferred #395): members present are upserted, members absent are deactivated. MUST be non-empty (a specific rule may not drop to zero active assignments — INV-02).\n The stored rule kind determines whether weekdays must be non-empty (scheduled) or absent/empty (calendar_gated)."
      },
      "ReminderContentType": {
        "type": "string",
        "enum": [
          "text",
          "images"
        ],
        "description": "What the reminder shows: words (`text`) or an ordered emoji sequence (`images`) for family members who cannot read yet."
      },
      "ReminderEditInput": {
        "type": "object",
        "properties": {
          "contentType": {
            "description": "switching to images requires emojis; switching to text requires a non-blank text (given, or the stored description) and clears emojis.",
            "$ref": "#/components/schemas/ReminderContentType"
          },
          "text": {
            "type": "string",
            "description": "must be non-blank when the resulting contentType is text."
          },
          "emojis": {
            "description": "full replacement list; accepted only when the resulting contentType is images.",
            "$ref": "#/components/schemas/ReminderEmojis"
          },
          "weekdays": {
            "minItems": 1,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Weekday"
            }
          },
          "active": {
            "type": "boolean"
          },
          "targetingMode": {
            "type": "string",
            "enum": [
              "apply_to_all",
              "specific"
            ]
          },
          "assignments": {
            "minItems": 1,
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ReminderAssignmentInput"
                },
                {
                  "$ref": "#/components/schemas/CalendarGatedAssignmentInput"
                }
              ]
            },
            "description": "full desired set; accepted only when the resulting targetingMode is specific."
          },
          "query": {
            "type": "string",
            "minLength": 1,
            "pattern": "\\S"
          },
          "queryFields": {
            "$ref": "#/components/schemas/QueryFields"
          }
        },
        "additionalProperties": false,
        "description": "Partial edit; kind is immutable. targetingMode may switch between apply_to_all and specific. Switching to specific requires assignments; switching a scheduled rule to apply_to_all requires weekdays; a calendar_gated rule switching to apply_to_all needs nothing extra. Weekdays are valid only when the resulting mode is apply_to_all on a scheduled rule; assignments only when the resulting mode is specific (full-set replace). Query fields only on stored calendar_gated rules. These state-dependent constraints are enforced by the service; a rejected edit persists nothing. Switching to apply_to_all deactivates (never deletes) the rule's active assignments.",
        "minProperties": 1,
        "not": {
          "allOf": [
            {
              "required": [
                "weekdays"
              ]
            },
            {
              "anyOf": [
                {
                  "required": [
                    "query"
                  ]
                },
                {
                  "required": [
                    "queryFields"
                  ]
                }
              ]
            }
          ]
        }
      },
      "ReminderEmission": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "emojis": {
            "$ref": "#/components/schemas/ReminderEmojis"
          }
        },
        "required": [
          "id",
          "text"
        ],
        "additionalProperties": false,
        "description": "one emitting reminder for a (member,date); ordering/priority deferred to Daily Briefing. `emojis` is present only for an `images` reminder, whose `text` is then its (possibly empty) description."
      },
      "ReminderEmojis": {
        "minItems": 1,
        "maxItems": 12,
        "type": "array",
        "items": {
          "type": "string",
          "minLength": 1
        },
        "description": "Ordered catalog emojis of an `images` reminder (1–12; repeats allowed). Each must be one the app ships a Noto SVG for; others are rejected 400."
      },
      "ReminderInput": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "scheduled",
              "calendar_gated"
            ]
          },
          "targetingMode": {
            "type": "string",
            "enum": [
              "apply_to_all",
              "specific"
            ]
          },
          "contentType": {
            "description": "defaults to text.",
            "$ref": "#/components/schemas/ReminderContentType"
          },
          "text": {
            "type": "string",
            "description": "required and non-blank for a text reminder; an optional description for images."
          },
          "emojis": {
            "description": "required iff contentType=images; rejected for text.",
            "$ref": "#/components/schemas/ReminderEmojis"
          },
          "weekdays": {
            "minItems": 1,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Weekday"
            },
            "description": "required iff targetingMode=apply_to_all; rejected for specific."
          },
          "assignments": {
            "minItems": 1,
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ReminderAssignmentInput"
                },
                {
                  "$ref": "#/components/schemas/CalendarGatedAssignmentInput"
                }
              ]
            },
            "description": "required iff targetingMode=specific; rejected for apply_to_all."
          },
          "query": {
            "type": "string",
            "minLength": 1,
            "pattern": "\\S"
          },
          "queryFields": {
            "$ref": "#/components/schemas/QueryFields"
          }
        },
        "required": [
          "kind",
          "targetingMode"
        ],
        "additionalProperties": false,
        "description": "Scheduled rules require weekday targeting; calendar-gated rules require a query and membership-only targeting. Active-member and duplicate checks are enforced by the service.",
        "allOf": [
          {
            "if": {
              "properties": {
                "contentType": {
                  "const": "images"
                }
              },
              "required": [
                "contentType"
              ]
            },
            "then": {
              "required": [
                "emojis"
              ]
            },
            "else": {
              "required": [
                "text"
              ],
              "properties": {
                "text": {
                  "minLength": 1,
                  "pattern": "\\S"
                }
              },
              "not": {
                "required": [
                  "emojis"
                ]
              }
            }
          },
          {
            "if": {
              "properties": {
                "kind": {
                  "const": "scheduled"
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "not": {
                "anyOf": [
                  {
                    "required": [
                      "query"
                    ]
                  },
                  {
                    "required": [
                      "queryFields"
                    ]
                  }
                ]
              },
              "if": {
                "properties": {
                  "targetingMode": {
                    "const": "apply_to_all"
                  }
                },
                "required": [
                  "targetingMode"
                ]
              },
              "then": {
                "required": [
                  "weekdays"
                ],
                "not": {
                  "required": [
                    "assignments"
                  ]
                }
              },
              "else": {
                "required": [
                  "assignments"
                ],
                "not": {
                  "required": [
                    "weekdays"
                  ]
                },
                "properties": {
                  "assignments": {
                    "items": {
                      "$ref": "#/components/schemas/ReminderAssignmentInput"
                    }
                  }
                }
              }
            },
            "else": {
              "required": [
                "query"
              ],
              "not": {
                "required": [
                  "weekdays"
                ]
              },
              "properties": {
                "assignments": {
                  "items": {
                    "$ref": "#/components/schemas/CalendarGatedAssignmentInput"
                  }
                }
              },
              "if": {
                "properties": {
                  "targetingMode": {
                    "const": "specific"
                  }
                },
                "required": [
                  "targetingMode"
                ]
              },
              "then": {
                "required": [
                  "assignments"
                ]
              },
              "else": {
                "not": {
                  "required": [
                    "assignments"
                  ]
                }
              }
            }
          }
        ]
      },
      "ResetTodayPrintsResponse": {
        "type": "object",
        "properties": {
          "targetDate": {
            "type": "string",
            "description": "household-local today (YYYY-MM-DD) whose print records were reset"
          },
          "resetRecords": {
            "type": "integer",
            "minimum": 0,
            "description": "print records made printable again (superseded)"
          },
          "cancelledJobs": {
            "type": "integer",
            "minimum": 0,
            "description": "pending or claimed-not-yet-fetched jobs cancelled; fetched jobs finish (H2)"
          }
        },
        "required": [
          "targetDate",
          "resetRecords",
          "cancelledJobs"
        ],
        "additionalProperties": false
      },
      "RestoreRequest": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string"
          },
          "confirmFilename": {
            "type": "string"
          }
        },
        "required": [
          "filename",
          "confirmFilename"
        ],
        "additionalProperties": false
      },
      "RestoreResult": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "restored"
                ]
              },
              "dbGeneration": {
                "type": "integer"
              },
              "migrated": {
                "type": "boolean"
              }
            },
            "required": [
              "status",
              "dbGeneration",
              "migrated"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "validation_error",
                  "confirmation_mismatch",
                  "incompatible_backup",
                  "downgrade_rejected",
                  "unsupported_lineage",
                  "restore_in_progress",
                  "snapshot_in_progress",
                  "quiesce_timeout",
                  "pre_restore_failed",
                  "swap_failed",
                  "migration_failed_rolled_back",
                  "rollback_failed",
                  "retention_floor",
                  "protected_pre_restore",
                  "upload_too_large",
                  "backup_failed",
                  "not_found"
                ]
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "status"
            ],
            "additionalProperties": false
          }
        ]
      },
      "RouteError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "not_found",
              "internal_error"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "Routine": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "dayPeriodId": {
            "type": "string",
            "description": "Day period the routine belongs to; PATCH may move it (FR-015)."
          },
          "active": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "name",
          "dayPeriodId",
          "active"
        ],
        "additionalProperties": false
      },
      "RoutineEditInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "active": {
            "type": "boolean"
          },
          "dayPeriodId": {
            "type": "string",
            "minLength": 1,
            "description": "Moves the routine to another existing day period; blank or unknown values are rejected (FR-015)."
          }
        },
        "additionalProperties": false,
        "description": "Edit payload — any of name, active and dayPeriodId (FR-015)."
      },
      "RoutineInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "dayPeriodId": {
            "type": "string",
            "description": "must reference an existing day_periods.id."
          }
        },
        "required": [
          "name",
          "dayPeriodId"
        ],
        "additionalProperties": false,
        "description": "Create payload."
      },
      "Slot": {
        "type": "string",
        "enum": [
          "breakfast",
          "lunch",
          "snack",
          "dinner"
        ]
      },
      "SnapshotResult": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "completed"
                ]
              },
              "filename": {
                "type": "string"
              }
            },
            "required": [
              "status",
              "filename"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "already_running"
                ]
              }
            },
            "required": [
              "status"
            ],
            "additionalProperties": false
          }
        ]
      },
      "SynchronizationPhase": {
        "type": "string",
        "enum": [
          "requesting",
          "downloading",
          "parsing",
          "reconciling",
          "succeeded",
          "failed"
        ]
      },
      "SystemStatus": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "checkedAt": {
            "type": "string",
            "format": "date-time"
          },
          "uptimeSeconds": {
            "type": "integer",
            "minimum": 0,
            "description": "Whole seconds since the server process started."
          },
          "build": {
            "$ref": "#/components/schemas/BuildInfo"
          }
        },
        "required": [
          "status",
          "checkedAt",
          "uptimeSeconds",
          "build"
        ],
        "additionalProperties": false
      },
      "TestPrintResponse": {
        "type": "object",
        "properties": {
          "enqueued": {
            "type": "boolean"
          },
          "jobId": {
            "type": [
              "string",
              "null"
            ]
          },
          "alreadyPrinted": {
            "type": "boolean",
            "description": "true when FR-012 dedup suppressed the enqueue"
          }
        },
        "required": [
          "enqueued"
        ],
        "additionalProperties": false
      },
      "TimeAnnouncementRule": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "time": {
            "type": "string",
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Strict 24h HH:MM, stored exactly as written (never normalized)."
          },
          "weekDays": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "mon",
                "tue",
                "wed",
                "thu",
                "fri",
                "sat",
                "sun"
              ]
            },
            "uniqueItems": true,
            "description": "Non-empty canonical set, no duplicates, canonical order on read."
          },
          "isActive": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "integer",
            "description": "epoch ms"
          },
          "updatedAt": {
            "type": "integer",
            "description": "epoch ms"
          }
        },
        "required": [
          "id",
          "time",
          "weekDays",
          "isActive",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "TimeAnnouncementRuleCreate": {
        "type": "object",
        "properties": {
          "time": {
            "type": "string",
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
          },
          "weekDays": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "mon",
                "tue",
                "wed",
                "thu",
                "fri",
                "sat",
                "sun"
              ]
            },
            "uniqueItems": true
          },
          "isActive": {
            "type": "boolean",
            "default": true
          }
        },
        "required": [
          "time",
          "weekDays"
        ],
        "additionalProperties": false
      },
      "TimeAnnouncementRulePatch": {
        "type": "object",
        "properties": {
          "time": {
            "type": "string",
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
          },
          "weekDays": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "mon",
                "tue",
                "wed",
                "thu",
                "fri",
                "sat",
                "sun"
              ]
            },
            "uniqueItems": true
          },
          "isActive": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "UnauthorizedError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "const": "unauthorized"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message",
          "code"
        ],
        "additionalProperties": false
      },
      "UnauthorizedErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "unauthorized"
            ]
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "machine code from the shared auth boundary (src/server/auth/boundary.ts, fix #682) — always `credential_invalid` on a 401 from this cross-cutting preHandler; optional here since older/other 401 emitters may not set it."
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "UpdateMemberRequest": {
        "type": "object",
        "properties": {
          "displayName": {
            "type": "string",
            "minLength": 1
          },
          "colorKey": {
            "description": "A curated key; duplicates are allowed. Omission preserves the existing key, as do archive and restore.",
            "$ref": "#/components/schemas/MemberColorKey"
          },
          "role": {
            "type": "string",
            "enum": [
              "parent",
              "child"
            ]
          },
          "birthDate": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/BirthDate"
              },
              {
                "type": "null"
              }
            ],
            "description": "null explicitly clears the birth date (FR-009a). Omitted fields are unchanged."
          },
          "celebration": {
            "description": "Replaces the celebration as a whole. Omission keeps the current one.",
            "$ref": "#/components/schemas/MemberCelebration"
          }
        },
        "additionalProperties": false,
        "minProperties": 1,
        "description": "Partial profile update. Must include at least one field; role=admin rejected."
      },
      "UploadResult": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string"
          }
        },
        "required": [
          "filename"
        ],
        "additionalProperties": false
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "validation_error"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "ValidationErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "validation_error"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": false
      },
      "VerifyPinRequest": {
        "type": "object",
        "properties": {
          "pin": {
            "type": "string"
          }
        },
        "required": [
          "pin"
        ]
      },
      "VerifyPinResult": {
        "type": "object",
        "properties": {
          "match": {
            "type": "boolean"
          }
        },
        "required": [
          "match"
        ],
        "description": "Advisory only — no session is created; grants no backend authority (FR-016/026)."
      },
      "WeatherBlockPayload": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD, household tz"
          },
          "conditionKey": {
            "$ref": "#/components/schemas/WeatherConditionKey"
          },
          "tempMinC": {
            "type": "number"
          },
          "tempMaxC": {
            "type": "number"
          },
          "rainPct": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          }
        },
        "required": [
          "date",
          "conditionKey",
          "tempMinC",
          "tempMaxC",
          "rainPct"
        ],
        "additionalProperties": false,
        "description": "The `data` shape of a `BlockInstance` whose `type` is `weather` (, the Weather domain contract). Present only when the household's forecast `daily[]` covers the briefing's household-local `date` (WEATHER-INV-05); frozen once written (WEATHER-INV-09) — regeneration is the only refresh. `BlockInstance.data` stays the generic `[object, array, 'null']` schema above (untyped per-type, matching every other block type's precedent) — this schema documents what a `weather`-typed block's `data` actually contains (the route-only drift gate cannot see this body-shape change, hence the explicit ripple-edit).\n"
      },
      "WeatherConditionKey": {
        "type": "string",
        "enum": [
          "clear",
          "mostlyClear",
          "partlyCloudy",
          "overcast",
          "fog",
          "drizzle",
          "freezingDrizzle",
          "rain",
          "freezingRain",
          "snow",
          "snowGrains",
          "rainShowers",
          "snowShowers",
          "thunderstorm",
          "thunderstormHail",
          "unknown"
        ]
      },
      "WeatherLocation": {
        "type": "object",
        "properties": {
          "lat": {
            "anyOf": [
              {
                "type": "number",
                "minimum": -90,
                "maximum": 90
              },
              {
                "type": "null"
              }
            ]
          },
          "lon": {
            "anyOf": [
              {
                "type": "number",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "null"
              }
            ]
          },
          "label": {
            "type": "string",
            "maxLength": 80,
            "description": "Optional free text; absent ⇒ no place label rendered; never reverse-geocoded (WEATHER-INV-08)."
          }
        },
        "additionalProperties": false,
        "description": "Both-or-neither non-null (partial pair rejected on write, WEATHER-INV-02); clearing writes both null as one unit."
      },
      "WeatherResponse": {
        "type": "object",
        "properties": {
          "forecast": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "properties": {
                  "current": {
                    "$ref": "#/components/schemas/ForecastCurrent"
                  },
                  "hourly": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ForecastHour"
                    }
                  },
                  "daily": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ForecastDay"
                    }
                  }
                },
                "required": [
                  "current",
                  "hourly",
                  "daily"
                ],
                "additionalProperties": false
              }
            ],
            "description": "null = silent absence: blank location, operator-disabled, or failed/timed-out fetch (WEATHER-INV-12). Never expressed as an HTTP error."
          }
        },
        "required": [
          "forecast"
        ],
        "additionalProperties": false
      },
      "WeekMenu": {
        "type": "object",
        "additionalProperties": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MenuItem"
            }
          }
        },
        "description": "Week grid: a map of the 7 local YYYY-MM-DD dates of the week (from `weekStartDay` + tz) to that date's derived menu grouped by slot (breakfast/lunch/snack/dinner -> MenuItem[]; an empty slot is `[]`).\n"
      },
      "Weekday": {
        "type": "string",
        "enum": [
          "mon",
          "tue",
          "wed",
          "thu",
          "fri",
          "sat",
          "sun"
        ],
        "description": "canonical mon..sun (ADR-020); ISO 1..7 rejected."
      },
      "WriteSettingsRequest": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "locale",
              "celebration",
              "weather",
              "printer",
              "printerTransport"
            ],
            "description": "Registered object name. Core locale and celebration are always available; inactive plugin-owned objects are not projected by GET /api/settings.\n"
          },
          "settings": {
            "type": "object",
            "description": "Complete replacement object. The Settings domain rejects unknown or invalid fields and writes a valid object atomically. For `printerTransport`, either all four fields are empty or `deviceId` and `name` are non-empty and `serviceUuid`/`characteristicUuid` are well-formed 128-bit UUIDs (8-4-4-4-12 hex, any version nibble), stored lower-case.\n"
          }
        },
        "required": [
          "object",
          "settings"
        ],
        "additionalProperties": false
      }
    }
  },
  "paths": {
    "/api/auth/credentials": {
      "get": {
        "operationId": "listDeviceCredentials",
        "summary": "List every API credential (never its key or hash), oldest first",
        "tags": [
          "bootstrap"
        ],
        "description": "Requires a provisioned `*` device cookie (`requireFullAccess`). The Admin PIN is a UI-only gate and is never evaluated here.\n",
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Every credential with its derived state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceCredentialList"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/credentials/{id}": {
      "patch": {
        "operationId": "labelDeviceCredential",
        "summary": "Name a credential so a device can be identified later",
        "tags": [
          "bootstrap"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceCredentialLabelRequest"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The relabelled credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceCredential"
                }
              }
            }
          },
          "400": {
            "description": "The body is not `{label}` or the label is empty or too long",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceCredentialError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "404": {
            "description": "No credential with this id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceCredentialError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/credentials/{id}/revoke": {
      "post": {
        "operationId": "revokeDeviceCredential",
        "summary": "Idempotently retire a credential; its next request is refused",
        "tags": [
          "bootstrap"
        ],
        "description": "Revoking the credential this request uses succeeds; the device is logged out on its next request. The bootstrap key configured in MP_BOOTSTRAP_KEY is refused with 409: change the variable and restart, then revoke the old row.\n",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The credential after revocation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceCredentialRevokeResult"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "404": {
            "description": "No credential with this id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceCredentialError"
                }
              }
            }
          },
          "409": {
            "description": "The credential is the configured MP_BOOTSTRAP_KEY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceCredentialError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/provision": {
      "post": {
        "operationId": "provisionDevice",
        "summary": "First connect — present the raw `*` bootstrap key, mint a cookie-bound device key.",
        "tags": [
          "bootstrap"
        ],
        "description": "Validates the presented raw `*` key against the configured bootstrap credential. On success mints a no-expiry `*` device key, persists only its hash with a label (the optional body's, else one derived from the User-Agent), and returns it via Set-Cookie. Fail-closed: an absent/invalid key yields 401 and the deployment stays locked (FR-003/004/007).\n",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProvisionRequest"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "example": "Bearer mpk-cedar-lantern-otter-ridge-velvet-amber-quilt-harbor"
            },
            "in": "header",
            "name": "Authorization",
            "required": true,
            "description": "The raw `*` bootstrap key. Never logged; never returned."
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Provisioned. Device key delivered via Set-Cookie; body has no raw key.",
            "headers": {
              "Set-Cookie": {
                "schema": {
                  "type": "string",
                  "example": "mp_device_key=mpk-…; HttpOnly; Secure; SameSite=Lax"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvisionResult"
                }
              }
            }
          },
          "400": {
            "description": "`invalid_label`: the body is not empty, `{}` or `{label}`, or the label is not a string of 1 to 80 trimmed characters. Nothing is minted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid bootstrap key — locked, never open.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/verify-pin": {
      "post": {
        "operationId": "verifyPin",
        "summary": "Advisory client-side-gate helper — compares the PIN, returns match/no-match.",
        "tags": [
          "bootstrap"
        ],
        "description": "Authorized by the device key like every endpoint. Compares the submitted PIN to the stored hash and returns `{ match }`. Creates NO session row and grants NO authority; the PIN is never an authorization input (FR-014/015/016/026).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyPinRequest"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Correct PIN → match true; incorrect PIN → match false. No state written.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyPinResult"
                }
              }
            }
          },
          "401": {
            "description": "No/invalid device key (independent of PIN).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/backups": {
      "get": {
        "operationId": "listBackups",
        "summary": "List the backup shelf (file-derived; backups:admin)",
        "tags": [
          "backups"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Newest-first shelf listing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable. Ordinary API traffic is also unavailable during quiescent restore.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/PluginUnavailable"
                    },
                    {
                      "$ref": "#/components/schemas/Quiescing"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/backups/restore": {
      "post": {
        "operationId": "restoreBackup",
        "summary": "Restore a backup (typed-filename confirmation; ADR-017 sequence)",
        "tags": [
          "backups"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestoreRequest"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Restored; clients should reload (dbGeneration bumped).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestoreResult"
                }
              }
            }
          },
          "400": {
            "description": "Validation error or typed-confirmation mismatch — no side effects.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestoreResult"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "404": {
            "description": "The named backup vanished between list and action (or failed the F9 hardened resolve).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestoreResult"
                }
              }
            }
          },
          "409": {
            "description": "A restore or snapshot is already in progress.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestoreResult"
                }
              }
            }
          },
          "422": {
            "description": "Incompatible backup, unsupported lineage, or downgrade rejected (fail-closed version gate).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestoreResult"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "Pre-restore snapshot failed (aborted untouched); a swap failure (WAL/SHM cleanup or copy/rename, rolled back losslessly); or a forward migration failure (rolled back losslessly).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestoreResult"
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/RestoreResult"
                    },
                    {
                      "$ref": "#/components/schemas/PluginUnavailable"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/backups/snapshot": {
      "post": {
        "operationId": "createSnapshot",
        "summary": "Create a snapshot now (routes through the scheduler's manual entry)",
        "tags": [
          "backups"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Completed (with filename) or an honest already_running.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SnapshotResult"
                }
              }
            }
          },
          "409": {
            "description": "A restore is currently in progress; snapshots are refused until it completes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "The snapshot write itself failed (e.g. ENOSPC) — error \"backup_failed\". `backup_failed` IS a member of the closed RestoreResult error-code enum above (F7, review #636/#637) — included there only for that union's exhaustiveness, since `restoreDatabase` itself never returns it, same precedent as `upload_too_large`. The failure is also surfaced via GET /api/backups's lastBackupError field and server logs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/BackupsError"
                    },
                    {
                      "$ref": "#/components/schemas/PluginUnavailable"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/backups/upload": {
      "post": {
        "operationId": "uploadBackup",
        "summary": "Upload a.db backup (size-capped before writing;.sql rejected)",
        "tags": [
          "backups"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Stored on the shelf with an upload- prefix.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadResult"
                }
              }
            }
          },
          "400": {
            "description": "Not a SQLite file / empty body (.sql is rejected via this same check).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "413": {
            "description": "Over the size cap; zero bytes written.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported Content-Type — this route only accepts application/octet-stream (F4, independent review of #639/#640).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "An unexpected failure inside the upload route (e.g. a disk write or rename failure). A stable, English, internals-free upload_failed envelope — never the raw thrown message (F4, independent review of #639/#640).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginUnavailable"
                }
              }
            }
          }
        }
      }
    },
    "/api/backups/{filename}": {
      "delete": {
        "operationId": "deleteBackup",
        "summary": "Delete a backup (respects the retention floor; protected pre-restore refused)",
        "tags": [
          "backups"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "filename",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "400": {
            "description": "Invalid filename (allowlist/traversal).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "404": {
            "description": "The named backup vanished between list and action.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "409": {
            "description": "Floor violation (retention_floor) or a pre-restore snapshot targeted while a restore is in progress (protected_pre_restore).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginUnavailable"
                }
              }
            }
          }
        }
      }
    },
    "/api/backups/{filename}/download": {
      "get": {
        "operationId": "downloadBackup",
        "summary": "Download a backup file (sensitive; backups:admin)",
        "tags": [
          "backups"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "filename",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The backup file.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid filename.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "404": {
            "description": "The named backup vanished between list and action.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginUnavailable"
                }
              }
            }
          }
        }
      }
    },
    "/api/backups/{filename}/download-sql": {
      "get": {
        "operationId": "downloadBackupSql",
        "summary": "Read-only in-process SQL export (never re-importable)",
        "tags": [
          "backups"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "filename",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "SQL text export.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid filename, or the file could not be read as SQLite.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "404": {
            "description": "The named backup vanished between list and action.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupsError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "Opening or re-validating the SQL dump source failed before streaming.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DumpInternalError"
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginUnavailable"
                }
              }
            }
          }
        }
      }
    },
    "/api/calendar/events": {
      "get": {
        "operationId": "getCalendarEvents",
        "summary": "Read the merged feed (getEvents) — the sole cross-module read path (INV-01/AC-01).",
        "tags": [
          "calendar"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "local",
                "external"
              ],
              "default": "all"
            },
            "in": "query",
            "name": "source",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "assignedTo",
            "required": false,
            "description": "member id; strict (INV-09/AC-06)"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "from",
            "required": true,
            "description": "Range start: a YYYY-MM-DD household date (from its household midnight) or an ISO instant (inclusive). All-day events match by household date."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "to",
            "required": true,
            "description": "Range end: a YYYY-MM-DD household date, included (read up to the next household midnight, INV-03), or an exclusive ISO instant."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "query",
            "required": false,
            "description": "Optional case/diacritic-insensitive substring match performed inside Calendar (default fields title+description; override with queryFields)."
          },
          {
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "title",
                  "description",
                  "location"
                ]
              }
            },
            "in": "query",
            "name": "queryFields",
            "required": false,
            "description": "Optional non-empty subset of title|description|location. Invalid entries → 400."
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Expanded, merged, member-scoped occurrences within the range.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/FeedItem"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing/malformed range, range outside the fixed −30d/+365d window, invalid source, or invalid queryFields entries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postCalendarEvents",
        "summary": "Create a local event (device-key auth; PIN is a client-only affordance gate).",
        "tags": [
          "calendar"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventInput"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "201": {
            "description": "created; returns the new master event id",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "new master event id"
                    }
                  },
                  "required": [
                    "id"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "validation (start==end, bad tzid, malformed rrule, …)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/calendar/events/{id}": {
      "patch": {
        "operationId": "patchCalendarEventsById",
        "summary": "Edit a local event's fields (single-row; rrule edit preserves exdates, FR-014).",
        "tags": [
          "calendar"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventEditInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedItem"
                }
              }
            }
          },
          "400": {
            "description": "validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such event"
          },
          "409": {
            "description": "`external_event_read_only`: the event is synchronized from an external calendar; only its participant assignments are editable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteCalendarEventsById",
        "summary": "Delete a local event + its assignments atomically (FR-009, INV-07 local).",
        "tags": [
          "calendar"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "deleted; event + all assignment rows removed in one transaction"
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such event"
          },
          "409": {
            "description": "`external_event_read_only`: the event is synchronized from an external calendar; only its participant assignments are editable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/calendar/events/{id}/assignments": {
      "put": {
        "operationId": "putCalendarEventsByIdAssignments",
        "summary": "Replace an event's assignment set atomically (FR-009; strict active-member, FR-006).",
        "tags": [
          "calendar"
        ],
        "description": "The response holds exactly the requested members. On an external event, a title-derived (`ext:`) assignment whose member is still requested is kept as title-derived, so later feed syncs keep owning it; every other requested member is stored as a manual assignment that survives syncs. A title-derived member left out of the set is removed until the next sync reads the title again.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssignmentReplace"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "replaced (atomic)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedItem"
                }
              }
            }
          },
          "400": {
            "description": "a target member is not active (strict-on-write)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such event"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/calendar/external-sources": {
      "get": {
        "operationId": "getCalendarExternalSources",
        "summary": "List safe source configuration, durable health, and transient phase.",
        "tags": [
          "calendar"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Raw feed URLs and conditional validators are absent.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ExternalSourcePublic"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid device key."
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/calendar/external-sources/{id}": {
      "put": {
        "operationId": "putCalendarExternalSourcesById",
        "summary": "Persist source configuration and start first synchronization after commit.",
        "tags": [
          "calendar"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalSourcePut"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "202": {
            "description": "Configuration persisted and first synchronization started.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalSourcePublic"
                }
              }
            }
          },
          "400": {
            "description": "Invalid source or unsafe URL."
          },
          "401": {
            "description": "Missing or invalid device key."
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "patchCalendarExternalSourcesById",
        "summary": "Reversibly enable or disable a source without deleting retained data.",
        "tags": [
          "calendar"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalSourcePatch"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Updated source state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalSourcePublic"
                }
              }
            }
          },
          "400": {
            "description": "Invalid body."
          },
          "401": {
            "description": "Missing or invalid device key."
          },
          "404": {
            "description": "Source not found."
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteCalendarExternalSourcesById",
        "summary": "Permanently delete source, imported events, and external assignments under the guard.",
        "tags": [
          "calendar"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "Deletion completed atomically."
          },
          "401": {
            "description": "Missing or invalid device key."
          },
          "404": {
            "description": "Source not found."
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/calendar/external-sources/{id}/sync": {
      "post": {
        "operationId": "postCalendarExternalSourcesByIdSync",
        "summary": "Start or observe the source's current synchronization.",
        "tags": [
          "calendar"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "202": {
            "description": "Synchronization started or an existing run is active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalSourcePublic"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid device key."
          },
          "404": {
            "description": "Source not found."
          },
          "409": {
            "description": "Source is disabled."
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/calendar/highlight-rules": {
      "get": {
        "operationId": "getCalendarHighlightRules",
        "summary": "List highlight rules in persisted priority order.",
        "tags": [
          "calendar"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Ordered rules.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/HighlightRule"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid device key."
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postCalendarHighlightRules",
        "summary": "Create an enabled highlight rule at the end of the order.",
        "tags": [
          "calendar"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HighlightRuleCreate"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "201": {
            "description": "Created rule.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HighlightRule"
                }
              }
            }
          },
          "400": {
            "description": "Invalid emoji or keywords."
          },
          "401": {
            "description": "Missing or invalid device key."
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/calendar/highlight-rules/reorder": {
      "put": {
        "operationId": "putCalendarHighlightRulesReorder",
        "summary": "Atomically replace the complete highlight order.",
        "tags": [
          "calendar"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HighlightRuleOrder"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Complete authoritative order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/HighlightRule"
                  }
                }
              }
            }
          },
          "400": {
            "description": "IDs do not exactly match the stored rule set."
          },
          "401": {
            "description": "Missing or invalid device key."
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/calendar/highlight-rules/{id}": {
      "patch": {
        "operationId": "patchCalendarHighlightRulesById",
        "summary": "Enable or disable one rule.",
        "tags": [
          "calendar"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HighlightRulePatch"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Updated rule.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HighlightRule"
                }
              }
            }
          },
          "400": {
            "description": "Invalid body."
          },
          "401": {
            "description": "Missing or invalid device key."
          },
          "404": {
            "description": "Rule not found."
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteCalendarHighlightRulesById",
        "summary": "Delete one highlight rule and compact the remaining order atomically.",
        "tags": [
          "calendar"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "Rule deleted."
          },
          "401": {
            "description": "Missing or invalid device key."
          },
          "404": {
            "description": "Rule not found."
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/chores/board": {
      "get": {
        "operationId": "getChoresBoard",
        "summary": "The household board (FR-017/FR-018) — one column per active child, all four day periods always present (DAY-PERIODS-AC-05), streak/progress today-only (FR-014). No PIN required (FR-019).\n",
        "tags": [
          "chores"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "in": "query",
            "name": "date",
            "required": true,
            "description": "household-local date; strict-valid (INV-03/AC-05)."
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BoardColumn"
                  }
                }
              }
            }
          },
          "400": {
            "description": "malformed or impossible date",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/chores/{id}": {
      "get": {
        "operationId": "getChoresById",
        "summary": "Fetch one chore by id — tolerant of soft-deleted rows (FR-007/INV-08: a soft-deleted chore stays readable for history). The single-fetch companion to the active-only list in GET /api/routines/{id}/chores.\n",
        "tags": [
          "chores"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK — active or soft-deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Chore"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such chore ever existed"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "patchChoresById",
        "summary": "Edit a chore's name and/or move it to a different routine (FR-019), and/or active.",
        "tags": [
          "chores"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChoreEditInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Chore"
                }
              }
            }
          },
          "400": {
            "description": "validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such chore"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteChoresById",
        "summary": "Soft-delete a chore (INV-08).",
        "tags": [
          "chores"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "soft-deleted"
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such chore"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/chores/{id}/completions": {
      "post": {
        "operationId": "postChoresByIdCompletions",
        "summary": "Complete a chore for a member/date (FR-008) — idempotent, no PIN required (FR-019).",
        "tags": [
          "chores"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompletionInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "completed (or already was — idempotent); emits routines.completion_changed post-commit (FR-015)."
          },
          "400": {
            "description": "malformed or impossible date, missing/blank memberId, or not currently markable (INV-04) — member/chore/routine/assignment state does not cover this date",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such chore"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "Unexpected storage failure; no completion event is emitted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RouteError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteChoresByIdCompletions",
        "summary": "Uncomplete a chore for a member/date (FR-009) — ALWAYS allowed, idempotent, no PIN.",
        "tags": [
          "chores"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "memberId",
            "required": true
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "in": "query",
            "name": "date",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "uncompleted (or already was — idempotent); emits routines.completion_changed post-commit if a row existed."
          },
          "400": {
            "description": "malformed or impossible date, or missing/blank memberId",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such chore"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-briefing/block-order": {
      "put": {
        "operationId": "putDailyBriefingBlockOrder",
        "summary": "Replace the ordered block-instance list (admin).",
        "tags": [
          "daily-briefing"
        ],
        "description": "Body is the ordered array itself (not wrapped). A type may repeat with distinct params (INV-05/ADR-044). Unknown types are REJECTED 400 at this write boundary (stricter than v1's silent-ignore); applies from the next generation only (FR-022).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/BlockOrderInstance"
                }
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "the validated, persisted block order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "blockOrder": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BlockOrderInstance"
                      }
                    }
                  },
                  "required": [
                    "blockOrder"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "not an array, an unknown block type, a malformed entry, or an unavailable `params.language` (400 `corpus_language_unavailable`, FR-009).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/CorpusLanguageUnavailableErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/FastifyParseErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-briefing/block-settings/{memberId}/{blockType}": {
      "put": {
        "operationId": "putDailyBriefingBlockSettingsByMemberIdByBlockType",
        "summary": "Set one member's per-block settings — enabled/weekdays/params (admin).",
        "tags": [
          "daily-briefing"
        ],
        "description": "Partial update: an omitted field keeps its current persisted value, or the FR-013 default-resolution value (every type enabled EXCEPT `onThisDay`) for a row that does not exist yet. `weekdays: null` means \"all days\"; `params.language` is validated against on-disk corpus availability for `blockType` (FR-008/FR-009).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberBlockSettingsInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "memberId",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "blockType",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "the updated per-member per-block settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemberBlockSettings"
                }
              }
            }
          },
          "400": {
            "description": "an unknown block type, an inactive/nonexistent member, a bad weekday, or an unavailable `params.language` (400 `corpus_language_unavailable`, FR-009).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/CorpusLanguageUnavailableErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/FastifyParseErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-briefing/generate": {
      "post": {
        "operationId": "postDailyBriefingGenerate",
        "summary": "Manually generate a briefing for one opted-in active member/date (admin).",
        "tags": [
          "daily-briefing"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateInput"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "generated briefing, or skipped because the member is paused on that weekday (FR-024).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Briefing"
                    },
                    {
                      "$ref": "#/components/schemas/GenerateSkippedResponse"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "invalid input, invalid date, inactive member, or member not opted-in.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/FastifyParseErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-briefing/generate-all": {
      "post": {
        "operationId": "postDailyBriefingGenerateAll",
        "summary": "Generate briefings for every active opted-in member (admin).",
        "tags": [
          "daily-briefing"
        ],
        "description": "Eligibility is active AND explicitly opted-in; opted-in archived members are skipped. The request date is strictly validated before candidate enumeration. Runs through the background-jobs scheduler's shared in-flight guard ( US2, ADR-014): a same-job run already in flight (scheduled, catch-up, or another manual call) returns `{status:\"already_running\"}` at 200 instead of racing a second generation.\n",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateAllInput"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "generated briefing summary, or an already_running guard response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerateAllResponse"
                }
              }
            }
          },
          "400": {
            "description": "invalid date or unknown request property.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/FastifyParseErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-briefing/history/{memberId}": {
      "get": {
        "operationId": "getDailyBriefingHistoryByMemberId",
        "summary": "List a member's latest briefings, newest first (admin, FR-026).",
        "tags": [
          "daily-briefing"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "memberId",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "household today plus at most 30 history entries; a pure read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BriefingHistoryResponse"
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-briefing/opt-in": {
      "get": {
        "operationId": "getDailyBriefingOptIn",
        "summary": "List persisted Daily Briefing opt-in states (admin).",
        "tags": [
          "daily-briefing"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "explicit per-member opt-in states; absent rows remain opt-out by default.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/OptInState"
                  }
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-briefing/opt-in/{memberId}": {
      "put": {
        "operationId": "putDailyBriefingOptInByMemberId",
        "summary": "Set a member's Daily Briefing opt-in (admin).",
        "tags": [
          "daily-briefing"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OptInInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "memberId",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "updated opt-in state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OptInState"
                }
              }
            }
          },
          "400": {
            "description": "invalid input or inactive member.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/FastifyParseErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-briefing/schedule/{memberId}": {
      "put": {
        "operationId": "putDailyBriefingScheduleByMemberId",
        "summary": "Set a member's weekday pause schedule (admin, FR-023/FR-025).",
        "tags": [
          "daily-briefing"
        ],
        "description": "Never regenerates or invalidates briefings. An empty list pauses every day.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BriefingScheduleInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "memberId",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "the stored schedule, canonical order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BriefingSchedule"
                }
              }
            }
          },
          "400": {
            "description": "bad weekday, missing weekdays, unknown field, or inactive member.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/FastifyParseErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-briefing/settings": {
      "get": {
        "operationId": "getDailyBriefingSettings",
        "summary": "Read block order + schedule + trigger binding + per-member block settings (admin).",
        "tags": [
          "daily-briefing"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "the current settings snapshot (documented defaults when no row exists yet).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DailyBriefingSettingsView"
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "putDailyBriefingSettings",
        "summary": "Update generation_time and/or the auto-print trigger binding (admin).",
        "tags": [
          "daily-briefing"
        ],
        "description": "Partial update: an omitted field keeps its current value. `autoPrintTrigger: null` explicitly clears the binding (the contract's trigger-binding model — there is deliberately no boolean `autoPrint` flag). Never regenerates or invalidates existing briefings (FR-022).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DailyBriefingSettingsInput"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "the updated settings snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DailyBriefingSettingsSnapshot"
                }
              }
            }
          },
          "400": {
            "description": "invalid HH:MM, unknown trigger kind, or an unsupported field.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/FastifyParseErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-briefing/{memberId}/{date}": {
      "get": {
        "operationId": "getDailyBriefingByMemberIdByDate",
        "summary": "Read a briefing (family/kiosk) — 019  adds `printedStatus`.",
        "tags": [
          "daily-briefing"
        ],
        "description": "Pure read (FR-010) — never creates a row. `printedStatus` is DERIVED, never Printing's own canonical state: `completed`/`failed` when Printing is active and either the local event-cache (fresh) or a read-time fallback query against Printing (FR-005/AC-04 dropped-event recovery) resolves one; `none` when Printing is active but no printable output has ever completed or dead-lettered for this member/date; `unavailable` when the Printing plugin itself is inactive (FR-007/AC-11 — distinct from `none`). Regeneration (a second call to `POST /api/daily-briefing/generate` for the same member/date) preserves the briefing id, atomically supersedes the prior Printing record for this output (FR-002/FR-003/FR-004, one transaction — research D4  fold), and enqueues no print job itself. `Briefing`/`BriefingPayload`/`BlockInstance` (the envelope v2 21-block registry) are documented locally and synchronized with the daily-briefing contract.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "memberId",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "date",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "the read result; `printedStatus` is present only when `generated: true` (a missing briefing carries no printed-status at all).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BriefingReadResultV2"
                }
              }
            }
          },
          "400": {
            "description": "Invalid strict calendar date.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-briefing/{memberId}/{date}/preview.png": {
      "get": {
        "operationId": "getDailyBriefingByMemberIdByDatePreviewPng",
        "summary": "Stored render PNG (admin preview).",
        "tags": [
          "daily-briefing"
        ],
        "description": "Serves the SAME `png` column pressedslip wrote at generation time (schema.ts: \"admin/preview surface only\") — never re-decodes the packed 1-bit raster, never re-renders. A pure read: a missing row is not generated on demand (FR-010).",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "memberId",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "date",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "the stored render, as a PNG.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "byte"
                }
              }
            }
          },
          "202": {
            "description": "a generation for this member/date is in flight and no PNG is stored yet (FR-028).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BriefingPreviewRendering"
                }
              }
            }
          },
          "400": {
            "description": "an invalid date.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "no briefing exists for this member/date.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "the briefing exists but never got a printable raster (Printing inactive at generation, or a catastrophic render — D5).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintableRasterMissingErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-briefing/{memberId}/{date}/print": {
      "post": {
        "operationId": "postDailyBriefingByMemberIdByDatePrint",
        "summary": "Send a stored briefing to the printer queue (admin, FR-027).",
        "tags": [
          "daily-briefing"
        ],
        "description": "Enqueues through Printing's producer seam under the record key `daily-briefing:<memberId>:manual:<date>`, targeting the household today. A job still waiting is reused; an already printed record is superseded and enqueued again.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "memberId",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "date",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "queued (or the waiting job reused).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BriefingPrintResponse"
                }
              }
            }
          },
          "400": {
            "description": "invalid date or inactive member.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "missing or invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "revoked or expired device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "no briefing for this member/date.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Printing plugin inactive, or the briefing has no printable raster.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/PrintingPluginInactiveErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/PrintableRasterMissingErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-messages": {
      "put": {
        "operationId": "putDailyMessages",
        "summary": "Create or replace the message for (memberId, date) — upsert on the UNIQUE (member_id, date) pair (INV-01/AC-01). A non-object/array body or an unsupported field rejects with 400 (#397); Text, date and active-member validation are enforced on writes.\n",
        "tags": [
          "daily-messages"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DailyMessageUpsert"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "upserted (created or replaced)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DailyMessage"
                }
              }
            }
          },
          "400": {
            "description": "non-object/array body, or an unsupported field (#397)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "getDailyMessages",
        "summary": "Window list — date-ascending messages for a member over the half-open window `[from, from+days)`, missing dates absent (INV-08). `days` outside `[1, 60]` -> 400 (AC-05). Tolerant read: gates on member existence not active-status, so an archived member's historical rows stay readable (P2-B); an unknown member -> 404, a valid member with no messages -> 200 empty list (AC-04).\n",
        "tags": [
          "daily-messages"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "memberId",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "from",
            "required": true,
            "description": "YYYY-MM-DD (window start, inclusive)"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 60
            },
            "in": "query",
            "name": "days",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "date-ascending messages in the window (possibly empty)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DailyMessage"
                  }
                }
              }
            }
          },
          "400": {
            "description": "days out of range, or an invalid from date",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "unknown member",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteDailyMessages",
        "summary": "Delete the message for (memberId, date) — a SEPARATE idempotent command, never implied by a blank write (AC-03/FR-006). A missing message OR an unknown member is a no-op success (204), never a 404.\n",
        "tags": [
          "daily-messages"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "memberId",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "date",
            "required": true,
            "description": "YYYY-MM-DD"
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "deleted, or already absent (idempotent no-op)"
          },
          "400": {
            "description": "missing/malformed query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-messages/current": {
      "get": {
        "operationId": "getDailyMessagesCurrent",
        "summary": "Outbound single read — the current message for (memberId, date), computed LIVE every call (no stored snapshot). Consumed by Daily Briefing. Tolerant read: gates on member existence not active-status (INV-08/AC-04, P2-B) — an unknown member -> 404, an archived member's historical row stays readable.\n",
        "tags": [
          "daily-messages"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "memberId",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "date",
            "required": true,
            "description": "YYYY-MM-DD"
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "the current message, or null when the member has none that date",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/DailyMessage"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "malformed date (DAILY-MESSAGES-INV-03)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "unknown member",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginUnavailable"
                }
              }
            }
          }
        }
      }
    },
    "/api/day-periods": {
      "get": {
        "operationId": "listDayPeriods",
        "summary": "List the four day periods (ordered by start). Public vocabulary — no PIN required.",
        "tags": [
          "day-periods"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Exactly four periods in ascending start order. Exposes no add/delete/reorder.",
            "content": {
              "application/json": {
                "schema": {
                  "minItems": 4,
                  "maxItems": 4,
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DayPeriod"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/day-periods/active": {
      "get": {
        "operationId": "getActiveDayPeriod",
        "summary": "The active period now, in the household timezone (server-authoritative, Option C).",
        "tags": [
          "day-periods"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The latest period whose start <= now; before the first start, the wrapping night.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActivePeriodResult"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/day-periods/{id}": {
      "patch": {
        "operationId": "editDayPeriodStart",
        "summary": "Edit one period's start boundary (validated strict order + uniqueness).",
        "tags": [
          "day-periods"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditStartRequest"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/PeriodId"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The updated period. Neighbours' derived ends follow (re-read via GET).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DayPeriod"
                }
              }
            }
          },
          "400": {
            "description": "Strict-order or uniqueness violation — nothing persisted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown period id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "Unexpected storage failure — nothing persisted. Opaque `internal_error` envelope; details go to the server log only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/meal-entries": {
      "post": {
        "operationId": "createMealEntry",
        "summary": "Add an entry, recurring (mealPlanId+weekday) or one-off (date).",
        "tags": [
          "meals"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MealEntryInput"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "201": {
            "description": "The created entry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MealEntry"
                }
              }
            }
          },
          "400": {
            "description": "Invalid kind/date/slot/weekday, both or neither of recipeId/note, date supplied on a recurring entry (or mealPlanId/weekday supplied on a oneoff entry), a recurring entry missing mealPlanId/weekday, or an unrecognized body property.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "recipeId does not reference an existing recipe (FR-028), or mealPlanId does not reference an existing meal_plan (recurring entries).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/meal-entries/{id}": {
      "patch": {
        "operationId": "editMealEntry",
        "summary": "Content-only edit (Clarifications): recipeId xor note; date/weekday/slot/unknown keys are rejected. To move an entry, DELETE it and POST a new one.\n",
        "tags": [
          "meals"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MealEntryEditInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The edited entry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MealEntry"
                }
              }
            }
          },
          "400": {
            "description": "Both or neither of recipeId/note, a non-content key (date/weekday/slot), or an unrecognized body property.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No entry with that id (never or no longer exists), or recipeId does not reference an existing recipe (FR-028).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteMealEntry",
        "summary": "Delete a meal entry. Idempotent-by-404 (FR-021 LWW, no etag/version): a second delete against an already-deleted id returns 404, never a no-op 204.\n",
        "tags": [
          "meals"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "The entry was removed."
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No entry with that id (never or no longer exists).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/meal-plans": {
      "post": {
        "operationId": "createMealPlan",
        "summary": "Create a meal_plan (name required; always created active).",
        "tags": [
          "meals"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MealPlanInput"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "201": {
            "description": "The created meal_plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MealPlan"
                }
              }
            }
          },
          "400": {
            "description": "Blank/missing name, or an unrecognized body property.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listMealPlans",
        "summary": "List all meal_plans (active and inactive).",
        "tags": [
          "meals"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The meal_plans, possibly empty.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MealPlan"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/meal-plans/{id}": {
      "get": {
        "operationId": "getMealPlan",
        "summary": "Fetch one meal_plan by id.",
        "tags": [
          "meals"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The meal_plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MealPlan"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No meal_plan with that id (never or no longer exists).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "editMealPlan",
        "summary": "Rename and/or activate/deactivate, allow-list name/active (research D5 / #397 lesson — handler-enforced). Deactivate-only: there is NO delete route for meal_plans (Clarifications). Deactivating drops the plan's recurring entries from every derived menu WITHOUT deleting the rows (AC-05); reactivating restores them.\n",
        "tags": [
          "meals"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MealPlanEditInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The edited meal_plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MealPlan"
                }
              }
            }
          },
          "400": {
            "description": "Blank name, empty patch body, or an unrecognized body property.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No meal_plan with that id (never or no longer exists).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/meal-plans/{id}/entries": {
      "get": {
        "operationId": "listPlanEntries",
        "summary": "List a plan's recurring entries for management — INCLUDING those of an INACTIVE (deactivated) plan (derived menu reads exclude inactive plans; this is the plan-management read so a deactivated plan's entries can be edited/deleted without reactivating).\n",
        "tags": [
          "meals"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The plan's recurring entries (retained even while the plan is inactive).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MealEntry"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No meal_plan with that id (never or no longer exists).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/members": {
      "post": {
        "operationId": "createMember",
        "summary": "Create a Member (optionally with a birth date and colour key).",
        "tags": [
          "members"
        ],
        "description": "One member profile in a single transaction, no Daily Briefing side effects. role=admin rejected.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMemberRequest"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "201": {
            "description": "Created (lifecycle active).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Member"
                }
              }
            }
          },
          "400": {
            "description": "Validation error — role=admin, unknown role, blank name, invalid birth date, colour key or celebration (unknown preset, custom without emojis, emojis on a non-custom preset, more than 6, duplicates, non-emoji strings).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "No/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listMembers",
        "summary": "List all members (active and archived).",
        "tags": [
          "members"
        ],
        "description": "Default (no lifecycle param or lifecycle=active) returns ACTIVE members only. lifecycle=archived → archived only; lifecycle=all → all members. Any other value returns 400 (invalid filter).\n",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "archived",
                "all"
              ],
              "default": "active"
            },
            "in": "query",
            "name": "lifecycle",
            "required": false,
            "description": "Filter by lifecycle (active/archived/all)."
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The member list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Member"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid lifecycle filter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "No/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/members/{id}": {
      "patch": {
        "operationId": "updateMember",
        "summary": "Edit a member profile (displayName, role, colorKey, birthDate incl. clear, celebration).",
        "tags": [
          "members"
        ],
        "description": "Partial update. Send `birthDate:null` to clear the birth date (FR-009a). No downstream side effects. Returns 404 if member not found; 400 for validation errors (invalid date, role=admin, no fields to update).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateMemberRequest"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Updated member.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Member"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (invalid date, role=admin, invalid celebration, no fields).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "No/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No member with that id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/members/{id}/archive": {
      "post": {
        "operationId": "archiveMember",
        "summary": "Archive a member (active → archived). Idempotent.",
        "tags": [
          "members"
        ],
        "description": "Single-row atomic transition; never a hard delete (MEMBERS-INV-04). Re-archiving an already archived member is a no-op success (returns current state without updating updated_at).\n",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Member archived (or already archived — no-op).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Member"
                }
              }
            }
          },
          "401": {
            "description": "No/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No member with that id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/members/{id}/restore": {
      "post": {
        "operationId": "restoreMember",
        "summary": "Restore an archived member (archived → active). Idempotent.",
        "tags": [
          "members"
        ],
        "description": "Reverses archive (FR-004). Re-restoring an already active member is a no-op success (returns current state without updating updated_at). An archived member holds no colour key: if another active member took theirs meanwhile, the restored member's `colorKey` becomes the first unused one.\n",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Member restored (or already active — no-op).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Member"
                }
              }
            }
          },
          "401": {
            "description": "No/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No member with that id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/menu": {
      "get": {
        "operationId": "getMenu",
        "summary": "Derived day menu for ?date=YYYY-MM-DD[&slot=] — the union of recurring entries of every ACTIVE meal_plan whose weekday matches weekdayOf(date, householdTz) and one-off entries for that date, in the full D2 total order; no materialized rows (INV-03); empty list = absence (FR-012); a stale recipe reference renders as a tombstone item (isTombstone:true, INV-09).\n",
        "tags": [
          "meals"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "date",
            "required": true,
            "description": "YYYY-MM-DD"
          },
          {
            "schema": {
              "$ref": "#/components/schemas/Slot"
            },
            "in": "query",
            "name": "slot",
            "required": false
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The derived menu (MenuItem[]), possibly empty.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MenuItem"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid date/slot.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/menu/week": {
      "get": {
        "operationId": "getWeekMenu",
        "summary": "Derived week grid for ?date=YYYY-MM-DD — the 7 local dates of the week containing `date`, starting at the weekStartDay app-setting (0=Sunday/1=Monday, ADR-028), each mapped to its derived day menu grouped by slot (date -> slot -> MenuItem[]); a pure view, no stored week window (FR-019).\n",
        "tags": [
          "meals"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "date",
            "required": true,
            "description": "YYYY-MM-DD"
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The week grid (WeekMenu).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WeekMenu"
                }
              }
            }
          },
          "400": {
            "description": "Invalid date.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/network-devices": {
      "get": {
        "operationId": "getNetworkDevices",
        "summary": "List the curated registry with derived live status (ZERO writes — INV-05)",
        "tags": [
          "network-devices"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The curated registry with derived live status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NetworkDevicesListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "revoked, expired or out-of-scope credential rejected (AC-06)"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postNetworkDevices",
        "summary": "Register a device from the fresh picker cache",
        "tags": [
          "network-devices"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterDeviceRequest"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "201": {
            "description": "Device registered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisteredDevice"
                }
              }
            }
          },
          "400": {
            "description": "validation (alias, inactive member)"
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "revoked, expired or out-of-scope credential rejected (AC-06)"
          },
          "409": {
            "description": "MAC not in the current fresh cache (`reselect_required`) or already registered (INV-01)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NetworkDeviceErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/network-devices/live-clients": {
      "get": {
        "operationId": "getNetworkDevicesLiveClients",
        "summary": "Picker feed — the controller's current live clients",
        "tags": [
          "network-devices"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The live-client picker feed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LiveClientsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "revoked, expired or out-of-scope credential rejected (AC-06)"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/network-devices/{id}": {
      "patch": {
        "operationId": "patchNetworkDevicesById",
        "summary": "Edit alias/assignment (local-only; MAC immutable)",
        "tags": [
          "network-devices"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditDeviceRequest"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Device updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisteredDevice"
                }
              }
            }
          },
          "400": {
            "description": "validation (inactive member on NEW assignment)"
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "revoked, expired or out-of-scope credential rejected (AC-06)"
          },
          "404": {
            "description": "unknown device"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteNetworkDevicesById",
        "summary": "Delete (local-only — NO controller call ever, AC-04)",
        "tags": [
          "network-devices"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "always succeeds locally, blocked devices included"
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "revoked, expired or out-of-scope credential rejected (AC-06)"
          },
          "404": {
            "description": "unknown device"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/network-devices/{id}/block": {
      "post": {
        "operationId": "postNetworkDevicesByIdBlock",
        "summary": "Block internet for the device (intent → controller → mirror)",
        "tags": [
          "network-devices"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Controller accepted; body reflects the belief (possibly beliefDiverged when the mirror write failed — AC-02).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisteredDevice"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "revoked, expired or out-of-scope credential rejected (AC-06)"
          },
          "404": {
            "description": "unknown device"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "502": {
            "description": "controller rejected/unreachable — nothing mirrored",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ControllerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/network-devices/{id}/unblock": {
      "post": {
        "operationId": "postNetworkDevicesByIdUnblock",
        "summary": "Restore internet (symmetric to block)",
        "tags": [
          "network-devices"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Device unblocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisteredDevice"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "revoked, expired or out-of-scope credential rejected (AC-06)"
          },
          "404": {
            "description": "unknown device"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "502": {
            "description": "controller rejected/unreachable — nothing mirrored",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ControllerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/openapi.json": {
      "get": {
        "operationId": "getOpenApiDocument",
        "summary": "The OpenAPI 3.1 document for this API.",
        "tags": [
          "docs"
        ],
        "description": "Generated at runtime from the same zod route schemas as the committed `docs/api/openapi.json`; `servers` reflects the deployment's BASE_PATH. The interactive reference UI is served at `/api/docs/`.",
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "OpenAPI document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "openapi": {
                      "type": "string",
                      "enum": [
                        "3.1.0"
                      ]
                    },
                    "info": {
                      "type": "object",
                      "properties": {
                        "title": {
                          "type": "string"
                        },
                        "version": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "title",
                        "version"
                      ]
                    },
                    "paths": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "openapi",
                    "info",
                    "paths"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "No/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/plugins": {
      "get": {
        "operationId": "listPlugins",
        "summary": "List the exact delivered first-party plugin catalog",
        "tags": [
          "plugins"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          },
          {
            "integrationKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Authenticated catalog in manifest order",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plugins": {
                      "minItems": 9,
                      "maxItems": 9,
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PluginCatalogEntry"
                      }
                    }
                  },
                  "required": [
                    "plugins"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "No single valid established credential was presented",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "The authenticated credential does not contain the `*` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "The safe catalog snapshot could not be read",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginCatalogUnavailable"
                }
              }
            }
          }
        }
      }
    },
    "/api/plugins/{pluginId}/activate": {
      "post": {
        "operationId": "activatePlugin",
        "summary": "Idempotently activate one delivered plugin",
        "tags": [
          "plugins"
        ],
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/PluginId"
            },
            "in": "path",
            "name": "pluginId",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          },
          {
            "integrationKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current terminal plugin representation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginCatalogEntry"
                }
              }
            }
          },
          "401": {
            "description": "No single valid established credential was presented",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "The authenticated credential does not contain the `*` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "The path ID is not in the exact delivered cohort",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "An opposite lifecycle target is already durable for this plugin",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "enum": [
                        "plugin_lifecycle_busy"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "A lifecycle operation is already in progress for this plugin."
                      ]
                    },
                    "plugin": {
                      "$ref": "#/components/schemas/PluginCatalogEntry"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "plugin"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "Lifecycle work failed safely or the pre-operation catalog snapshot was unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/PluginLifecycleFailed"
                    },
                    {
                      "$ref": "#/components/schemas/PluginCatalogUnavailable"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/plugins/{pluginId}/deactivate": {
      "post": {
        "operationId": "deactivatePlugin",
        "summary": "Idempotently deactivate one delivered plugin after bounded drain",
        "tags": [
          "plugins"
        ],
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/PluginId"
            },
            "in": "path",
            "name": "pluginId",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          },
          {
            "integrationKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current terminal plugin representation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginCatalogEntry"
                }
              }
            }
          },
          "401": {
            "description": "No single valid established credential was presented",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "The authenticated credential does not contain the `*` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "The path ID is not in the exact delivered cohort",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "An opposite lifecycle target is already durable for this plugin",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "enum": [
                        "plugin_lifecycle_busy"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "A lifecycle operation is already in progress for this plugin."
                      ]
                    },
                    "plugin": {
                      "$ref": "#/components/schemas/PluginCatalogEntry"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "plugin"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "Lifecycle work failed safely or the pre-operation catalog snapshot was unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/PluginLifecycleFailed"
                    },
                    {
                      "$ref": "#/components/schemas/PluginCatalogUnavailable"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/plugins/{pluginId}/fault": {
      "post": {
        "operationId": "reportPluginFault",
        "summary": "Report an allow-listed client contribution fault without raw details",
        "tags": [
          "plugins"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string",
                    "enum": [
                      "contribution_render_failed",
                      "contribution_start_failed"
                    ]
                  }
                },
                "required": [
                  "code"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/PluginId"
            },
            "in": "path",
            "name": "pluginId",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          },
          {
            "integrationKey": []
          }
        ],
        "responses": {
          "204": {
            "description": "Fault contained or already contained"
          },
          "400": {
            "description": "Body contains an unknown field, raw detail, or unsupported code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "No single valid established credential was presented",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "The authenticated credential does not contain the `*` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "The path ID is not in the exact delivered cohort",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "An opposite lifecycle target is already durable for this plugin",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "enum": [
                        "plugin_lifecycle_busy"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "A lifecycle operation is already in progress for this plugin."
                      ]
                    },
                    "plugin": {
                      "$ref": "#/components/schemas/PluginCatalogEntry"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "plugin"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "Lifecycle work failed safely or the pre-operation catalog snapshot was unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/PluginLifecycleFailed"
                    },
                    {
                      "$ref": "#/components/schemas/PluginCatalogUnavailable"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/printing/capability": {
      "post": {
        "operationId": "postPrintingCapability",
        "summary": "register this session as print-capable on pairing (ADR-035, FR-021 — `/claim` requires it)",
        "tags": [
          "printing"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "capability registered for the session's key (idempotent)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CapabilityResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "defensive only, `code: \"credential_invalid\"` — no authenticated API key on the request (should never occur past authBoundary); this route has no OTHER 403 cause (unlike /claim below, it never checks an EXISTING capability, only writes one)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "printing plugin inactive (FR-013)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/printing/claim": {
      "post": {
        "operationId": "postPrintingClaim",
        "summary": "executor claim — atomic, day-scoped (research D1); requires the session's registered printer capability (FR-021, ADR-035)",
        "tags": [
          "printing"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "one job claimed with a fresh lease",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaimResponse"
                }
              }
            }
          },
          "204": {
            "description": "nothing claimable"
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "TWO causes, both `ErrorResponse`: session has no registered printer capability, `code: \"printer_capability_missing\"` (FR-021 — the common case); OR, defensively, no authenticated API key on the request, `code: \"credential_invalid\"` (should never occur past authBoundary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "printing plugin inactive (FR-013)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/printing/jobs": {
      "get": {
        "operationId": "getPrintingJobs",
        "summary": "admin list with derived states (SC-003 visibility)",
        "tags": [
          "printing"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "all jobs with derived states",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobsListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginUnavailable"
                }
              }
            }
          }
        }
      }
    },
    "/api/printing/jobs/{id}/ack": {
      "post": {
        "operationId": "postPrintingJobsByIdAck",
        "summary": "byte-level success acknowledgement (ADR-019, FR-004/FR-008)",
        "tags": [
          "printing"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leaseToken": {
                    "type": "string"
                  }
                },
                "required": [
                  "leaseToken"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "printedAt stamped, `printing.completed` emitted (idempotent per lease)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintJob"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "404": {
            "description": "unknown job id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "stale lease token — no state change (INV-05)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/printing/jobs/{id}/fail": {
      "post": {
        "operationId": "postPrintingJobsByIdFail",
        "summary": "executor-reported transport failure — recoverable → attempts+1 and immediately re-claimable; permanent codes → dead-letter (FR-009)",
        "tags": [
          "printing"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leaseToken": {
                    "type": "string"
                  },
                  "reason": {
                    "type": "string"
                  },
                  "permanentCode": {
                    "anyOf": [
                      {
                        "type": "string",
                        "enum": [
                          "render_failure",
                          "unsupported_transport",
                          "secure_context"
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "present only when the executor knows the failure is permanent (contract vocabulary)"
                  }
                },
                "required": [
                  "leaseToken",
                  "reason"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "failure recorded; lease released or job dead-lettered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintJob"
                }
              }
            }
          },
          "400": {
            "description": "malformed body — missing/invalid `reason` or `permanentCode`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "404": {
            "description": "unknown job id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "stale lease token (INV-05)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/printing/jobs/{id}/payload": {
      "get": {
        "operationId": "getPrintingJobsByIdPayload",
        "summary": "fetch final ESC/POS bytes — raster pulled from the producer's provider and converted at fetch time (FR-017, ADR-066)",
        "tags": [
          "printing"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "leaseToken",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "the job's final printer-ready ESC/POS byte stream",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "404": {
            "description": "unknown job id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "stale/rotated lease token (INV-05 fencing)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "permanent conversion failure (`render_failure`) — job dead-letters, `printing.failed` emitted (FR-017)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/printing/reset-today": {
      "post": {
        "operationId": "postPrintingResetToday",
        "summary": "admin \"reset today's print\" (FR-016) — supersede every print record of household-today so it can print again; cancels pending and claimed-not-yet-fetched jobs. Takes no body.",
        "tags": [
          "printing"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "today's print records were reset (zero counts when nothing existed)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResetTodayPrintsResponse"
                }
              }
            }
          },
          "400": {
            "description": "a request body with any field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "409": {
            "description": "printing plugin inactive (FR-013)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginUnavailable"
                }
              }
            }
          }
        }
      }
    },
    "/api/printing/status": {
      "get": {
        "operationId": "getPrintingStatus",
        "summary": "client-side plugin-state read (FR-013, issue 691) — no capability gate (a plain read, matching /jobs GET's own posture, not a printer-session action)",
        "tags": [
          "printing"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "current plugin-active state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingStatusResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/printing/test-print": {
      "post": {
        "operationId": "postPrintingTestPrint",
        "summary": "admin trigger — enqueue the test printable (FR-018; dedup per FR-012). Body is OPTIONAL; an omitted/absent `targetDate` defaults to the household-local \"today\" (research D10).",
        "tags": [
          "printing"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "targetDate": {
                    "type": "string",
                    "description": "override for the trigger's target date — MUST be strictly calendar-valid YYYY-MM-DD (Constitution IV); the one HTTP-reachable seam for this slice's target_date validity check"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "trigger evaluated — enqueued, or dedup-suppressed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestPrintResponse"
                }
              }
            }
          },
          "400": {
            "description": "malformed body, or `targetDate` is not strictly calendar-valid (Constitution IV)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "409": {
            "description": "printing plugin inactive (FR-013)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintingErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/recipes": {
      "post": {
        "operationId": "createRecipe",
        "summary": "Create a recipe (name required; ingredients/instructions/slots optional).",
        "tags": [
          "meals"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecipeInput"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "201": {
            "description": "The created recipe.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recipe"
                }
              }
            }
          },
          "400": {
            "description": "Blank/missing name, or an unrecognized body property.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listRecipes",
        "summary": "List recipes, or search by name with `?search=` (case- and diacritic-insensitive substring match, JS-side — research D4; e.g. `lentejas` matches \"Lentejas\" and \"Lentéjas\").\n",
        "tags": [
          "meals"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "search",
            "required": false
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The matching recipes (all recipes if `search` is absent/empty), possibly empty.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Recipe"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/recipes/{id}": {
      "get": {
        "operationId": "getRecipe",
        "summary": "Fetch one recipe by id.",
        "tags": [
          "meals"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The recipe.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recipe"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No recipe with that id (never or no longer exists).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "editRecipe",
        "summary": "Partial recipe edit, allow-list name/ingredients/instructions/slots (research D5 / #397 lesson — handler-enforced). Strict update-by-id (FR-005): a patch against a deleted/unknown id returns 404 and never recreates the row.\n",
        "tags": [
          "meals"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecipeEditInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The edited recipe.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recipe"
                }
              }
            }
          },
          "400": {
            "description": "Blank name, empty patch body, or an unrecognized body property.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No recipe with that id (never or no longer exists) — no recreate.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteRecipe",
        "summary": "Informed-cascade delete (FR-003/004, INV-08): removes the recipe and every referencing entry (recurring + one-off) atomically; an emptied meal_plan survives untouched. Strict update-by-id (FR-005): a delete against an already-deleted id returns 404, never a no-op 204.\n",
        "tags": [
          "meals"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "The recipe and its referencing entries were removed."
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No recipe with that id (never or no longer exists).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/recipes/{id}/dependents": {
      "get": {
        "operationId": "getRecipeDependents",
        "summary": "Split dependent counts for a recipe (recurringCount/oneOffCount), advisory pre-delete confirmation (AC-06).\n",
        "tags": [
          "meals"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The split dependent counts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecipeDependentCounts"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No recipe with that id (never or no longer exists).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/reminders": {
      "get": {
        "operationId": "getReminders",
        "summary": "List all reminder rules (+ their assignments). Admin surface.",
        "tags": [
          "reminders"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "all reminders",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Reminder"
                  }
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginUnavailable"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postReminders",
        "summary": "Create a scheduled reminder (apply_to_all, or specific + assignments), atomically.",
        "tags": [
          "reminders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReminderInput"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "201": {
            "description": "created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reminder"
                }
              }
            }
          },
          "400": {
            "description": "invalid kind/targetingMode, blank text, empty/non-canonical weekdays, zero/inactive-member assignments, or a query/queryFields field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/reminders/emissions": {
      "get": {
        "operationId": "getRemindersEmissions",
        "summary": "Outbound read — scheduled reminders emitting for (member,date). Daily-Briefing consumer interface.",
        "tags": [
          "reminders"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "memberId",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "date",
            "required": true,
            "description": "strict YYYY-MM-DD"
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "emitting reminders (empty if member inactive or none apply)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ReminderEmission"
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid/impossible date",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/reminders/{id}": {
      "get": {
        "operationId": "getRemindersById",
        "summary": "One reminder rule + its assignments.",
        "tags": [
          "reminders"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "reminder",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reminder"
                }
              }
            }
          },
          "404": {
            "description": "not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "patchRemindersById",
        "summary": "Edit text/active/weekdays/query and switch targetingMode (assignments for specific). kind immutable (FR-013).",
        "tags": [
          "reminders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReminderEditInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reminder"
                }
              }
            }
          },
          "400": {
            "description": "kind in body, invalid targetingMode, missing weekdays/assignments for the switch, or invalid field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteRemindersById",
        "summary": "Hard-delete a reminder rule (genuine removal, distinct from active:false). Cascades to its reminder_assignment rows (ON DELETE CASCADE).\n",
        "tags": [
          "reminders"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "deleted"
          },
          "404": {
            "description": "not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/reminders/{id}/assignments": {
      "put": {
        "operationId": "putRemindersByIdAssignments",
        "summary": "Atomic full-set replace of a specific-mode rule's assignments (the admin matrix \"save\"). Replaces the entire active assignment set in ONE transaction — upsert the members present, deactivate those absent (deactivate, never hard-delete). Last-write- wins (no If-Match/409 optimistic concurrency — deferred #395). The ONLY assignment- write operation, so a multi-member edit (add one, remove another, change weekdays) commits or rolls back as a whole — no partial per-row writes. An empty set is rejected (a specific rule may not drop to zero active assignments — use the rule's active:false to silence instead; FR-005/INV-02). apply_to_all rules reject this endpoint (they carry no assignments).\n",
        "tags": [
          "reminders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReminderAssignmentSetInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "the resulting active assignment set",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ReminderAssignment"
                  }
                }
              }
            }
          },
          "400": {
            "description": "apply_to_all rule, empty set, inactive member, or non-canonical weekday",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "reminder not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/reminders/{id}/dry-run": {
      "post": {
        "operationId": "postRemindersByIdDryRun",
        "summary": "Dry-run / explain (009,) — would this calendar_gated rule emit for (memberId, date), and if not, why (the 3 mutually-exclusive reasons, FR-008). 400 if the stored rule is not calendar_gated (a scheduled rule's emission is not opaque).\n",
        "tags": [
          "reminders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DryRunInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "verdict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DryRunResult"
                }
              }
            }
          },
          "400": {
            "description": "bad memberId/date/body, or the rule is not kind=calendar_gated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "rule not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/routines": {
      "get": {
        "operationId": "getRoutines",
        "summary": "List active routines, ordered by day-period start time, then name (FR-016).",
        "tags": [
          "chores"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Routine"
                  }
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postRoutines",
        "summary": "Create a routine attached to one day period.",
        "tags": [
          "chores"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoutineInput"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "201": {
            "description": "created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Routine"
                }
              }
            }
          },
          "400": {
            "description": "validation (bad dayPeriodId, empty name)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/routines/{id}": {
      "get": {
        "operationId": "getRoutinesById",
        "summary": "Fetch one routine by id — tolerant of soft-deleted rows (FR-007/INV-08: a soft-deleted routine stays readable for history). The single-fetch companion to the active-only list in GET /api/routines.\n",
        "tags": [
          "chores"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK — active or soft-deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Routine"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such routine ever existed"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "patchRoutinesById",
        "summary": "Edit a routine's name, active flag and/or day period (FR-015).",
        "tags": [
          "chores"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoutineEditInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Routine"
                }
              }
            }
          },
          "400": {
            "description": "validation (blank name, non-boolean active, blank or unknown dayPeriodId)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such routine"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteRoutinesById",
        "summary": "Soft-delete a routine (INV-08) — excluded from active reads/streak, stays historical.",
        "tags": [
          "chores"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "soft-deleted"
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such routine"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/routines/{id}/assignments": {
      "get": {
        "operationId": "getRoutinesByIdAssignments",
        "summary": "List a routine's assignments (active and inactive, for admin history).",
        "tags": [
          "chores"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Assignment"
                  }
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "The requested routine does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RouteError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/routines/{id}/assignments/{memberId}": {
      "put": {
        "operationId": "putRoutinesByIdAssignmentsByMemberId",
        "summary": "Upsert the routine/member assignment (FR-001/FR-002/FR-005) — reactivation reuses the row.",
        "tags": [
          "chores"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssignmentUpsert"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "memberId",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "upserted (atomic)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Assignment"
                }
              }
            }
          },
          "400": {
            "description": "member not an active child (INV-01), or a weekday outside the 7-code enum (AC-05)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such routine"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteRoutinesByIdAssignmentsByMemberId",
        "summary": "Soft-deactivate the assignment (sets active=false; row is never hard-deleted, INV-08).",
        "tags": [
          "chores"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "memberId",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "deactivated"
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such assignment"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/routines/{id}/chores": {
      "get": {
        "operationId": "getRoutinesByIdChores",
        "summary": "List a routine's active chores, ordered.",
        "tags": [
          "chores"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Chore"
                  }
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "The requested routine does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RouteError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postRoutinesByIdChores",
        "summary": "Add a chore to a routine (appended at the end of sortOrder).",
        "tags": [
          "chores"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChoreInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "201": {
            "description": "created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Chore"
                }
              }
            }
          },
          "400": {
            "description": "validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such routine"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/routines/{id}/chores/order": {
      "put": {
        "operationId": "putRoutinesByIdChoresOrder",
        "summary": "Atomically reorder a routine's chores (FR-005/FR-006) — full-order replace, no partial state.",
        "tags": [
          "chores"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChoreOrderInput"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "reordered (atomic)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Chore"
                  }
                }
              }
            }
          },
          "400": {
            "description": "choreIds does not match the routine's active chore set",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "missing/invalid device key"
          },
          "404": {
            "description": "no such routine"
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/settings": {
      "get": {
        "operationId": "getSettings",
        "summary": "Cold-readable effective settings (valid key only; no admin session/PIN).",
        "tags": [
          "settings"
        ],
        "description": "Available at cold boot with a valid key and no PIN (FR-008/009/011).",
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Effective settings including the fully-populated locale object.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EffectiveSettings"
                }
              }
            }
          },
          "401": {
            "description": "No/invalid key (PIN state is irrelevant to this outcome).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "putSettings",
        "summary": "Replace one registered settings object.",
        "tags": [
          "settings"
        ],
        "description": "Validates the envelope and entire object before persisting it. Successful writes return the current effective settings projection. Unknown object names and invalid settings fail without a partial write. The UI PIN does not authorize this operation.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WriteSettingsRequest"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Effective settings after the write.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EffectiveSettings"
                }
              }
            }
          },
          "400": {
            "description": "Invalid envelope, unknown object, or invalid settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "No/invalid device key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "Unexpected persistence or server failure; details are not exposed in the response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/telemetry/client-log": {
      "post": {
        "operationId": "ingestClientLog",
        "summary": "Ingest a bounded batch of client log entries (telemetry:write)",
        "tags": [
          "telemetry"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClientLogBatch"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Batch processed best-effort. Invalid entries and flood-dropped entries are counted in `dropped`; the response is 200 even when every entry was dropped.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientLogIngestResult"
                }
              }
            }
          },
          "400": {
            "description": "Structurally unparseable body (not JSON / not the batch shape).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "readClientLog",
        "summary": "Read the client log, filtered and cursor-paged (telemetry:admin)",
        "tags": [
          "telemetry"
        ],
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/ClientLogLevel"
            },
            "in": "query",
            "name": "level",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "component",
            "required": false
          },
          {
            "schema": {
              "type": "integer"
            },
            "in": "query",
            "name": "from",
            "required": false,
            "description": "Inclusive lower bound on received_at (epoch ms)."
          },
          {
            "schema": {
              "type": "integer"
            },
            "in": "query",
            "name": "to",
            "required": false,
            "description": "Inclusive upper bound on received_at (epoch ms)."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "cursor",
            "required": false,
            "description": "Opaque continuation cursor from a previous page."
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Newest-first page, server-hard-capped at 50 rows.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientLogPage"
                }
              }
            }
          },
          "400": {
            "description": "Invalid filter or cursor.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/telemetry/system-status": {
      "get": {
        "operationId": "readSystemStatus",
        "summary": "Report the running server's health and the commit it was built from (telemetry:admin)",
        "tags": [
          "telemetry"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "The server answered; `build` names what is deployed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemStatus"
                }
              }
            }
          },
          "401": {
            "description": "Missing, ambiguous or invalid API credential (shared authentication boundary).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthUnauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/time-announcements": {
      "get": {
        "operationId": "getTimeAnnouncements",
        "summary": "List all rules (inactive included), ordered by time — kiosk-visible",
        "tags": [
          "time-announcements"
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "All rules ordered by time (ties by id).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/TimeAnnouncementRule"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginUnavailable"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postTimeAnnouncements",
        "summary": "Create a rule (admin write capability)",
        "tags": [
          "time-announcements"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TimeAnnouncementRuleCreate"
              }
            }
          }
        },
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimeAnnouncementRule"
                }
              }
            }
          },
          "400": {
            "description": "Malformed time / empty or non-canonical weekdays / unknown keys — no row created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "409": {
            "description": "Active rule overlaps another active rule (same time + shared weekday).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OverlapError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/time-announcements/{id}": {
      "patch": {
        "operationId": "patchTimeAnnouncementsById",
        "summary": "Partial edit / toggle active (admin write capability; overlap re-checked when result is active)",
        "tags": [
          "time-announcements"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TimeAnnouncementRulePatch"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Updated (LWW by id against latest persisted rows).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimeAnnouncementRule"
                }
              }
            }
          },
          "400": {
            "description": "Malformed fields / unknown keys / empty patch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "404": {
            "description": "Unknown rule id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "Patch would leave an active rule overlapping another active rule.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OverlapError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteTimeAnnouncementsById",
        "summary": "Permanent delete, no archive tier (admin write capability)",
        "tags": [
          "time-announcements"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted permanently."
          },
          "403": {
            "description": "Revoked/expired credential or denied capability; code distinguishes credential loss from scope denial.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthForbidden"
                }
              }
            }
          },
          "404": {
            "description": "Unknown rule id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/weather": {
      "get": {
        "operationId": "getWeather",
        "summary": "Read the normalized forecast for the household's configured location",
        "tags": [
          "weather"
        ],
        "description": "WEATHER's only own surface (FR-024) — the location is read/written ONLY through App Settings; no weather settings endpoint exists (negative-proved via `app.hasRoute`). `forecast: null` covers every absence case alike (blank location, operator-disabled via `WEATHER_ENABLED`, or a failed/timed-out upstream fetch) — NEVER a 5xx (WEATHER-INV-12, D3). Gated only by the app-wide API-key boundary, no capability (mirrors `GET /api/settings`).\n",
        "security": [
          {
            "deviceKeyCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Always 200 — absence is expressed as `forecast: null`, never an error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WeatherResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid API key."
          },
          "429": {
            "description": "Repeated credential failures from this transport source. Valid active credentials remain usable; this is failure-only retry backpressure, not a hard guess or request-volume limit.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Remaining cooldown in seconds, rounded up. Retry manually.",
                "required": true
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                },
                "required": true
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_requests"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Authentication retry required"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "The owning plugin is inactive or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginUnavailable"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Liveness — the ONLY unauthenticated route (allowlisted).",
        "tags": [
          "bootstrap"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Always reachable, even with no credential configured (FR-002).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "{base}",
      "description": "Your Marplanner instance",
      "variables": {
        "base": {
          "default": "http://localhost:3000"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "bootstrap",
      "description": "**Marplanner foundation API**\n\nHealth, frontend access, device provisioning, PIN verification and household settings. Device cookies authorize the API. Effective settings contain only active contributions; the UI PIN is advisory."
    },
    {
      "name": "settings",
      "description": "**Marplanner — Settings registry API**\n\nRead the effective settings projection (core locale plus the settings objects of active plugins) and atomically replace one registered settings object. The UI PIN does not authorize writes."
    },
    {
      "name": "members",
      "description": "**Marplanner — Members referential root API**\n\nMember creation, editing, archive and restore. Member roles and lifecycle are validated independently from API credential capabilities. Historical records remain readable after archival."
    },
    {
      "name": "day-periods",
      "description": "**Marplanner — Day Periods vocabulary API**\n\nThe fixed four household day periods and their editable start times. Ordering and uniqueness are validated; end boundaries derive from the next start."
    },
    {
      "name": "chores",
      "description": "**Marplanner — Household Daily Chores Board API**\n\nRoutines, member assignments, dated completion and derived streaks. Active-member validation applies on writes; historical reads tolerate archived members."
    },
    {
      "name": "calendar",
      "description": "**Marplanner — Calendar local feed API**\n\nLocal and imported events, recurrence, member assignment, highlight rules and source metadata. Timed events preserve UTC instants and originating timezones; all-day dates use exclusive end boundaries.\n\n**Marplanner Calendar Feed Synchronization API**\n\nExternal calendar source configuration, synchronization and safe diagnostics. Fetch validation rejects private network destinations; writes reconcile complete source results atomically."
    },
    {
      "name": "meals",
      "description": "**Marplanner — Meals & Recipes API**\n\nRecipe catalogue, meal types and additive dated or recurring meal entries. Deleting a recipe requires an informed cascade; read projections remain derived from current data."
    },
    {
      "name": "reminders",
      "description": "**Marplanner — Scheduled Reminders API**\n\nScheduled reminder CRUD, assignment replacement, and live emissions. Supports all-member and explicit-member modes. Assignment replacement is atomic; the advisory UI PIN does not authorize backend requests.\n\n**Marplanner — Calendar-gated Reminders API delta**\n\nCalendar-gated reminders extend scheduled reminder CRUD and assignments with query rules and dry-run explanations. Request shapes are discriminated by reminder kind."
    },
    {
      "name": "daily-messages",
      "description": "**Marplanner — Daily Messages API**\n\nPer-member daily messages with strict dates and text validation. Writes require an active member; reads preserve archived-member history and reject unknown members. The device-key cookie authorizes backend access."
    },
    {
      "name": "daily-briefing",
      "description": "**Marplanner — Daily Briefing API**\n\nBriefing block configuration, generation, preview and print integration. The server composes and renders content; printing uses the current registered provider at execution time.\n\n**Marplanner — Daily Briefing API**\n\nMember briefing generation, opt-in settings, snapshots and status. Calendar, chores, reminders, meals and messages are read through their owning domain interfaces."
    },
    {
      "name": "time-announcements",
      "description": "**Marplanner — Time Announcements API**\n\nRule-CRUD surface for. The server owns rule DATA ONLY — firing is entirely client-side (ADR-051 as reconciled by ADR-065): no server-side scheduler job, queue row, claim, or staleness sweep exists for announcements, so this contract is the domain's WHOLE server surface (drift-checked by tools/check-openapi-drift.mjs). Writes require the time-announcements:admin capability (fail-closed via registerRoutesWithCapabilities, telemetry precedent); the list is kiosk-visible behind the standard auth boundary (TIME-ANNOUNCEMENTS-AC-07). Validation is strict-reject, never normalize (TIME-ANNOUNCEMENTS-INV-02/03); the active-overlap check runs inside the write transaction on POST and PATCH (TIME-ANNOUNCEMENTS-INV-04)."
    },
    {
      "name": "weather",
      "description": "**Marplanner — Weather API**\n\nHousehold location settings and forecast reads. Location may be unset. Provider unavailability is explicit; inactive plugin settings are omitted from effective settings."
    },
    {
      "name": "printing",
      "description": "**marplanner printing**\n\nDurable printing jobs, printer capability registration, fenced claims, payloads, acknowledgement and failure reporting. Printed state requires a valid acknowledgement. The browser performs physical transport."
    },
    {
      "name": "network-devices",
      "description": "**Marplanner — Network Devices API**\n\nRegistered network devices, live controller inventory and block state. Every route requires an active credential with the network:admin (or full \"*\") capability; a normally provisioned household device qualifies. Provider failures use safe typed errors."
    },
    {
      "name": "backups",
      "description": "**Marplanner — Backups API**\n\nSnapshot, shelf, download, upload, delete and quiescent restore operations. Requires backups:admin capability. Restore validates compatibility and takes a pre-restore snapshot before replacing the database."
    },
    {
      "name": "telemetry",
      "description": "**Marplanner Client Logging / Telemetry API**\n\nTelemetry ingest + admin read. Ingest is best-effort at-most-once: a well-formed batch ALWAYS returns 200 (accepted/dropped counts), never 429 and never per-entry errors the client would react to. Redaction and bounding happen server-side before storage (Constitution II). Capabilities: telemetry:write (ingest) / telemetry:admin (read); full-access ('*') keys satisfy both."
    },
    {
      "name": "plugins",
      "description": "**Marplanner Plugin Lifecycle API**\n\nAuthenticated first-party plugin catalog and lifecycle mutations for. Canonical plugin state is active, inactive, or errored; operation is a separate transient projection. The API never accepts or returns the admin PIN or raw errors."
    },
    {
      "name": "docs",
      "description": "**API documentation**\n\nThe generated OpenAPI document and its interactive reference UI (`/api/docs`). Same authentication as the rest of `/api/*`."
    }
  ]
}
