{
  "openapi": "3.1.0",
  "info": {
    "title": "illo skill public machine surface",
    "summary": "Read-only catalog and discovery files for the illo skill. No image render API.",
    "description": "Public HTTP resources on illo-skill.com. This origin publishes the character pack catalog, agent-facing docs, OpenAPI, and a catalog-only MCP server. It does **not** generate images, accept OAuth, take payments, or expose webhooks. Rendering happens in the installed agent skill (`illo.py` in tmchow/illo-skill).",
    "version": "1.0.0",
    "contact": {
      "name": "Trevin Chow",
      "url": "https://illo-skill.com/contact"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/license/mit/"
    }
  },
  "servers": [
    {
      "url": "https://illo-skill.com",
      "description": "Production marketing and catalog origin"
    }
  ],
  "tags": [
    {
      "name": "catalog",
      "description": "Public character pack list. Same facts as /characters.json."
    },
    {
      "name": "discovery",
      "description": "Agent-facing docs, OpenAPI, MCP manifests, CLI pointer."
    },
    {
      "name": "mcp",
      "description": "Streamable HTTP MCP for catalog lookup only."
    }
  ],
  "paths": {
    "/characters.json": {
      "get": {
        "operationId": "getCharacterCatalog",
        "tags": [
          "catalog"
        ],
        "summary": "Full character pack catalog",
        "description": "Return the site render catalog: every public pack with name, look, short description, notes, and preview URL. This is the file the characters page grid reads. Install a pack with `/illo install {name} character pack` after the skill is installed. Does not render images.",
        "responses": {
          "200": {
            "description": "Catalog document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CharacterCatalog"
                },
                "examples": {
                  "catalog": {
                    "summary": "Document header",
                    "value": {
                      "schema_version": "1.0",
                      "site": "https://illo-skill.com/",
                      "source_repo": "https://github.com/tmchow/illo-characters",
                      "install_phrase_template": "/illo install {name} character pack",
                      "characters": [
                        {
                          "name": "blot",
                          "look": "riso",
                          "description": "a deadpan ink drop",
                          "notes": "the quiet regular",
                          "preview": "https://illo-skill.com/img/tower-blot.webp"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/characters": {
      "get": {
        "operationId": "listCharacters",
        "tags": [
          "catalog"
        ],
        "summary": "List character packs, optionally filtered",
        "description": "Typed wrapper around the public catalog. Omit filters to list every pack. `look` restricts to one bundled print look. `name` returns a one-item list or 404. Same data as GET /characters.json. Does not render images.",
        "parameters": [
          {
            "name": "look",
            "in": "query",
            "required": false,
            "description": "Bundled print look to filter by.",
            "schema": {
              "type": "string",
              "enum": [
                "riso",
                "blueprint",
                "woodcut",
                "pixel",
                "clay",
                "manila",
                "chalk",
                "phosphor",
                "enamel",
                "gouache",
                "felt",
                "diorama",
                "sketchbook",
                "bricks",
                "fizz",
                "bloom",
                "snes"
              ]
            },
            "examples": {
              "riso": {
                "value": "riso"
              }
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Exact pack name (case-insensitive).",
            "schema": {
              "type": "string"
            },
            "examples": {
              "mole": {
                "value": "mole"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Filtered catalog list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CharacterList"
                }
              }
            }
          },
          "404": {
            "description": "Unknown path or character name. JSON problem with code, message, and hint.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/characters/{name}": {
      "get": {
        "operationId": "getCharacter",
        "tags": [
          "catalog"
        ],
        "summary": "Get one character pack by name",
        "description": "Return a single public pack plus the install phrase for the installed illo skill. Unknown names return a JSON problem (code, message, hint). Does not render images.",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "Pack name, e.g. blot or mole.",
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "examples": {
              "blot": {
                "value": "blot"
              },
              "mole": {
                "value": "mole"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One pack with install phrase.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CharacterRecord"
                }
              }
            }
          },
          "404": {
            "description": "Unknown path or character name. JSON problem with code, message, and hint.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiSpec",
        "tags": [
          "discovery"
        ],
        "summary": "OpenAPI 3.1 description of this origin",
        "description": "This document. Describes only real public GET resources and the catalog MCP POST. There is no checkout, OAuth, webhook, GraphQL, or image-render path.",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "tags": [
          "discovery"
        ],
        "summary": "Agent-facing reference",
        "description": "When to use the illo skill, install table, backends, character catalog pointer, MCP status, and CLI pointer (illo.py — not an npm API client).",
        "responses": {
          "200": {
            "description": "Plain-text agent reference.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-instructions.md": {
      "get": {
        "operationId": "getAgentInstructions",
        "tags": [
          "discovery"
        ],
        "summary": "When-to-use and how-to-call instructions",
        "description": "Markdown instructions for agents deciding whether to reach for the illo skill and how to invoke it after install.",
        "responses": {
          "200": {
            "description": "Markdown document.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/developers.md": {
      "get": {
        "operationId": "getDevelopersMarkdown",
        "tags": [
          "discovery"
        ],
        "summary": "illo skill developer resources (markdown)",
        "description": "Markdown twin of /developers. Title and H1: illo skill developer resources. Indexes OpenAPI, catalog, MCP, and the skill CLI.",
        "responses": {
          "200": {
            "description": "Markdown developer index.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/cli.json": {
      "get": {
        "operationId": "getCliPointer",
        "tags": [
          "discovery"
        ],
        "summary": "Machine-readable CLI pointer",
        "description": "The only honest CLI for illo skill is `illo.py` inside the installed skill (tmchow/illo-skill). This file says so in JSON. There is no npm package that calls illo-skill.com/api to render images.",
        "responses": {
          "200": {
            "description": "CLI pointer document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CliPointer"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/api-catalog": {
      "get": {
        "operationId": "getRfc9727ApiCatalog",
        "tags": [
          "discovery"
        ],
        "summary": "RFC 9727 API catalog",
        "description": "Linkset naming the public catalog API, OpenAPI spec, MCP endpoint, and developer docs.",
        "responses": {
          "200": {
            "description": "application/linkset+json catalog.",
            "content": {
              "application/linkset+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/ai-catalog.json": {
      "get": {
        "operationId": "getAiCatalog",
        "tags": [
          "discovery"
        ],
        "summary": "AI Catalog pointing at the MCP server card",
        "description": "Domain-level discovery document. Entries of type application/mcp-server-card+json point at /mcp/server-card.",
        "responses": {
          "200": {
            "description": "AI Catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/mcp": {
      "get": {
        "operationId": "getWellKnownMcp",
        "tags": [
          "mcp"
        ],
        "summary": "Well-known MCP discovery document",
        "description": "Points at the Streamable HTTP endpoint, server card, and registry manifest. Catalog lookup only.",
        "responses": {
          "200": {
            "description": "MCP discovery JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/server.json": {
      "get": {
        "operationId": "getMcpRegistryManifest",
        "tags": [
          "mcp"
        ],
        "summary": "MCP registry server.json",
        "description": "Remote Streamable HTTP manifest for the catalog MCP. No stdio npm package; no image tools.",
        "responses": {
          "200": {
            "description": "MCP server.json.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/mcp/server-card": {
      "get": {
        "operationId": "getMcpServerCard",
        "tags": [
          "mcp"
        ],
        "summary": "MCP server card",
        "description": "Static connectivity document for the catalog MCP (application/mcp-server-card+json). Also at /.well-known/mcp/server-card.json.",
        "responses": {
          "200": {
            "description": "MCP server card.",
            "content": {
              "application/mcp-server-card+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "postMcpJsonRpc",
        "tags": [
          "mcp"
        ],
        "summary": "Catalog-only Streamable HTTP MCP",
        "description": "JSON-RPC 2.0 Streamable HTTP endpoint. Tools: list_character_packs and get_character_pack, both read-only against /characters.json. initialize, tools/list, tools/call, ping, resources/list, and resources/read are implemented. There is no render, install, or publish tool.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "202": {
            "description": "Notification acknowledged (no body)."
          },
          "400": {
            "description": "Malformed request. JSON problem with code, message, and hint.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error",
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "message",
              "hint"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine error code, e.g. not_found."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the failure."
              },
              "hint": {
                "type": "string",
                "description": "What to do next: which public files or endpoints exist."
              }
            }
          },
          "type": {
            "type": "string",
            "format": "uri",
            "description": "RFC 9457 problem type URI."
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string"
          }
        }
      },
      "Character": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "look",
          "description",
          "notes",
          "preview"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Pack name used in `/illo install {name} character pack`.",
            "examples": [
              "blot",
              "mole"
            ]
          },
          "look": {
            "type": "string",
            "description": "Bundled print look. Packs couple character and look; do not swap styles.",
            "examples": [
              "riso",
              "clay"
            ]
          },
          "description": {
            "type": "string",
            "description": "Short visual description of the mascot (`a <thing>`)."
          },
          "notes": {
            "type": "string",
            "description": "Editorial voice line for the mascot."
          },
          "preview": {
            "type": "string",
            "format": "uri",
            "description": "On-site preview image URL (WebP)."
          }
        }
      },
      "CharacterCatalog": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema_version",
          "site",
          "source_repo",
          "install_phrase_template",
          "characters"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "examples": [
              "1.0"
            ]
          },
          "site": {
            "type": "string",
            "format": "uri"
          },
          "source_repo": {
            "type": "string",
            "format": "uri"
          },
          "install_phrase_template": {
            "type": "string",
            "description": "Replace `{name}` with a pack name from `characters`."
          },
          "characters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Character"
            }
          }
        }
      },
      "CharacterList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema_version",
          "site",
          "count",
          "looks",
          "characters"
        ],
        "properties": {
          "schema_version": {
            "type": "string"
          },
          "site": {
            "type": "string",
            "format": "uri"
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "looks": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Looks represented in this response."
          },
          "characters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Character"
            }
          },
          "install_phrase_template": {
            "type": "string"
          }
        }
      },
      "CharacterRecord": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "look",
          "description",
          "notes",
          "preview",
          "install"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "look": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "preview": {
            "type": "string",
            "format": "uri"
          },
          "install": {
            "type": "string",
            "description": "Exact phrase to give the installed illo skill.",
            "examples": [
              "/illo install mole character pack"
            ]
          }
        }
      },
      "CliPointer": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "product",
          "name",
          "kind",
          "language",
          "repository",
          "path",
          "invoke",
          "npm",
          "pypi",
          "homebrew",
          "description"
        ],
        "properties": {
          "product": {
            "type": "string",
            "const": "illo skill"
          },
          "name": {
            "type": "string",
            "const": "illo.py"
          },
          "kind": {
            "type": "string",
            "const": "agent-skill-engine"
          },
          "language": {
            "type": "string",
            "const": "python"
          },
          "repository": {
            "type": "string",
            "format": "uri"
          },
          "path": {
            "type": "string"
          },
          "invoke": {
            "type": "string"
          },
          "npm": {
            "type": "null",
            "description": "No npm CLI talks to this origin."
          },
          "pypi": {
            "type": "null"
          },
          "homebrew": {
            "type": "null"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "method": {
            "type": "string"
          },
          "params": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "result": {
            "type": "object",
            "additionalProperties": true
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    }
  },
  "x-illo-surfaces": {
    "renders_images": false,
    "accounts": false,
    "oauth": false,
    "webhooks": false,
    "graphql": false,
    "commerce": false,
    "mcp": "catalog-lookup-only",
    "cli": "https://illo-skill.com/cli.json"
  }
}