{
  "openapi": "3.1.0",
  "info": {
    "title": "Tools — who-iris",
    "version": "0.1.0",
    "description": "The call contracts of the harness's Tools, one operation per Tool, generated from the Tool nodes (`schemas/tools/tool.ts`) so standard API tooling can read them. **No HTTP server serves these paths**: each Tool is reached as its `x-invoke` says — a command line, an MCP tool, or an in-process call. Tags are the skills each Tool satisfies."
  },
  "servers": [],
  "tags": [
    {
      "name": "graph-rendering"
    },
    {
      "name": "iris-cdn-exporter"
    },
    {
      "name": "iris-dspace"
    },
    {
      "name": "translation-manager"
    }
  ],
  "paths": {
    "/tools/ci-iris-cdn": {
      "post": {
        "operationId": "ci-iris-cdn",
        "summary": "Run the IRIS CDN export",
        "description": "Dispatch `iris-cdn.yml`: the nightly change ingest or the weekly reconciliation of the IRIS CDN (`scripts/iris-cdn/run.ts`), then verify the signed release. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "iris-cdn-exporter"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "ci-iris-cdn/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/who-iris/tools/ci-iris-cdn.jsonld",
        "x-invoke": {
          "shell": "gh workflow run iris-cdn.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "iris-cdn-exporter"
        ],
        "x-selection": {
          "when": "Running the IRIS CDN nightly ingest or reconciliation on demand instead of waiting for its schedule. Pass the mode with `-f mode=nightly` or `-f mode=reconcile`.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-iris-cover-pdfs": {
      "post": {
        "operationId": "ci-iris-cover-pdfs",
        "summary": "Fetch IRIS cover PDFs",
        "description": "Dispatch `iris-cover-pdfs.yml`: fetch the PDFs the replica's home page references (`scripts/iris-covers/fetch-referenced-pdfs.py`) and render their cover previews (`scripts/iris-covers/render-previews.py`). Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "iris-dspace"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "ci-iris-cover-pdfs/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/who-iris/tools/ci-iris-cover-pdfs.jsonld",
        "x-invoke": {
          "shell": "gh workflow run iris-cover-pdfs.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "iris-dspace"
        ],
        "x-selection": {
          "when": "Refreshing the replica's cover previews on demand. Pass `-f only=<slugs>` to limit it to some items.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A CI run on GitHub's runners."
        }
      }
    },
    "/tools/iris-pages": {
      "post": {
        "operationId": "iris-pages",
        "summary": "who-iris catalogue and docs pages",
        "description": "Render who-iris's docs pages, the catalogue visualiser at its declared route (what the catalogue knows, and what it records that it does not know), the library's withheld list, and the IRIS replica's home page.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "iris-pages/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built (the tree `compose-docs --shell` wrote): write only the catalogue page into it, at its route in who-iris's own site, plus a forwarding page at the declared route. A site build passes it (`visualiser-writers.ts`)."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The replica's home page at `site/index.html` (and its translations), the docs under `docs/`, and the catalogue page under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/who-iris/tools/iris-pages.jsonld",
        "x-invoke": {
          "shell": "bun run cat iris:pages"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/translation-qa-prune": {
      "post": {
        "operationId": "translation-qa-prune",
        "summary": "Prune round-trip rulings of removed strings",
        "description": "Drop the translation-semantic-roundtrip rulings of strings the catalogues no longer hold, and renumber the rest to catalogue order. Rulings are paired with strings by the hash of their msgid, so removing strings invalidates none and needs no agent re-run; this is the upkeep that follows. It only drops or renumbers: a verdict is never changed or invented, and a ruling for a string the ref's history never held (one recorded ahead of its PR) is kept.",
        "tags": [
          "translation-manager"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "translation-qa-prune/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "write": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Apply the change to test/attestations/translation-qa/. Absent, it is a dry run that prints each dropped ruling and the renumbered spans."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "Whose catalogues decide what was removed. Default origin/main: the state branch serves main and every branch, so a ruling goes only once main no longer holds its string."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "attestations": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "With --write, the rewritten `test/attestations/translation-qa/<catalogue>.<locale>.attestations.json`, to be pushed to `cat/who-iris/attestations`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/who-iris/tools/translation-qa-prune.jsonld",
        "x-invoke": {
          "shell": "bun run cat translation-qa:prune"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": false
        },
        "x-satisfies": [
          "translation-manager"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Branch": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[A-Za-z0-9][A-Za-z0-9._/-]*$",
        "description": "A git branch name",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Branch"
      },
      "Flag": {
        "type": "boolean",
        "description": "A boolean switch — projects to a bare flag, with no value word",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag"
      },
      "RepoFullName": {
        "type": "string",
        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*\\/[A-Za-z0-9][A-Za-z0-9._-]*$",
        "description": "A forge repository's full name, owner/name",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoFullName"
      },
      "RepoPath": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[A-Za-z0-9._][A-Za-z0-9._/-]*$",
        "description": "A path relative to the repository root. No `..` segments.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath"
      },
      "Text": {
        "type": "string",
        "minLength": 1,
        "maxLength": 400,
        "description": "A short single-line human string. Not admissible as a command-line argument.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text"
      }
    }
  }
}
