{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hermes.bstein.dev/contracts/hux/v1/suggestion.schema.json",
  "title": "HUX onboarding suggestion and suppression state",
  "description": "Restrained onboarding (HUX-09). A suggestion declares exactly when it may appear and how often; suppression state is per user and wins over the suggestion. Nothing is shown without a trigger, and every suggestion is dismissable.",
  "$defs": {
    "suggestion": {
      "type": "object",
      "additionalProperties": false,
      "required": ["schema", "id", "kind", "trigger", "title", "body", "priority", "suppression"],
      "properties": {
        "schema": {"const": "hux.suggestion.v1"},
        "id": {"$ref": "common.schema.json#/$defs/id"},
        "kind": {"type": "string", "enum": ["workflow", "project", "feature", "tip"]},
        "trigger": {
          "type": "object",
          "additionalProperties": false,
          "required": ["surface", "context"],
          "properties": {
            "surface": {"$ref": "common.schema.json#/$defs/surface"},
            "context": {"type": "string", "enum": ["first_session", "empty_project", "after_artifact", "after_research", "after_approval", "idle"]}
          }
        },
        "title": {"type": "string", "minLength": 1, "maxLength": 80},
        "body": {"type": "string", "minLength": 1, "maxLength": 280},
        "action": {
          "type": "object",
          "additionalProperties": false,
          "required": ["type"],
          "properties": {
            "type": {"type": "string", "enum": ["open_mode", "create_project", "open_memory", "open_artifacts", "start_workflow", "none"]},
            "payload": {"type": "object"}
          }
        },
        "priority": {"type": "integer", "minimum": 0, "maximum": 100},
        "suppression": {
          "type": "object",
          "additionalProperties": false,
          "required": ["dismissable", "max_shows", "cooldown_seconds", "never_again_supported"],
          "properties": {
            "dismissable": {"const": true},
            "max_shows": {"type": "integer", "minimum": 1, "maximum": 5},
            "cooldown_seconds": {"type": "integer", "minimum": 3600},
            "never_again_supported": {"const": true}
          }
        }
      }
    },
    "state": {
      "type": "object",
      "additionalProperties": false,
      "required": ["schema", "owner", "suggestion_id", "shows", "never_again"],
      "properties": {
        "schema": {"const": "hux.suggestion_state.v1"},
        "owner": {"$ref": "common.schema.json#/$defs/user_ref"},
        "suggestion_id": {"$ref": "common.schema.json#/$defs/id"},
        "shows": {"type": "integer", "minimum": 0},
        "last_shown_at": {"$ref": "common.schema.json#/$defs/timestamp"},
        "dismissed_at": {"$ref": "common.schema.json#/$defs/timestamp"},
        "acted_at": {"$ref": "common.schema.json#/$defs/timestamp"},
        "never_again": {"type": "boolean"}
      }
    }
  },
  "oneOf": [
    {"$ref": "#/$defs/suggestion"},
    {"$ref": "#/$defs/state"}
  ]
}