{
  "openapi": "3.1.0",
  "info": {
    "title": "Tools — smart-base",
    "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": "classify-and-code-content"
    },
    {
      "name": "dak-postprocessing"
    },
    {
      "name": "dak-preprocessing"
    },
    {
      "name": "graph-rendering"
    },
    {
      "name": "ig-artifact-ingestion"
    },
    {
      "name": "ig-publisher-fork"
    },
    {
      "name": "l4-application-run-local"
    },
    {
      "name": "publish-extracted-statements"
    },
    {
      "name": "recommendation-candidates"
    },
    {
      "name": "recommendation-scenarios"
    },
    {
      "name": "smart-base-tools"
    },
    {
      "name": "transcription-verbatim"
    }
  ],
  "paths": {
    "/tools/bpmn-graphviz-layout": {
      "post": {
        "operationId": "bpmn-graphviz-layout",
        "summary": "BPMN → Diagram Interchange, laid out by Graphviz",
        "description": "Lay out a BPMN that carries no Diagram Interchange (`bpmn_to_svg.py` beside this file, moved from `.github/skills/bpmn_layout/` by bean folio-assistant-tgaj): one Graphviz cluster per participant, the coordinates written back into the BPMN as `<bpmndi:BPMNDiagram>`, and Graphviz's own SVG. cat-harness-tools' `render:bpmn` draws only the DI a file already has (bpmn-js does not lay out), so this is the step before it for a DAK process written, or imported, without one.",
        "tags": [
          "smart-base-tools"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "bpmn-graphviz-layout/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bpmn": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A BPMN 2.0 file, with or without DI."
                  }
                },
                "required": [
                  "bpmn"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bpmn": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The BPMN with a Graphviz-placed `<bpmndi:BPMNDiagram>` (`--bpmn`)."
                    },
                    "svg": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "Graphviz's drawing (`--svg`); not bpmn-js's, so not the published picture."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/bpmn-graphviz-layout.jsonld",
        "x-invoke": {
          "shell": "python3 smart-base/L2-bpmn/tools/bpmn-graphviz-layout/bpmn_to_svg.py <file.bpmn> [--bpmn <out.bpmn>] [--svg <out.svg>] [--dot <out.dot>]"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "python3",
            "graphviz"
          ],
          "network": false
        },
        "x-satisfies": [
          "smart-base-tools"
        ],
        "x-selection": {
          "when": "A BPMN has no Diagram Interchange, so `render:bpmn` would draw it blank, and a first layout is wanted before an author tidies it (`bpmn:detangle`).",
          "limits": "A first layout, not the finished one: it does not meet `bpmn-authoring`'s readability rules (fixed task size, label placement, lane order); run `bun run cat bpmn:detangle --write` and look at `render:bpmn`'s picture after it. It parses with the standard library's ElementTree, so it is for files an author holds, not untrusted input.",
          "cost": "Seconds; needs Graphviz `dot` on the PATH."
        }
      }
    },
    "/tools/bpmn-to-fsh": {
      "post": {
        "operationId": "bpmn-to-fsh",
        "summary": "BPMN → FHIR Shorthand",
        "description": "Derive FSH from a DAK's BPMN business processes (the inverse of the extractors).",
        "tags": [
          "smart-base-tools"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "bpmn-to-fsh/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bpmn": {
                    "$ref": "#/components/schemas/FilesystemPath"
                  }
                },
                "required": [
                  "bpmn"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "fsh": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "Generated FSH, for SUSHI to compile."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/bpmn-to-fsh.jsonld",
        "x-invoke": {
          "shell": "python3 smart-base/scripts/smart-base-transform.py bpmn2fsh <file.bpmn|dir> [-o OUTDIR]"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "python3"
          ],
          "network": false
        },
        "x-satisfies": [
          "smart-base-tools"
        ],
        "x-selection": {
          "when": "An L2 business process is to reach L3 as a computable artefact, not only a picture.",
          "limits": "Requires a `smart-base` checkout at `SMART_BASE_HOME`; without one the capability is ABSENT, not a clean run.",
          "cost": "Seconds, plus the upstream checkout."
        }
      }
    },
    "/tools/bpmn-validate": {
      "post": {
        "operationId": "bpmn-validate",
        "summary": "BPMN structure, vendor namespaces and lane → actor",
        "description": "Check a DAK's BPMN (`validate.ts` beside this file; bean folio-assistant-tgaj, which replaced four Python validators with it): well-formed XML whose root is `<bpmn:definitions>`, no Camunda or Zeebe namespace, no duplicate id, at least one process, no bpmn-moddle (bpmn-js) import warning; every process has a `<laneSet>`, every flow node sits in a lane, and lane ids are unique and valid FSH ids; and every innermost lane names its actor by id: its `partitionElementRef` (a top-level `<bpmn:resource>`), else its own id, matched exactly against the `Instance:` ids of the ActorDefinitions in the IG's FSH (or JSON) and, for a harness process, the role ids of the mounted layers' `scenarios/roles.json`. Never by file name or title. With no file named it reads the declared process directories, `smart-base/**/processes/` and an IG's `input/bpmn/`.",
        "tags": [
          "smart-base-tools"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "bpmn-validate/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bpmn": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The .bpmn files to check; when absent, every .bpmn under the declared process directories (or, with `--changed <ref>`, those the branch changed)."
                  },
                  "fsh": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Directories of ActorDefinition FSH or JSON; default `input/fsh` and `input/resources`."
                  },
                  "roles": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "`scenarios/roles.json` files whose role ids a harness lane may bind; default those of smart-base and the mounted cat-harness, fhir-harness and folio-assistant-core."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "One `✗` line per error and `!` per warning, then a count. Exit 0 no error, 1 an error, 2 nothing to check (not a pass). `--json` prints the findings as data."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/bpmn-validate.jsonld",
        "x-invoke": {
          "shell": "bun run smart-base/L2-bpmn/tools/bpmn-validate/validate.ts [file.bpmn ...] [--root <repo>] [--fsh <dir>]... [--roles <roles.json>]... [--changed <git ref>] [--json] [--verbose]"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "smart-base-tools"
        ],
        "x-selection": {
          "when": "A DAK's business process (L2, BPMN) is added or edited, before review (skill `l2-component-edit-review`, the BPMN row's checker), and on every pull request that changes a `.bpmn`.",
          "limits": "An ActorDefinition a dependency IG declares is found only when its FSH or JSON directory is passed with `--fsh`. Reads lanes, not pools: a participant whose process has no lanes is reported as a process with no laneSet. A lane bound to a harness role is accepted here; whether that role is equipped is cat-harness's `role-model` check (`kg:audit`). A published DAK whose processes are still Visio figures is crosswalked against its personas by `smart-base/scripts/dak-swimlanes.ts` (always on, beside the `web-annex` kind's `dak-swimlanes/v1` validator), not by this Tool. It does not draw the diagram (`render:bpmn` does) or check DI completeness.",
          "cost": "Seconds, no network."
        }
      }
    },
    "/tools/dak-api-hub": {
      "post": {
        "operationId": "dak-api-hub",
        "summary": "DAK API hub",
        "description": "Generate `dak-api.html`, the DAK API's entry page, and the per-artefact `.openapi.json` / `.displays.json` sidecars.",
        "tags": [
          "dak-postprocessing",
          "ig-artifact-ingestion"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "dak-api-hub/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "igOutput": {
                    "$ref": "#/components/schemas/RepoPath"
                  }
                },
                "required": [
                  "igOutput"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "hub": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`dak-api.html`."
                    },
                    "sidecars": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`.openapi.json` and `.displays.json` under `schemas/`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/dak-api-hub.jsonld",
        "x-invoke": {
          "shell": "python3 input/scripts/generate_dak_api_hub.py"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "python3"
          ],
          "network": false
        },
        "x-satisfies": [
          "dak-postprocessing",
          "ig-artifact-ingestion"
        ],
        "x-selection": {
          "when": "The DAK API is to have a reader-facing entry point.",
          "limits": "`dak-api.html` links its schemas to a `schemas/` directory that does not hold the root enumeration schemas. Resolve a sidecar from the index, never by composing the hub's path.",
          "cost": "The largest upstream script; runs inside the publisher container against the full output."
        }
      }
    },
    "/tools/dak-config-from-sushi": {
      "post": {
        "operationId": "dak-config-from-sushi",
        "summary": "sushi-config.yaml → index.config.json#contentTypes.dak",
        "description": "Derive the DAK configuration from `sushi-config.yaml` plus repository and branch context.",
        "tags": [
          "dak-preprocessing"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "dak-config-from-sushi/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sushiConfig": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "`sushi-config.yaml` at the IG root."
                  },
                  "branch": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "Sanitised branch name, for the publication and preview URLs."
                  }
                },
                "required": [
                  "sushiConfig"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "dakConfig": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`index.config.json` (`contentTypes.dak`)."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/dak-config-from-sushi.jsonld",
        "x-invoke": {
          "shell": "python3 input/scripts/generate_dak_from_sushi.py"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "python3"
          ],
          "network": false
        },
        "x-satisfies": [
          "dak-preprocessing"
        ],
        "x-selection": {
          "when": "A DAK repository has no configuration yet, or its branch context has changed.",
          "limits": "Upstream runs it twice, before and after the branch name is sanitised, as an ordering workaround. Run it once, after sanitising.",
          "cost": "Seconds. The whole DAK phase is gated on the file it writes, so a silent failure disables every later step."
        }
      }
    },
    "/tools/dmn-to-html": {
      "post": {
        "operationId": "dmn-to-html",
        "summary": "DMN → HTML",
        "description": "Render each DMN decision table to an HTML fragment for a page, via `dmn2html.xslt` and `dmn.css`.",
        "tags": [
          "dak-preprocessing"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "dmn-to-html/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dmnDir": {
                    "$ref": "#/components/schemas/RepoPath"
                  }
                },
                "required": [
                  "dmnDir"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "html": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "One HTML fragment per decision table."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/dmn-to-html.jsonld",
        "x-invoke": {
          "shell": "python3 input/scripts/transform_dmn.py"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "python3"
          ],
          "network": false
        },
        "x-satisfies": [
          "dak-preprocessing"
        ],
        "x-selection": {
          "when": "A reader needs to see a decision table as a table.",
          "limits": "Its output is HTML, which the JSON-only render contract (`ig-render-jekyll`) does not accept as a representation. Whether the just-the-docs pipeline gets a structured output from it or carries the HTML as an embedded asset is undecided.",
          "cost": "Seconds; needs `lxml` for the XSLT."
        }
      }
    },
    "/tools/dmn-to-questionnaire": {
      "post": {
        "operationId": "dmn-to-questionnaire",
        "summary": "DMN → FHIR Questionnaire",
        "description": "Generate FHIR `Questionnaire` resources from a DAK's DMN decision tables. Authoring, not rendering: the IG Publisher validates and indexes them like any other resource.",
        "tags": [
          "dak-preprocessing"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "dmn-to-questionnaire/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dmnDir": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The DMN source directory, by convention `input/dmn/`."
                  }
                },
                "required": [
                  "dmnDir"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "questionnaires": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The generated `Questionnaire` resources, written beside SUSHI's output."
                    },
                    "generated": {
                      "$ref": "#/components/schemas/Count",
                      "description": "How many were produced. Zero means none only when the DMN directory was found; a missing directory is reported as such."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/dmn-to-questionnaire.jsonld",
        "x-invoke": {
          "shell": "python3 input/scripts/dmn_questionnaire_generator.py"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "python3"
          ],
          "network": false
        },
        "x-satisfies": [
          "dak-preprocessing"
        ],
        "x-selection": {
          "when": "A DAK carries DMN decision tables and the IG is to expose them as answerable questionnaires.",
          "limits": "Reads DMN only: a decision expressed only in prose or CQL is skipped without error. It cannot tell an empty DMN directory from a DAK with no decisions.",
          "cost": "Seconds, no network. It runs before the Publisher, so a failure noticed only downstream costs a build cycle."
        }
      }
    },
    "/tools/extract-dak": {
      "post": {
        "operationId": "extract-dak",
        "summary": "DAK spreadsheets → DMN, PlanDefinitions, CQL, requirements, logical models",
        "description": "Run WHO's `extract_dak.py` in a DAK or IG repository. It reads the DAK template spreadsheets (`input/decision-logic/*.xlsx` via `dt_extractor`, `input/system-requirements/*.xlsx` via `req_extractor`, `input/dictionary/*.xlsx` via `dd_extractor`) and the BPMN, and writes DMN decision tables, CPG recommendation PlanDefinitions with citations, CQL library skeletons, Requirements and logical-model FSH. Per the WHO IG Starter Kit (`l3_decisiontables`, `l3_cql`), an adapted decision or scheduling table is an edited copy of the upstream DAK's spreadsheet, never a parallel format.",
        "tags": [
          "smart-base-tools"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "extract-dak/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dakRepository": {
                    "$ref": "#/components/schemas/FilesystemPath",
                    "description": "The working directory: a DAK or IG repository with `input/decision-logic/`, `input/system-requirements/` and `input/dictionary/` spreadsheets in the DAK template layout."
                  }
                },
                "required": [
                  "dakRepository"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "dmn": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "Decision tables in the DAK DMN format (namespace `https://www.omg.org/spec/DMN/20240513/MODEL/`), each with an `Annotations` and a `Reference(s)` output."
                    },
                    "fsh": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "PlanDefinition, ActivityDefinition, Requirements and logical-model FSH, for SUSHI to compile."
                    },
                    "cql": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "CQL library skeletons, one per decision table, with the definitions already present in `input/cql/` carried over."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/extract-dak.jsonld",
        "x-invoke": {
          "shell": "python3 $SMART_BASE_HOME/input/scripts/extract_dak.py"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "python3"
          ],
          "network": false
        },
        "x-satisfies": [
          "smart-base-tools"
        ],
        "x-selection": {
          "when": "An L2 decision-support, scheduling, requirements or data-dictionary component is created or adapted and the upstream DAK keeps it in the WHO DAK spreadsheet template. Look for that spreadsheet upstream before writing a decision table by hand.",
          "limits": "Reads only the DAK template layout (COVER sheet, per-tab inputs and outputs); a table in any other shape is invisible to it. Requires a `smart-base` checkout at `SMART_BASE_HOME`; without one the capability is ABSENT, not a clean run. Where the upstream DAK repository has its own converters (e.g. `tools/node/processDT*.js` in https://github.com/litlfred/smart-immunizations), use those.",
          "cost": "Seconds to minutes, no network unless `--run-publisher` is passed."
        }
      }
    },
    "/tools/immz-schedule-app-local": {
      "post": {
        "operationId": "immz-schedule-app-local",
        "summary": "Run the immunization schedule-check app locally on a WHO or country IG",
        "description": "Start litlfred/awho-mcp's schedule-check web form on this machine: a HAPI FHIR server in Docker, the WHO SMART Immunizations IG loaded, then optionally a country adaptation IG (its decision-logic tables replace WHO's; its country profile is generated from its `input/l2/dependencies.yaml`), the CQL cache warmed, and the form served. Both listen on 127.0.0.1. Unbuilt IGs are built with SUSHI first, and each Library's CQL is embedded from `input/cql/` as the IG Publisher would. A re-run reuses a server loaded from the same commits; `--down` stops both.",
        "tags": [
          "l4-application-run-local"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "immz-schedule-app-local/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "who-ig": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A WHO SMART Immunizations IG checkout, relative to the working directory (the folder holding the checkouts, e.g. `~/space_cats`)."
                  },
                  "country-ig": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A country adaptation IG checkout, e.g. `smart-immunizations-uganda`, relative to the working directory. Without it the app follows WHO's own schedule."
                  },
                  "fhir-port": {
                    "$ref": "#/components/schemas/Port",
                    "description": "The HAPI port on 127.0.0.1. Default 8081."
                  },
                  "web-port": {
                    "$ref": "#/components/schemas/Port",
                    "description": "The form's port on 127.0.0.1. Default 8090."
                  },
                  "down": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Stop the form and the server."
                  }
                },
                "required": [
                  "who-ig"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "$ref": "#/components/schemas/Url",
                      "description": "The form on 127.0.0.1. It stores nothing; each check is one inline `$apply` round."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/immz-schedule-app-local.jsonld",
        "x-invoke": {
          "shell": "awho-mcp/scripts/local_up.sh --who-ig <dir> [--country-ig <dir>] [--fhir-port <n>] [--web-port <n>] [--down]"
        },
        "x-install": {
          "cli": "git clone https://github.com/litlfred/awho-mcp && cd awho-mcp && python3 -m pip install -e ."
        },
        "x-requires": {
          "runtime": [
            "docker",
            "python3",
            "git"
          ],
          "network": true
        },
        "x-satisfies": [
          "l4-application-run-local"
        ],
        "x-selection": {
          "when": "Trying or demonstrating the immunizations L4 app on a clean IG build, before anything is hosted, on the viewer's own machine.",
          "limits": "Immunizations only (awho-mcp's catalog is the WHO SMART Immunizations IG). One country per server, because a country IG reuses WHO's PlanDefinition ids. Local only: nothing is published and the URL does not open from another machine.",
          "cost": "Docker and about 4 GB of memory. First run: the HAPI image pull, about a minute to load and warm, and a SUSHI build of any unbuilt IG. A re-run on the same commits restarts only the form."
        }
      }
    },
    "/tools/kg-extract-bpmn": {
      "post": {
        "operationId": "kg-extract-bpmn",
        "summary": "BPMN → L2-BPMN knowledge graph",
        "description": "Extract the interior of one BPMN file as the L2-BPMN subgraph (`smart-base/L2-bpmn/schemas/extract-bpmn.ts`, ported from WHO smart-kg `tools/extract-bpmn.mjs`): a `bpmn-definitions` node and its processes, participants, tasks, gateways, events, the `flowsTo`/`messageTo`/`contains` edges between them, and one `performedBy` edge from each pool to the persona its @name matches against the ActorDefinition titles under `--personas`. The output is a graph document whose `@context` is the l2-bpmn context and validates with the engine's `check()`.",
        "tags": [
          "smart-base-tools"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "kg-extract-bpmn/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bpmn": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The .bpmn file to read."
                  },
                  "personas": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A directory of ActorDefinition FSH; a pool's @name is matched against their titles. When absent, every pool -> persona join is recorded unresolved."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where the graph document goes; stdout when absent."
                  }
                },
                "required": [
                  "bpmn"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "graph": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The L2-BPMN graph document (nodes, edges, provenance)."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/kg-extract-bpmn.jsonld",
        "x-invoke": {
          "shell": "npx --prefix smart-base/L1/schemas tsx smart-base/L2-bpmn/schemas/extract-bpmn.ts"
        },
        "x-install": {
          "none": true
        },
        "x-satisfies": [
          "smart-base-tools"
        ],
        "x-selection": {
          "when": "A BPMN file's interior is to be read into the knowledge graph as the L2-BPMN subgraph, with its pool -> persona joins recorded and their resolution status made queryable.",
          "limits": "Parses the OMG BPMN serialisation with regular expressions, as smart-kg did; it reads tasks, sub-processes, exclusive gateways, start/end events, sequence and message flows, and does not interpret diagram layout. A pool -> persona match is exact string equality on a display title, so it does not survive a rename.",
          "cost": "Seconds, no network."
        }
      }
    },
    "/tools/kg-extract-citations": {
      "post": {
        "operationId": "kg-extract-citations",
        "summary": "DMN reference column → L1 citations",
        "description": "Extract the L1 citations from a DMN decision table's reference column (`smart-base/L2-dmn/schemas/extract-citations.ts`, ported from WHO smart-kg `tools/extract-citations.mjs`): one `external-artifact` node for the table and one `citation` node per distinct reference string, each left `unresolved`, with `appearsIn` edges and a coverage report of how many rules cite an L1 source. A citation string is content-addressed in the DAK's namespace, so the same string is one node here and in the L2-DMN graph's `citesSource` edges. The output is an L2 document.",
        "tags": [
          "smart-base-tools"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "kg-extract-citations/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dmn": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The .dmn file to read."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where the graph document goes; also echoed to stdout when absent."
                  }
                },
                "required": [
                  "dmn"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "graph": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The citation graph document (an L2 document: the table as an external artefact and its L1 citation nodes), plus a coverage report on stderr."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/kg-extract-citations.jsonld",
        "x-invoke": {
          "shell": "npx --prefix smart-base/L1/schemas tsx smart-base/L2-dmn/schemas/extract-citations.ts"
        },
        "x-install": {
          "none": true
        },
        "x-satisfies": [
          "smart-base-tools"
        ],
        "x-selection": {
          "when": "A DMN decision table carries an L1 reference column and its citations are to be turned into graph nodes, with coverage counted rather than assumed.",
          "limits": "Copies each reference string verbatim and never resolves it to a publication — resolution is a judgement the schema requires evidence for. '[Add appropriate reference]' is recorded as a placeholder, which coverage counts apart from a blank. The reference column is found by its description.",
          "cost": "Seconds, no network."
        }
      }
    },
    "/tools/kg-extract-dak": {
      "post": {
        "operationId": "kg-extract-dak",
        "summary": "dak.json + FSH tree → L2 DAK component graph",
        "description": "Extract the DAK component layer (L2) from a smart-base-shaped IG (`smart-base/L2/schemas/extract-dak.ts`, ported from WHO smart-kg `tools/extract-dak.mjs`): a `dak` node from dak.json, a `persona` node per ActorDefinition, a `functional`/`non-functional-requirement` node per requirement instance with its `requirement-statement`s, the `hasComponent`/`hasStatement` edges, and the `fulfilledBy` edges that resolve each requirement's `actor = Canonical(...)` against a persona's instance id. Coverage is reported across all nine DAK components, including the empty ones, and files present with no component declaring them are listed. Distinct from the existing `extract-dak` tool (WHO's spreadsheet extractor).",
        "tags": [
          "smart-base-tools"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "kg-extract-dak/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dak": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The dak.json with the kit's metadata (canonicalUrl, title, version)."
                  },
                  "fsh": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The FSH instance tree (e.g. `input/fsh`)."
                  },
                  "bpmnDir": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A BPMN directory; its files are listed as business-process orphans when no component declares them."
                  },
                  "dmnDir": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A DMN directory; its files are listed as decision-logic orphans when no component declares them."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where the graph document goes; stdout when absent."
                  }
                },
                "required": [
                  "dak",
                  "fsh"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "graph": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The L2 DAK component graph document, with coverage across all nine components on stderr."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/kg-extract-dak.jsonld",
        "x-invoke": {
          "shell": "npx --prefix smart-base/L1/schemas tsx smart-base/L2/schemas/extract-dak.ts"
        },
        "x-install": {
          "none": true
        },
        "x-satisfies": [
          "smart-base-tools"
        ],
        "x-selection": {
          "when": "A DAK's component layer is to be read into the knowledge graph from dak.json and the committed FSH instances, with the gaps (components with no instance, files no component declares) made visible.",
          "limits": "Reads the FSH instance tree, not the DAK spreadsheets; it covers personas and requirements, the components the estate commits as instances. Kit membership is inferred from presence in the input tree, since dak.json declares no component arrays. The `fulfilledBy` join resolves by canonical reference and does not depend on a display title.",
          "cost": "Seconds, no network."
        }
      }
    },
    "/tools/kg-extract-dmn": {
      "post": {
        "operationId": "kg-extract-dmn",
        "summary": "DMN → L2-DMN knowledge graph",
        "description": "Extract the interior of one DMN decision table as the L2-DMN subgraph (`smart-base/L2-dmn/schemas/extract-dmn.ts`, ported from WHO smart-kg `tools/extract-dmn.mjs`): a `dmn-definitions` node and its decisions, decision tables, input and output clauses and rules, the `reads` edges to the data elements recovered from input expressions, the `citesSource` edges to the L1 citations each rule's reference column names, and the `invokedBy` edge to the BPMN task the `usingTask` href names. Pass `--bpmn` to resolve that task by name instead of recording it unresolved.",
        "tags": [
          "smart-base-tools"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "kg-extract-dmn/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dmn": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The .dmn file to read."
                  },
                  "bpmn": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A BPMN file; the `usingTask` href fragment is matched against its task @name to resolve `invokedBy`."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where the graph document goes; stdout when absent."
                  }
                },
                "required": [
                  "dmn"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "graph": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The L2-DMN graph document. Its `citesSource` edges reach L1 citations minted by kg-extract-citations from the same strings."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/kg-extract-dmn.jsonld",
        "x-invoke": {
          "shell": "npx --prefix smart-base/L1/schemas tsx smart-base/L2-dmn/schemas/extract-dmn.ts"
        },
        "x-install": {
          "none": true
        },
        "x-satisfies": [
          "smart-base-tools"
        ],
        "x-selection": {
          "when": "A DMN decision table's interior is to be read into the knowledge graph as the L2-DMN subgraph, joining its rules to the L1 sources they cite and to the BPMN task that invokes the decision.",
          "limits": "Parses the DMN serialisation with regular expressions, as smart-kg did. A data element recovered from an input expression carries only the name that was referenced, never a definition, and is left unresolved. The reference column is found by its description, and the outputEntry/annotationEntry split is read from the first rule.",
          "cost": "Seconds, no network."
        }
      }
    },
    "/tools/kg-extract-l3": {
      "post": {
        "operationId": "kg-extract-l3",
        "summary": "FHIR IG → L3 knowledge graph",
        "description": "Extract the L3 index from a SMART Guidelines IG's source tree (`smart-base/L3/schemas/extract-l3.ts`, ported from WHO smart-kg `tools/extract-l3.mjs`): one thin node per FHIR artefact (PlanDefinition, ActivityDefinition, Library, Measure, Questionnaire, StructureMap/Definition, ValueSet, CodeSystem, ConceptMap, ActorDefinition, Requirements, CQL) read from FSH, FML and JSON with RuleSets expanded, the real `uses` and `citesSource` canonical references, and the `implementedBy` edges that tie each artefact to the L2 component its Title names by the SOP's id convention. Coverage is reported across every artefact type.",
        "tags": [
          "smart-base-tools"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "kg-extract-l3/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ig": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The IG root (holds `sushi-config.yaml` and `input/`)."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where the graph document goes; stdout when absent."
                  }
                },
                "required": [
                  "ig"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "graph": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The L3 graph document; each node carries the SHA-256 of the file it came from."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/kg-extract-l3.jsonld",
        "x-invoke": {
          "shell": "npx --prefix smart-base/L1/schemas tsx smart-base/L3/schemas/extract-l3.ts"
        },
        "x-install": {
          "none": true
        },
        "x-satisfies": [
          "smart-base-tools"
        ],
        "x-selection": {
          "when": "A built or source IG's FHIR artefacts are to be indexed as the L3 subgraph and tied back to the L2 components and L1 recommendations they implement.",
          "limits": "Reads the FSH/FML/JSON source, not a built package; the L2 joins are the SOP's Title-and-id conventions (no back-pointer extension exists), so they are recorded unresolved with the rule that matched them. Only artefact types with committed instances are modelled; ExampleScenario, TestPlan and TestScript are reported absent.",
          "cost": "Seconds, no network."
        }
      }
    },
    "/tools/l1-extraction-pages": {
      "post": {
        "operationId": "l1-extraction-pages",
        "summary": "L1 extraction viewer: a hub and a page per instance with `l1-extraction` directories",
        "description": "For every visualiser an instance declares with `renderedBy: l1-extraction-pages`, write the hub at `<locale>/<harness>/<id>/` and, with `subgraphs: \"instance\"`, one page per instance that declares an `l1-extraction` directory. Each page shows, from what the files declare: the L1 statements (graph nodes with a `statement`, and an authored L1 source's `recommendations`); the candidate work list's counts, coverage and decisions; each graph document's nodes by type and edges by predicate (L2 scenario candidates included); counts of curation, mapping, vocabulary, exclusions and run context; and a link from every file to its published copy (cat-harness's `library:viz`), when the site has it, and to its source at the pinned commit. A declared directory not on disk is reported UNKNOWN, never zero.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "l1-extraction-pages/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The site being built; pages go under it (cat-harness-tools' `visualiser-writers.ts` passes it). Default: the checkout's site directory."
                  },
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The checkout whose declarations are read. Default: the checkout holding the working directory."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write nothing; exit 1 when a page is stale, missing or orphaned."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Pages written: the hub and one per instance."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/l1-extraction-pages.jsonld",
        "x-invoke": {
          "shell": "bun run smart-base/scripts/gen-l1-extraction-pages.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ],
        "x-selection": {
          "when": "Publishing a site that should show what each L1 extraction holds.",
          "limits": "Validates nothing (`l1-recommendation-candidates` and `l1-recommendation-scenarios` do, on every write) and does not re-render the JSON-LD (the library viewer publishes it).",
          "cost": "Reads each file of each declared directory once."
        }
      }
    },
    "/tools/l1-recommendation-candidates": {
      "post": {
        "operationId": "l1-recommendation-candidates",
        "summary": "L1 guideline → recommendation candidates (L1 3.0)",
        "description": "Find every normative sentence of an ingested `library/` entry (folio-assistant-core's `l1-coverage` markers), flag uncertain readings, and propose the publication's identity. Given an agent's `l1-recommendation-curation/v1`, refuse a non-verbatim statement or an unknown location, and write the recommendations and remarks as an L1 3.0 graph (checked with `L1/schemas/validate.ts`) with coverage and proposed, unsigned exclusions.",
        "tags": [
          "recommendation-candidates"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "l1-recommendation-candidates/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "entry": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "An ingested `library/<id>/` with page-tagged `sections/*.md` and `structure.json`."
                  },
                  "curation": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The agent's decisions per candidate location (`l1-recommendation-curation/v1`). Absent: only the work list is written."
                  }
                },
                "required": [
                  "entry"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "candidates": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`recommendation-candidates.json` — every normative sentence, its hints and its decision; cites the run context."
                    },
                    "graph": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`l1.json` — L1 3.0 publication, recommendation and remark nodes, every one `inferred`."
                    },
                    "exclusions": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`exclusions.proposed.json`, in `l1-coverage`'s shape; none counts until a person signs it."
                    },
                    "warnings": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`extraction-warnings.md` — undecided candidates, unsigned exclusions, statements taken from a layout fragment."
                    },
                    "runContext": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`run-context.json`, cat-harness `folio-run-context/v1`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/l1-recommendation-candidates.jsonld",
        "x-invoke": {
          "shell": "bun run smart-base/L1/scripts/l1-recommendation-candidates.ts --entry <library entry> [--curation <curation.yaml>] --out <dir> [--check]"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "recommendation-candidates"
        ],
        "x-skill-contracts": {
          "recommendation-candidates.input": {
            "$ref": "#/components/schemas/skill.recommendation-candidates.input"
          },
          "recommendation-candidates.output": {
            "$ref": "#/components/schemas/skill.recommendation-candidates.output"
          }
        },
        "x-selection": {
          "when": "A WHO guideline, position paper or handbook has been ingested and its recommendations are to become L1 3.0 nodes — especially one with no `Recommendation N:` labels, where `extract-smart-kg-l1` finds none.",
          "limits": "Finds candidates by marker words only: a recommendation without `should`/`must`/`recommend…` (a table step, an imperative) is invisible to it. The splitter reads a bulleted list or table row as one sentence; the curation's `statement` override narrows it. It decides nothing: with no curation every candidate is `undecided`.",
          "cost": "Seconds, no network."
        }
      }
    },
    "/tools/l1-recommendation-scenarios": {
      "post": {
        "operationId": "l1-recommendation-scenarios",
        "summary": "L1 recommendations → L2 user-scenario candidates",
        "description": "From an agent's `l1-scenario-mapping/v1`, write one smart-kg L2 `user-scenario` candidate per L1 recommendation, joined to a `persona` and a `business-process` by smart-kg L2's existing edges. Reuses the guide's own personas and processes, then smart-base's generic `DAK.Persona.*`; otherwise a glossary candidate or `could-not-determine`, each with a WARNING. Never invents a process.",
        "tags": [
          "recommendation-scenarios"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "l1-recommendation-scenarios/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "l1": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The recommendations: `l1-recommendation-candidates`' L1 3.0 graph, or an authored L1 YAML."
                  },
                  "vocabulary": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The target guide's personas and processes (`l1-scenario-vocabulary/v1`)."
                  },
                  "generic": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "smart-base's generic personas (second rung)."
                  },
                  "mapping": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The agent's persona, process, act, outcome and domain per recommendation, each with a source and a basis."
                  }
                },
                "required": [
                  "l1",
                  "vocabulary",
                  "mapping"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "graph": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`scenario-candidates.l2.json`."
                    },
                    "warnings": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`scenario-warnings.md` — processes not determined, personas that are glossary candidates."
                    },
                    "runContext": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`run-context.json`, cat-harness `folio-run-context/v1`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/l1-recommendation-scenarios.jsonld",
        "x-invoke": {
          "shell": "bun run smart-base/scripts/l1-recommendation-scenarios.ts --l1 <l1.json|yaml> --vocabulary <guide.json> [--generic <generic.json>] --mapping <mapping.yaml> --out <dir> [--check]"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "recommendation-scenarios"
        ],
        "x-skill-contracts": {
          "recommendation-scenarios.input": {
            "$ref": "#/components/schemas/skill.recommendation-scenarios.input"
          },
          "recommendation-scenarios.output": {
            "$ref": "#/components/schemas/skill.recommendation-scenarios.output"
          }
        },
        "x-selection": {
          "when": "Each extracted recommendation is to say who acts on it and during which business process, before any L2 asset is drawn.",
          "limits": "Checks ids against the vocabulary and coverage against the recommendations. Whether a persona or process is the RIGHT one is the agent's judgement, and stays `candidate` until a person reviews it. smart-kg's `user-scenario` has no slot for domain, link source or review status, so those ride on the edges.",
          "cost": "Seconds, no network."
        }
      }
    },
    "/tools/l1-statement-lists": {
      "post": {
        "operationId": "l1-statement-lists",
        "summary": "L1 extraction → statement lists",
        "description": "The smart-base collector for core's `publish-extracted-statements` step: an `l1-extraction` directory's authored L1 sources (`recommendations:` rows) and scenario-candidate graphs (`user-scenario` nodes whose `evidence.location` names a row), written as `folio-extracted-statements/v1` lists, each statement with the library entry its L1 source names and the page it was read from. Core's `statements:pages` then renders them with links to the entry and section.",
        "tags": [
          "publish-extracted-statements"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "l1-statement-lists/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dir": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "An `l1-extraction` directory."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where the lists go."
                  },
                  "instance-root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The instance the evidence locations are relative to; the working directory when absent."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Compare instead of writing: exit 1 when a list is stale."
                  }
                },
                "required": [
                  "dir",
                  "out"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lists": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`<stem>.recommendations.json` per L1 source and `<stem>.scenarios.json` per scenario graph."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/l1-statement-lists.jsonld",
        "x-invoke": {
          "shell": "bun run smart-base/scripts/l1-statement-lists.ts"
        },
        "x-install": {
          "none": true
        },
        "x-satisfies": [
          "publish-extracted-statements"
        ],
        "x-selection": {
          "when": "An L1 extraction's statements are to be published, with links to their sources, in the folio's own pages and the shared viewer.",
          "limits": "An L1 source that names no library entry is refused. A row's page is its first page. A node citing a file that is not an L1 source (a persona citing the mapping) is not a statement and is skipped.",
          "cost": "Seconds, no network."
        }
      }
    },
    "/tools/l1-transcription-verbatim": {
      "post": {
        "operationId": "l1-transcription-verbatim",
        "summary": "Authored L1 → verbatim against transcriptions and image narratives",
        "description": "Check authored L1 (`*.l1.yaml`, the measles pattern) for a source with no usable text layer: each statement must be verbatim in the image narrative (`images.json`) or the `transcription` block it names; every transcription word (digits aside) must be corroborated by the entry's text layer unless listed under `inspectionOnly`; keys must be unique.",
        "tags": [
          "transcription-verbatim"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "l1-transcription-verbatim/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dir": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The directory of authored `*.l1.yaml`; each names its library entry in `graph.source.entry`."
                  }
                },
                "required": [
                  "dir"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "One summary line per file and one `FINDING` line per failure. Exit 0 clean, 1 findings, 2 nothing to check (not a pass)."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/l1-transcription-verbatim.jsonld",
        "x-invoke": {
          "shell": "bun run smart-base/L1/scripts/l1-transcription-verbatim.ts --dir <dir of *.l1.yaml> [--root <repo>]"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "transcription-verbatim"
        ],
        "x-skill-contracts": {
          "transcription-verbatim.input": {
            "$ref": "#/components/schemas/skill.transcription-verbatim.input"
          },
          "transcription-verbatim.output": {
            "$ref": "#/components/schemas/skill.transcription-verbatim.output"
          }
        },
        "x-selection": {
          "when": "The L1 was authored from inspected images or transcriptions because `l1-recommendation-candidates` found no normative sentence in the entry's text layer (a poster, a slide deck).",
          "limits": "Verbatim is checked after NFKC normalisation with private-use glyphs dropped, so digits a text layer maps to private-use code points rest on inspection alone. Whether the transcription reads the picture correctly is the reviewer's call (`bun run cat narratives`).",
          "cost": "Seconds, no network."
        }
      }
    },
    "/tools/smart-fhir-cache-seed": {
      "post": {
        "operationId": "smart-fhir-cache-seed",
        "summary": "Seed the FHIR package cache, with WHO's published site as a source",
        "description": "Run fhir-harness's `fhir-cache-seed-npm` with smart-base's publisher-site rules (`SMART_PUBLISHER_SITE_REPOS`), so `smart.who.int.*` packages can also be read from WHO's published-site repository, each fetch verified against the tarball's own package.json. All other sources and checks are the seeder's.",
        "tags": [
          "ig-publisher-fork"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "smart-fhir-cache-seed/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sushi-config": {
                    "$ref": "#/components/schemas/FilesystemPath",
                    "description": "Seed what this IG pins: its `dependencies:` and the core package for its `fhirVersion`."
                  },
                  "cache": {
                    "$ref": "#/components/schemas/FilesystemPath",
                    "description": "Default `~/.fhir/packages`, which SUSHI and the IG Publisher read."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "installed": {
                      "$ref": "#/components/schemas/Count"
                    },
                    "missing": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Exit 1 when any is missing, each listed with why."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/smart-fhir-cache-seed.jsonld",
        "x-invoke": {
          "shell": "bun run fhir-harness/scripts/fhir-cache-seed-npm.ts --site-repo smart.who.int.=WorldHealthOrganization/smart-html@main [--cache <dir>] [--sushi-config <file>] [--mirror <dir|git-url>] [--template-repo <name=owner/repo>] [--missing-out <file>] [--dry-run] [name#version ...]"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "npm",
            "git"
          ],
          "network": true
        },
        "x-satisfies": [
          "ig-publisher-fork"
        ],
        "x-selection": {
          "when": "Seeding the cache for a WHO SMART IG where packages.fhir.org is unreachable.",
          "limits": "The site rule only adds a source; the seeder's trust checks, exact-version rule and missing list are unchanged.",
          "cost": "As `fhir-cache-seed-npm`, plus one `git ls-remote` and one download per `smart.who.int.*` package."
        }
      }
    },
    "/tools/smart-liquid-variables": {
      "post": {
        "operationId": "smart-liquid-variables",
        "summary": "IG metadata → Liquid variables",
        "description": "Scan the Publisher's `output/` for `{ResourceType}-{id}.json` and emit a Liquid include assigning `smart__<ResourceType>__<id>__<category>__<key>` for each published resource.",
        "tags": [
          "dak-postprocessing"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "smart-liquid-variables/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "igOutput": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The Publisher's `output/`, the script's source of truth."
                  },
                  "igRoot": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Repository root, where `input/` lives. Defaults to `.`."
                  }
                },
                "required": [
                  "igOutput"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "include": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`input/includes/smart.liquid`, copied to `output/smart.liquid`."
                    },
                    "categories": {
                      "$ref": "#/components/schemas/Text",
                      "description": "`url__canonical`, `url__page`, `url__json`, `text__display`, `link__html`, `elements__<key>`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/smart-liquid-variables.jsonld",
        "x-invoke": {
          "shell": "python3 input/scripts/generate_smart_liquid.py"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "python3"
          ],
          "network": false
        },
        "x-satisfies": [
          "dak-postprocessing"
        ],
        "x-selection": {
          "when": "Page content needs to reference a published resource by canonical URL, page URL, download URL or display label without hard-coding it.",
          "limits": "The documentation page it writes, `input/pagecontent/smart.liquid.md`, is only processed by the NEXT build, so the script also writes `output/smart.liquid.html` directly; a surface that takes two builds to converge cannot support an incremental staging loop. Ids are normalised by replacing every non-alphanumeric character with `_`, so ids differing only in punctuation collide into one variable.",
          "cost": "Seconds. Recomputed from scratch on every run; no delta path."
        }
      }
    },
    "/tools/terminology-lookup": {
      "post": {
        "operationId": "terminology-lookup",
        "summary": "Reuse-first terminology and code-list lookup",
        "description": "Look up a concept or code token for a semantic slot across the four reuse-first rungs of the `terminology-coding` methodology: (1) the target guide's `l1-scenario-vocabulary/v1`; (2) smart-base's generic personas (`DAK.Persona.*`), GRADE `code-lists/*.json` and the `guideline-domain` SKOS glossary; (3) local WHO/ILO FSH CodeSystems (`ISCO08`, `CDHIv2`, `CDHIv1`, `CDSCv2`, `KGTerminologySystem`); (4) a proposed `glossary-terms` candidate (`status: \"candidate\"`), or `could-not-determine` for `business-process`.",
        "tags": [
          "classify-and-code-content"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "terminology-lookup/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "slot": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "The slot to code (`condition`, `intervention`, `persona`, `medicine`, `domain`, `business-process`, `recommendation-strength`, `recommendation-direction`, `evidence-certainty`)."
                  },
                  "query": {
                    "$ref": "#/components/schemas/DocId",
                    "description": "The term, identifier or code token to look up."
                  },
                  "vocabulary": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The target guide's personas and business processes (`l1-scenario-vocabulary/v1`), rung 1."
                  },
                  "generic": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "smart-base's generic personas (`l1-scenario-vocabulary/v1`), rung 2."
                  },
                  "scheme": {
                    "$ref": "#/components/schemas/DocId",
                    "description": "Restrict to one scheme (e.g. `guideline-domain`, `ISCO08`, `CDHIv2`, `grade-recommendation-strength`)."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write the result JSON."
                  }
                },
                "required": [
                  "slot",
                  "query"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "Result JSON conforming to `L1/schemas/skills/classify-and-code-content/output.schema.json`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "http://smart.who.int/base/tools/terminology-lookup.jsonld",
        "x-invoke": {
          "shell": "bun run smart-base/scripts/terminology-lookup.ts --slot <slot> --query <query> [--vocabulary <guide.json>] [--generic <generic.json>] [--scheme <scheme>] [--out <out.json>]"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "classify-and-code-content"
        ],
        "x-skill-contracts": {
          "classify-and-code-content.input": {
            "$ref": "#/components/schemas/skill.classify-and-code-content.input"
          },
          "classify-and-code-content.output": {
            "$ref": "#/components/schemas/skill.classify-and-code-content.output"
          }
        },
        "x-selection": {
          "when": "Coding L1 narrative statements or L2 DAK slots (personas, processes, domains, interventions, conditions, medicines, GRADE ratings) reuse-first, per `terminology-coding`.",
          "limits": "Queries local code lists, SKOS glossaries, `l1-scenario-vocabulary/v1` files and FSH CodeSystems, offline. It ranks lexical exact and close matches only and prepares rung-4 candidate records; semantic fit and exclusion sign-off stay human judgements in `classify-and-code-content.bpmn`.",
          "cost": "Milliseconds, offline."
        }
      }
    }
  },
  "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"
      },
      "Count": {
        "type": "integer",
        "minimum": 0,
        "maximum": 1000000000,
        "description": "A non-negative count — how many of something, or how many to show. Zero is a real answer.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count"
      },
      "DocId": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
        "description": "A library document id, e.g. WPR-RDO-2020-003-eng",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/DocId"
      },
      "FilesystemPath": {
        "type": "string",
        "minLength": 1,
        "description": "A filesystem path, possibly outside the repository. Not admissible as a command-line argument.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath"
      },
      "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"
      },
      "Port": {
        "type": "integer",
        "minimum": 0,
        "maximum": 65535,
        "description": "TCP port for a locally bound server; 0 asks the OS for a free one.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Port"
      },
      "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"
      },
      "skill.classify-and-code-content.input": {
        "title": "Classify and Code Content Input",
        "description": "Slot, query token, and optional target-guide or generic vocabulary paths for reuse-first terminology lookup and content coding.",
        "type": "object",
        "required": [
          "slot",
          "query"
        ],
        "properties": {
          "slot": {
            "type": "string",
            "enum": [
              "condition",
              "intervention",
              "persona",
              "medicine",
              "domain",
              "business-process",
              "recommendation-strength",
              "recommendation-direction",
              "evidence-certainty"
            ],
            "description": "The semantic slot being classified and coded, determining the authoritative scheme and reuse-first ladder."
          },
          "query": {
            "type": "string",
            "description": "The concept term, identifier, or code token to look up across the reuse-first precedence rungs."
          },
          "vocabulary": {
            "type": "string",
            "description": "Optional repository path to the target guide's personas and business processes (l1-scenario-vocabulary/v1), Rung 1 of reuse."
          },
          "generic": {
            "type": "string",
            "description": "Optional repository path to smart-base's generic personas (l1-scenario-vocabulary/v1), Rung 2 of reuse."
          },
          "scheme": {
            "type": "string",
            "description": "Optional scheme identifier filter (e.g. guideline-domain, ISCO08, CDHIv2, grade-recommendation-strength)."
          },
          "out": {
            "type": "string",
            "description": "Optional repository path where the lookup result JSON is written."
          }
        },
        "additionalProperties": false
      },
      "skill.classify-and-code-content.output": {
        "title": "Classify and Code Content Output",
        "description": "Ranked terminology lookup hits across the four reuse-first rungs, best SKOS match kind, and either the resolved coding or the candidate/warning to record.",
        "type": "object",
        "required": [
          "slot",
          "query",
          "authorityScheme",
          "bestMatchKind",
          "selectedRung",
          "matches"
        ],
        "properties": {
          "slot": {
            "type": "string",
            "description": "The semantic slot that was queried."
          },
          "query": {
            "type": "string",
            "description": "The query token or concept label that was looked up."
          },
          "authorityScheme": {
            "type": "object",
            "required": [
              "id",
              "title",
              "uri"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "uri": {
                "type": "string"
              },
              "localSources": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": false
          },
          "bestMatchKind": {
            "type": "string",
            "enum": [
              "exactMatch",
              "closeMatch",
              "none"
            ],
            "description": "SKOS mapping precision of the top hit across local and base vocabularies, or none when Rung 4 applies."
          },
          "selectedRung": {
            "type": "string",
            "enum": [
              "rung-1-target-guide",
              "rung-2-smart-base",
              "rung-3-external-standard",
              "rung-4-local-candidate"
            ],
            "description": "The reuse-first precedence rung that settled the lookup."
          },
          "matches": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "rung",
                "scheme",
                "code",
                "label",
                "matchKind",
                "sourcePath"
              ],
              "properties": {
                "rung": {
                  "type": "string",
                  "enum": [
                    "rung-1-target-guide",
                    "rung-2-smart-base",
                    "rung-3-external-standard"
                  ]
                },
                "scheme": {
                  "type": "string"
                },
                "code": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "definition": {
                  "type": "string"
                },
                "matchKind": {
                  "type": "string",
                  "enum": [
                    "exactMatch",
                    "closeMatch"
                  ]
                },
                "uri": {
                  "type": "string"
                },
                "sourcePath": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "candidateToMint": {
            "type": "object",
            "description": "Populated when bestMatchKind is none: either a glossary-terms candidate entry (status: candidate) or could-not-determine for business-process, with its greppable WARNING line.",
            "required": [
              "action",
              "warning"
            ],
            "properties": {
              "action": {
                "type": "string",
                "enum": [
                  "mint-glossary-candidate",
                  "could-not-determine"
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "candidate",
                  "could-not-determine"
                ]
              },
              "term": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "prefLabel": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "const": "candidate"
                  },
                  "source": {
                    "type": "string",
                    "const": "extracted"
                  }
                },
                "additionalProperties": true
              },
              "warning": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "skill.recommendation-candidates.input": {
        "title": "Recommendation Candidates Input",
        "description": "One ingested L1 source to turn into L1 3.0 recommendation nodes. Step 1 of recommendation-extraction, run once per included source.",
        "type": "object",
        "required": [
          "entry"
        ],
        "properties": {
          "entry": {
            "type": "string",
            "description": "An ingested library/<id>/ with page-tagged sections/*.md and structure.json."
          },
          "curation": {
            "type": "string",
            "description": "The agent's decision per candidate location (l1-recommendation-curation/v1). Absent: only the work list is written."
          },
          "out": {
            "type": "string",
            "description": "Where the outputs are written."
          }
        },
        "additionalProperties": false
      },
      "skill.recommendation-candidates.output": {
        "title": "Recommendation Candidates Output",
        "description": "The work list and, once curated, the L1 3.0 graph of one source.",
        "type": "object",
        "required": [
          "candidates",
          "runContext"
        ],
        "properties": {
          "candidates": {
            "type": "string",
            "description": "recommendation-candidates.json: every normative sentence, its hints and its decision."
          },
          "graph": {
            "type": "string",
            "description": "l1.json: the L1 3.0 publication, recommendation and remark nodes, every one inferred. Present once a curation is given."
          },
          "exclusions": {
            "type": "string",
            "description": "exclusions.proposed.json, in l1-coverage's shape; none counts until a person signs it."
          },
          "warnings": {
            "type": "string",
            "description": "extraction-warnings.md: undecided candidates, unsigned exclusions, statements from a layout fragment."
          },
          "runContext": {
            "type": "string",
            "description": "run-context.json, cat-harness folio-run-context/v1."
          }
        },
        "additionalProperties": false
      },
      "skill.recommendation-scenarios.input": {
        "title": "Recommendation Scenarios Input",
        "description": "The L1 recommendations of one source, and what to join them to. Step 2 of recommendation-extraction.",
        "type": "object",
        "required": [
          "l1",
          "vocabulary",
          "mapping"
        ],
        "properties": {
          "l1": {
            "type": "string",
            "description": "The recommendations: recommendation-candidates' L1 3.0 graph, or an authored L1 YAML."
          },
          "vocabulary": {
            "type": "string",
            "description": "The target guide's personas and processes (l1-scenario-vocabulary/v1)."
          },
          "generic": {
            "type": "string",
            "description": "smart-base's generic personas, the second rung of reuse."
          },
          "mapping": {
            "type": "string",
            "description": "The agent's persona, process, act, outcome and domain per recommendation, each with a source and a basis."
          },
          "out": {
            "type": "string",
            "description": "Where the outputs are written."
          }
        },
        "additionalProperties": false
      },
      "skill.recommendation-scenarios.output": {
        "title": "Recommendation Scenarios Output",
        "description": "One smart-kg L2 user-scenario candidate per L1 recommendation.",
        "type": "object",
        "required": [
          "graph",
          "runContext"
        ],
        "properties": {
          "graph": {
            "type": "string",
            "description": "scenario-candidates.l2.json."
          },
          "warnings": {
            "type": "string",
            "description": "scenario-warnings.md: processes not determined, personas that are glossary candidates."
          },
          "runContext": {
            "type": "string",
            "description": "run-context.json, cat-harness folio-run-context/v1."
          }
        },
        "additionalProperties": false
      },
      "skill.transcription-verbatim.input": {
        "title": "Transcription Verbatim Input",
        "description": "Authored L1 for a source with no usable text layer (a poster, a slide deck), to check against the image narratives and transcriptions it names. A step of recommendation-extraction, run when recommendation-candidates found no normative sentence in the entry's text layer.",
        "type": "object",
        "required": [
          "dir"
        ],
        "properties": {
          "dir": {
            "type": "string",
            "description": "The directory of authored *.l1.yaml; each names its library entry in graph.source.entry."
          }
        },
        "additionalProperties": false
      },
      "skill.transcription-verbatim.output": {
        "title": "Transcription Verbatim Output",
        "description": "The verdict on each authored L1 file: every statement verbatim in the image narrative or transcription it names, every transcription word corroborated by the text layer unless listed under inspectionOnly, and unique keys.",
        "type": "object",
        "required": [
          "report"
        ],
        "properties": {
          "report": {
            "type": "string",
            "description": "One summary line per file and one FINDING line per failure. Exit 0 clean, 1 findings, 2 nothing to check (not a pass)."
          }
        },
        "additionalProperties": false
      },
      "Slug": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[a-z0-9][a-z0-9-]*$",
        "description": "A folio slug, e.g. quantum-observable-universe",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Slug"
      },
      "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"
      },
      "Url": {
        "type": "string",
        "format": "uri",
        "description": "An absolute http(s) URL",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Url"
      }
    }
  }
}
