{
  "openapi": "3.1.0",
  "info": {
    "title": "Wheelie feature discovery API",
    "version": "0.1.0",
    "summary": "Provider-neutral, low-noise feature suggestions for Wheelie CLI and web surfaces.",
    "description": "The contract accepts typed usage/context signals and returns a small ranked set of support-level-honest suggestions. Callers must not send raw command arguments, source paths, secrets, or free-form project content."
  },
  "servers": [{ "url": "https://wheelie.dev" }],
  "paths": {
    "/v1/wheelie/feature-suggestions": {
      "post": {
        "operationId": "suggestWheelieFeatures",
        "summary": "Return low-noise Wheelie feature suggestions for one surface/context.",
        "tags": ["wheelie", "feature-discovery"],
        "x-support-level": "preview_static_catalog_with_client_personalization",
        "x-privacy": {
          "raw_command_arguments_collected": false,
          "raw_source_paths_collected": false,
          "secret_values_collected": false,
          "server_side_personalization_requires_consent": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/FeatureSuggestionRequest" },
              "examples": {
                "cli_command_end": {
                  "value": {
                    "schema_version": "wheelie_feature_suggestion_request/v1",
                    "surface": "wheelie_cli_command_end",
                    "context": {
                      "command_family": "doctor",
                      "command_action": "none",
                      "active_workflow": "first_run"
                    },
                    "user_state": {
                      "used_feature_ids": ["install_update"],
                      "dismissed_suggestion_ids": [],
                      "recent_exposure_ids": []
                    },
                    "limit": 1
                  }
                },
                "web_reload": {
                  "value": {
                    "schema_version": "wheelie_feature_suggestion_request/v1",
                    "surface": "wheelie_dev_reload",
                    "context": { "active_workflow": "first_run" },
                    "user_state": {
                      "used_feature_ids": [],
                      "dismissed_suggestion_ids": ["try_checkpoint_handoff"],
                      "recent_exposure_ids": []
                    },
                    "limit": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked suggestions and rate-limit decision metadata.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FeatureSuggestionResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FeatureSuggestionRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["schema_version", "surface", "context", "user_state"],
        "properties": {
          "schema_version": { "type": "string", "const": "wheelie_feature_suggestion_request/v1" },
          "surface": { "$ref": "#/components/schemas/FeatureSuggestionSurface" },
          "context": { "$ref": "#/components/schemas/FeatureSuggestionContext" },
          "user_state": { "$ref": "#/components/schemas/FeatureSuggestionUserState" },
          "limit": { "type": "integer", "minimum": 1, "maximum": 3, "default": 1 },
          "org_policy_tags": { "type": "array", "items": { "type": "string" }, "default": [] }
        }
      },
      "FeatureSuggestionSurface": {
        "type": "string",
        "enum": ["wheelie_cli_command_end", "wheelie_dev_reload"]
      },
      "FeatureSuggestionContext": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "command_family": {
            "type": "string",
            "enum": [
              "version",
              "doctor",
              "auth",
              "models",
              "harness",
              "context",
              "work",
              "working-copy",
              "validation",
              "change",
              "checkpoint",
              "resources",
              "unknown"
            ]
          },
          "command_action": { "type": "string", "maxLength": 64 },
          "active_workflow": {
            "type": "string",
            "enum": ["first_run", "agent_setup", "coding", "validation", "handoff", "unknown"]
          }
        }
      },
      "FeatureSuggestionUserState": {
        "type": "object",
        "additionalProperties": false,
        "required": ["used_feature_ids", "dismissed_suggestion_ids", "recent_exposure_ids"],
        "properties": {
          "used_feature_ids": { "type": "array", "items": { "type": "string" } },
          "dismissed_suggestion_ids": { "type": "array", "items": { "type": "string" } },
          "recent_exposure_ids": { "type": "array", "items": { "type": "string" } },
          "disabled": { "type": "boolean", "default": false }
        }
      },
      "FeatureSuggestionResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["schema_version", "surface", "suggestions", "decision"],
        "properties": {
          "schema_version": { "type": "string", "const": "wheelie_feature_suggestion_response/v1" },
          "surface": { "$ref": "#/components/schemas/FeatureSuggestionSurface" },
          "suggestions": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/FeatureSuggestion" },
            "maxItems": 3
          },
          "decision": { "$ref": "#/components/schemas/FeatureSuggestionDecision" }
        }
      },
      "FeatureSuggestion": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "capability_id", "title", "why", "support_level", "support_state", "action", "cooldown_hours", "rank_score"],
        "properties": {
          "id": { "type": "string" },
          "capability_id": { "type": "string" },
          "title": { "type": "string" },
          "why": { "type": "string" },
          "support_level": { "type": "string" },
          "support_state": { "type": "string" },
          "action": { "$ref": "#/components/schemas/FeatureSuggestionAction" },
          "docs": { "type": "string" },
          "cooldown_hours": { "type": "integer", "minimum": 1 },
          "rank_score": { "type": "integer", "minimum": 0 },
          "metrics": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "impression_event": { "type": "string", "const": "wheelie_feature_suggestion_impression" },
              "click_event": { "type": "string", "const": "wheelie_feature_suggestion_click" },
              "dismiss_event": { "type": "string", "const": "wheelie_feature_suggestion_dismiss" }
            }
          }
        }
      },
      "FeatureSuggestionAction": {
        "type": "object",
        "additionalProperties": false,
        "required": ["kind", "target"],
        "properties": {
          "kind": { "type": "string", "enum": ["command", "link", "open_panel"] },
          "target": { "type": "string" }
        }
      },
      "FeatureSuggestionDecision": {
        "type": "object",
        "additionalProperties": false,
        "required": ["shown", "reason", "personalization_basis", "rate_limited"],
        "properties": {
          "shown": { "type": "boolean" },
          "reason": {
            "type": "string",
            "enum": [
              "shown",
              "disabled",
              "cooldown_active",
              "no_untried_supported_features",
              "policy_suppressed"
            ]
          },
          "personalization_basis": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["typed_command_context", "typed_workflow_context", "usage_history", "dismissal_history", "support_level_policy"]
            }
          },
          "rate_limited": { "type": "boolean" }
        }
      }
    }
  }
}