{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agentguides.io/schemas/0.1/install.schema.json",
  "title": "INSTALL.md frontmatter",
  "description": "JSON Schema for the YAML frontmatter `install:` block of a repo's INSTALL.md (the agent-installable convention). Generated from agentguides.spec.install.",
  "$defs": {
    "GuideAction": {
      "additionalProperties": false,
      "properties": {
        "os": {
          "description": "Optional OS filter; omit = any OS.",
          "items": {
            "enum": [
              "macos",
              "linux",
              "windows"
            ],
            "type": "string"
          },
          "type": "array"
        },
        "kind": {
          "const": "guide",
          "type": "string"
        },
        "ref": {
          "description": "Relative reference to a co-located Guide.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "kind",
        "ref"
      ],
      "type": "object"
    },
    "InstallBlock": {
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Stable kebab-case identifier for the thing being installed.",
          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
          "type": "string"
        },
        "summary": {
          "description": "One line: what this is and why you'd install it.",
          "minLength": 1,
          "type": "string"
        },
        "methods": {
          "description": "Ordered ALTERNATIVES; the agent selects ONE best-fit entry.",
          "items": {
            "discriminator": {
              "mapping": {
                "guide": "#/$defs/GuideAction",
                "manual": "#/$defs/ManualAction",
                "package": "#/$defs/PackageAction",
                "plugin": "#/$defs/PluginAction",
                "script": "#/$defs/ScriptAction",
                "skill": "#/$defs/SkillAction"
              },
              "propertyName": "kind"
            },
            "oneOf": [
              {
                "$ref": "#/$defs/PackageAction"
              },
              {
                "$ref": "#/$defs/PluginAction"
              },
              {
                "$ref": "#/$defs/SkillAction"
              },
              {
                "$ref": "#/$defs/GuideAction"
              },
              {
                "$ref": "#/$defs/ScriptAction"
              },
              {
                "$ref": "#/$defs/ManualAction"
              }
            ]
          },
          "minItems": 1,
          "type": "array"
        },
        "verify": {
          "description": "Optional command expected to exit 0 post-install.",
          "type": "string"
        },
        "upgrade": {
          "description": "Optional policy for when the tool is ALREADY installed. never (default when absent): keep the installed version, skip. ask: report installed-vs-available and upgrade only with consent (explicit consent even under auto-approve). always: prefer latest — recommend the upgrade, auto-approvable. Advisory only: 'available' is best-effort via the manager's own upgrade idiom; no version pin, lockfile, or resolver.",
          "enum": [
            "never",
            "ask",
            "always"
          ],
          "type": "string"
        },
        "configure": {
          "description": "Optional ordered post-install actions the agent runs ALL of, in order.",
          "items": {
            "discriminator": {
              "mapping": {
                "guide": "#/$defs/GuideAction",
                "manual": "#/$defs/ManualAction",
                "package": "#/$defs/PackageAction",
                "plugin": "#/$defs/PluginAction",
                "script": "#/$defs/ScriptAction",
                "skill": "#/$defs/SkillAction"
              },
              "propertyName": "kind"
            },
            "oneOf": [
              {
                "$ref": "#/$defs/PackageAction"
              },
              {
                "$ref": "#/$defs/PluginAction"
              },
              {
                "$ref": "#/$defs/SkillAction"
              },
              {
                "$ref": "#/$defs/GuideAction"
              },
              {
                "$ref": "#/$defs/ScriptAction"
              },
              {
                "$ref": "#/$defs/ManualAction"
              }
            ]
          },
          "type": "array"
        }
      },
      "required": [
        "id",
        "summary",
        "methods"
      ],
      "type": "object"
    },
    "ManualAction": {
      "additionalProperties": false,
      "properties": {
        "os": {
          "description": "Optional OS filter; omit = any OS.",
          "items": {
            "enum": [
              "macos",
              "linux",
              "windows"
            ],
            "type": "string"
          },
          "type": "array"
        },
        "kind": {
          "const": "manual",
          "type": "string"
        },
        "instructions": {
          "description": "What the agent tells the user to do (and waits).",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "kind",
        "instructions"
      ],
      "type": "object"
    },
    "PackageAction": {
      "additionalProperties": false,
      "properties": {
        "os": {
          "description": "Optional OS filter; omit = any OS.",
          "items": {
            "enum": [
              "macos",
              "linux",
              "windows"
            ],
            "type": "string"
          },
          "type": "array"
        },
        "kind": {
          "const": "package",
          "type": "string"
        },
        "manager": {
          "description": "Package-manager label matched to the user's preference.",
          "minLength": 1,
          "type": "string"
        },
        "command": {
          "description": "Exact install invocation.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "kind",
        "manager",
        "command"
      ],
      "type": "object"
    },
    "PluginAction": {
      "additionalProperties": false,
      "properties": {
        "os": {
          "description": "Optional OS filter; omit = any OS.",
          "items": {
            "enum": [
              "macos",
              "linux",
              "windows"
            ],
            "type": "string"
          },
          "type": "array"
        },
        "kind": {
          "const": "plugin",
          "type": "string"
        },
        "harness": {
          "description": "Target harness for the plugin.",
          "minLength": 1,
          "type": "string"
        },
        "ref": {
          "description": "Plugin / marketplace id or install command.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "kind",
        "harness",
        "ref"
      ],
      "type": "object"
    },
    "ScriptAction": {
      "additionalProperties": false,
      "properties": {
        "os": {
          "description": "Optional OS filter; omit = any OS.",
          "items": {
            "enum": [
              "macos",
              "linux",
              "windows"
            ],
            "type": "string"
          },
          "type": "array"
        },
        "kind": {
          "const": "script",
          "type": "string"
        },
        "command": {
          "description": "Command running an in-tree script.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "kind",
        "command"
      ],
      "type": "object"
    },
    "SkillAction": {
      "additionalProperties": false,
      "properties": {
        "os": {
          "description": "Optional OS filter; omit = any OS.",
          "items": {
            "enum": [
              "macos",
              "linux",
              "windows"
            ],
            "type": "string"
          },
          "type": "array"
        },
        "kind": {
          "const": "skill",
          "type": "string"
        },
        "registry": {
          "description": "Registry that hosts the skill.",
          "minLength": 1,
          "type": "string"
        },
        "ref": {
          "description": "Skill id within the registry.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "kind",
        "registry",
        "ref"
      ],
      "type": "object"
    }
  },
  "properties": {
    "install": {
      "$ref": "#/$defs/InstallBlock"
    }
  },
  "required": [
    "install"
  ],
  "type": "object"
}