{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["schema_version", "helpers"],
  "properties": {
    "schema_version": { "const": "helper-tools-registry.v1" },
    "helpers": {
      "type": "array",
      "minItems": 1,
      "items": { "$ref": "#/$defs/helper" }
    }
  },
  "additionalProperties": false,
  "$defs": {
    "helper": {
      "type": "object",
      "required": [
        "id",
        "kind",
        "profiles",
        "surface_overlays",
        "required",
        "baseline_blocking",
        "required_for",
        "recommended_for",
        "demand_signals",
        "detection",
        "installation",
        "safety",
        "platform_required_tools",
        "runner_kind"
      ],
      "properties": {
        "id": { "type": "string", "minLength": 1 },
        "kind": { "enum": ["cli", "global-skill", "browser-helper"] },
        "profiles": {
          "type": "array",
          "items": { "enum": ["minimal", "recommended", "platform"] }
        },
        "surface_overlays": {
          "type": "array",
          "items": { "enum": ["surface-ui", "surface-data-security"] }
        },
        "required": { "type": "boolean" },
        "baseline_blocking": { "type": "boolean" },
        "required_for": {
          "type": "array",
          "items": { "type": "string" }
        },
        "recommended_for": {
          "type": "array",
          "items": { "type": "string" }
        },
        "demand_signals": {
          "type": "array",
          "items": { "type": "string" }
        },
        "detection": {
          "type": "object",
          "required": ["kind"],
          "properties": {
            "kind": { "enum": ["command", "global-skill", "agent-browser"] },
            "command": { "type": "string" },
            "skill_name": { "type": "string" },
            "fallback_command": { "type": "string" }
          },
          "additionalProperties": false
        },
        "installation": {
          "type": "object",
          "required": ["strategy", "commands", "next_action"],
          "properties": {
            "strategy": { "enum": ["package-manager", "npm-global", "skills-cli", "manual", "explicit-opt-in"] },
            "commands": {
              "type": "object",
              "description": "Display/approval-only approximate install commands per OS. NOT the execution source of truth: actual installs run through install-helpers.sh run_install_command (environment-aware: package-manager detection, brew upgrade wrapping, mirror fallback). Kept for human/LLM-readable approval context.",
              "properties": {
                "macos": { "type": "string" },
                "linux": { "type": "string" },
                "windows": { "type": "string" }
              },
              "additionalProperties": false
            },
            "next_action": { "type": "string" }
          },
          "additionalProperties": false
        },
        "safety": {
          "type": "object",
          "required": ["risk_flags", "source", "source_repo", "version_policy", "review_required", "install_effect"],
          "properties": {
            "risk_flags": {
              "type": "array",
              "items": { "type": "string" }
            },
            "source": { "type": "string" },
            "source_repo": { "type": "string" },
            "version_policy": {
              "type": "object",
              "required": ["pin_status"],
              "properties": {
                "pin_status": { "enum": ["pinned", "unpinned", "latest", "manual", "not-applicable"] }
              },
              "additionalProperties": false
            },
            "review_required": { "type": "boolean" },
            "install_effect": { "type": "string" }
          },
          "additionalProperties": false
        },
        "platform_required_tools": {
          "type": "object",
          "required": ["shell", "powershell"],
          "properties": {
            "shell": {
              "type": "array",
              "items": { "type": "string" }
            },
            "powershell": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "additionalProperties": false
        },
        "runner_kind": { "enum": ["shell", "powershell", "cross-platform"] }
      },
      "additionalProperties": false
    }
  }
}