headlesson

Find and compare CLI, MCP, and API apps by task, name, and confirmed axes. Known axis spelling aliases are normalized (licence to license, local_mcp_server to local_mcp, remote_mcp_server to remote_mcp); unrecognized axes are reported as unknown_axes. Private sources use an operator-provided or editorial source label; local paths are not returned as citations. Non-public provenance exceptions are grouped by source/at/cert/by. operator_own is an operational observation excluded from source-default inheritance.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Task or product name in English or Japanese; common request words are ignored.",
      "examples": [
        "schedule social media posts",
        "SNS に予約投稿したい",
        "Postiz"
      ],
      "type": "string"
    },
    "where": {
      "description": "Confirmed axis filters: AND across axes, OR inside a value array; known spelling aliases are normalized.",
      "examples": [
        {
          "remote_mcp": true,
          "pricing": [
            "paid",
            "freemium"
          ]
        }
      ],
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "boolean"
          },
          {
            "type": "number"
          },
          {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": [
                "string",
                "boolean",
                "number"
              ]
            }
          }
        ],
        "description": "One confirmed value or an OR-list for an axis; unknown is never a confirmed match.",
        "examples": [
          true,
          [
            "paid",
            "freemium"
          ]
        ]
      }
    },
    "axes": {
      "description": "Axes to compare: auth, pricing, license, cli, local_mcp, remote_mcp are useful starting points; licence is normalized to license.",
      "examples": [
        [
          "auth",
          "pricing",
          "remote_mcp"
        ],
        [
          "licence"
        ]
      ],
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "sort": {
      "description": "Optional axis ordering before relevance; unknown values remain last.",
      "examples": [
        {
          "axis": "last_release",
          "order": "desc"
        }
      ],
      "type": "object",
      "properties": {
        "axis": {
          "type": "string",
          "description": "Axis used for ordering; spelling aliases such as licence are normalized.",
          "examples": [
            "last_release",
            "pricing"
          ]
        },
        "order": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ],
          "description": "Ascending or descending order; unknown is last in either direction.",
          "examples": [
            "desc"
          ]
        }
      },
      "required": [
        "axis",
        "order"
      ],
      "additionalProperties": false
    },
    "ids": {
      "description": "Explicit app IDs to compare; any missing ID produces an error instead of being silently omitted.",
      "examples": [
        [
          "app:postiz",
          "app:typefully"
        ]
      ],
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "limit": {
      "default": 5,
      "description": "Maximum app results, from 1 to 20; default is 5.",
      "examples": [
        5
      ],
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Get a recorded app, concept, protocol, usecase, feature, axes or search guide by ID. Private source tuples use non-URL source labels and grouped non-public exceptions; docs/homepage labels are not links. operator_own and lesson.tested retain their values but are operational observations excluded from source-default inheritance.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Record ID or the special axes/search-guide ID; missing records return nearby ID suggestions.",
      "examples": [
        "app:postiz",
        "feature:since-2025",
        "axes",
        "search-guide"
      ]
    },
    "sections": {
      "description": "App sections to return in text and structuredContent; omitted means description, interfaces and six major axes.",
      "examples": [
        [
          "lesson",
          "gotchas"
        ],
        [
          "axes",
          "relations",
          "changes"
        ]
      ],
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "lesson",
          "relations",
          "gotchas",
          "changes",
          "axes"
        ]
      }
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

List documented changes since a date, optionally by kind or affected record. Public source URLs remain; private sources use non-URL labels and grouped exceptions.

{
  "type": "object",
  "properties": {
    "since": {
      "description": "Inclusive event-date lower bound in YYYY-MM-DD; omitted uses the previous 90 days, not source confirmation dates.",
      "examples": [
        "2026-01-01"
      ],
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "kinds": {
      "description": "Change kinds to include; the array is an OR-list.",
      "examples": [
        [
          "breaking",
          "deprecation"
        ]
      ],
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "new",
          "rename",
          "deprecation",
          "breaking",
          "standard",
          "acquisition"
        ]
      }
    },
    "about": {
      "description": "Affected record ID to filter changes, such as an app or protocol.",
      "examples": [
        "proto:mcp"
      ],
      "type": "string"
    },
    "limit": {
      "default": 20,
      "description": "Maximum changes, from 1 to 100; default is 20.",
      "examples": [
        20
      ],
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

This content is sent to the headlesson operator. Feedback about headlesson itself is sufficient. Do not include personal information or conversation contents.

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "Feedback to the headlesson operator, 1–2000 Unicode characters; exclude personal information and conversation text.",
      "minLength": 1,
      "maxLength": 2000,
      "examples": [
        "The lesson needs a clearer owner-login prerequisite."
      ]
    },
    "kind": {
      "default": "comment",
      "description": "Report type: comment, worked, failed, missing or tip; receipt does not verify the claim.",
      "examples": [
        "missing"
      ],
      "type": "string",
      "enum": [
        "comment",
        "worked",
        "failed",
        "missing",
        "tip"
      ]
    },
    "about": {
      "description": "Optional record ID that the feedback concerns; feedback about headlesson itself needs no product ID.",
      "examples": [
        "app:postiz"
      ],
      "type": "string"
    },
    "client": {
      "description": "Optional client name only; do not include full User-Agent, account IDs or credentials.",
      "examples": [
        "MCP Inspector"
      ],
      "type": "string"
    },
    "model": {
      "description": "Optional model name associated with the report, without conversation content.",
      "examples": [
        "model-name"
      ],
      "type": "string"
    }
  },
  "required": [
    "text"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}