{
  "openapi": "3.1.0",
  "info": {
    "title": "Tools — every layer",
    "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": "adversarial-code-review"
    },
    {
      "name": "agent-memory"
    },
    {
      "name": "archimate-models"
    },
    {
      "name": "asset-extraction"
    },
    {
      "name": "bean-coordination"
    },
    {
      "name": "block-actions"
    },
    {
      "name": "bootstrap-graph-emission"
    },
    {
      "name": "bootstrap-graph-publication"
    },
    {
      "name": "cache-first-ci"
    },
    {
      "name": "ci-health"
    },
    {
      "name": "code-node-review"
    },
    {
      "name": "content-acquisition"
    },
    {
      "name": "content-graph"
    },
    {
      "name": "content-test"
    },
    {
      "name": "content-validate"
    },
    {
      "name": "continual-progress"
    },
    {
      "name": "coordinate"
    },
    {
      "name": "corpus-grep"
    },
    {
      "name": "decision-audit"
    },
    {
      "name": "deployment-auth"
    },
    {
      "name": "diff"
    },
    {
      "name": "directory-conventions"
    },
    {
      "name": "discussion"
    },
    {
      "name": "docs-generation"
    },
    {
      "name": "document-intake"
    },
    {
      "name": "dsa-checksum"
    },
    {
      "name": "dublin-core-renderings"
    },
    {
      "name": "feature-staging"
    },
    {
      "name": "figure-rebuild"
    },
    {
      "name": "filing-dublin-core"
    },
    {
      "name": "folio-init"
    },
    {
      "name": "getting-started"
    },
    {
      "name": "glossary-terms"
    },
    {
      "name": "graph-rendering"
    },
    {
      "name": "harness-tiles"
    },
    {
      "name": "idle-backlog"
    },
    {
      "name": "index-config"
    },
    {
      "name": "initialization-steps"
    },
    {
      "name": "iris-cdn-exporter"
    },
    {
      "name": "iris-dspace"
    },
    {
      "name": "journey-maps"
    },
    {
      "name": "kg-affordances"
    },
    {
      "name": "kg-export"
    },
    {
      "name": "kg-navigation"
    },
    {
      "name": "kg-separation"
    },
    {
      "name": "kg-subgraph-layout"
    },
    {
      "name": "kg-to-portal"
    },
    {
      "name": "kg-viewer"
    },
    {
      "name": "l1-coverage"
    },
    {
      "name": "l1-document-ingestion"
    },
    {
      "name": "library-ingestion"
    },
    {
      "name": "log-message"
    },
    {
      "name": "lsi-indexing"
    },
    {
      "name": "merge-conflict-patterns"
    },
    {
      "name": "merge-queue"
    },
    {
      "name": "mesh-subject-indexing"
    },
    {
      "name": "npm-kg-distribution"
    },
    {
      "name": "ontologist"
    },
    {
      "name": "package-release"
    },
    {
      "name": "pdf-inline-viewer"
    },
    {
      "name": "pending-show"
    },
    {
      "name": "platform-gates"
    },
    {
      "name": "prepare-merge"
    },
    {
      "name": "process-state"
    },
    {
      "name": "public-comment"
    },
    {
      "name": "publish-extracted-statements"
    },
    {
      "name": "publish-verification"
    },
    {
      "name": "qa-reports"
    },
    {
      "name": "ref-stewardship"
    },
    {
      "name": "remote-mount"
    },
    {
      "name": "render-kg-to-cdn"
    },
    {
      "name": "render-logging"
    },
    {
      "name": "repo-conversion"
    },
    {
      "name": "review-comments"
    },
    {
      "name": "review-heatmap"
    },
    {
      "name": "review-log-watch"
    },
    {
      "name": "review-sheet-script"
    },
    {
      "name": "role-model"
    },
    {
      "name": "security"
    },
    {
      "name": "serving-renderings"
    },
    {
      "name": "session-intent"
    },
    {
      "name": "site-presentation-assets"
    },
    {
      "name": "skills-and-tools"
    },
    {
      "name": "staging-review"
    },
    {
      "name": "sub-kg-lifecycle"
    },
    {
      "name": "tabular-metadata"
    },
    {
      "name": "task-authorization"
    },
    {
      "name": "test-engineer"
    },
    {
      "name": "todo-manager"
    },
    {
      "name": "translation-adjudication"
    },
    {
      "name": "translation-candidate-source"
    },
    {
      "name": "translation-manager"
    },
    {
      "name": "translation-refresh"
    },
    {
      "name": "uml-overview"
    },
    {
      "name": "upload-routes"
    },
    {
      "name": "upstream-version-adoption"
    },
    {
      "name": "visual-diff"
    },
    {
      "name": "vocabulary-authority"
    },
    {
      "name": "wireframe-viewport-check"
    },
    {
      "name": "work-context"
    }
  ],
  "paths": {
    "/tools/agent-memory": {
      "post": {
        "operationId": "agent-memory",
        "summary": "Agent memory assembler",
        "description": "Assemble every declared `memory` directory's nodes into each agent's memory, per vendor: Claude Code's `.claude/agent-memory/<agent>/MEMORY.md` (a marked region, injected when the subagent starts) and Antigravity's workspace skill `.agents/skills/<agent>-memory/SKILL.md`. Other vendors (Gemini CLI, Copilot, Codex, Cursor) are not generated.",
        "tags": [
          "agent-memory"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/agent-memory/"
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "memory": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "Each agent's assembled memory file, per vendor."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/agent-memory.jsonld",
        "x-invoke": {
          "shell": "bun run cat agent-memory"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "agent-memory"
        ]
      }
    },
    "/tools/archimate-actors": {
      "post": {
        "operationId": "archimate-actors",
        "summary": "Check that an ArchiMate model's fhir-actor tags point at the IG's FHIR ActorDefinitions",
        "description": "Actors come first: the IG's ActorDefinitions are written from the DAK's personas, and an ArchiMate model only points at them. For one model a layer's `cat-archimate.config.json` names, this reads every element carrying the Archi property `fhir-actor`, whose value is an ActorDefinition's canonical URL, and the IG's ActorDefinitions: FSH `InstanceOf: ActorDefinition` under `input/fsh/`, and FHIR JSON under `fsh-generated/resources/` or `input/resources/`, each canonical being `<sushi-config canonical>/ActorDefinition/<id>` unless its `url` says otherwise. It fails on a value that is not a canonical URL, a tag that names no ActorDefinition, an element kind that cannot be an actor (a data object, a goal), and a type mismatch (a `#person` actor on an application or technology element, a `#system` actor on a business actor or role). It warns about each ActorDefinition no element realizes; `--strict` makes that a failure. `--json` prints element → actors and actor → elements, for page back-links. It never writes an ActorDefinition or any FSH, and never matches boxes to actors by name.",
        "tags": [
          "archimate-models"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/archimate-actors/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root whose ArchiMate model is read."
                  },
                  "model": {
                    "$ref": "#/components/schemas/ArchimateModelId",
                    "description": "The model's id from the config."
                  },
                  "ig": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The IG directory holding `sushi-config.yaml` and `input/fsh/`; absent, the layer root."
                  },
                  "strict": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail, not only warn, when an ActorDefinition is realized by no element of the model."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print the back-links as JSON (element → actors, actor → elements, problems, unrealized) instead of the report."
                  }
                },
                "required": [
                  "instance",
                  "model"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The problems, the unrealized ActorDefinitions and a summary line; with `--json`, the back-links as JSON. Exit 1 on any problem, or on an unrealized actor under `--strict`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/archimate-actors.jsonld",
        "x-invoke": {
          "shell": "bun run cat archimate:actors"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "archimate-models"
        ],
        "x-selection": {
          "when": "In an IG whose systems are drawn in an ArchiMate model, after its ActorDefinitions are written from the DAK personas: when model authors tag boxes `fhir-actor` in Archi, in CI, and before generating pages that link boxes to actors.",
          "limits": "Reads one model per run. Checks pointers only: it never creates an ActorDefinition, and an actor missing from the IG is added there, by hand, from its persona. Reads FSH by pattern, not with SUSHI, so an ActorDefinition made only through a RuleSet is not seen until its JSON is generated.",
          "cost": "One parse of the model and of the IG's FSH; milliseconds. No network, no JVM, no SUSHI."
        }
      }
    },
    "/tools/archimate-blocks": {
      "post": {
        "operationId": "archimate-blocks",
        "summary": "Draw a document's tables and figures from its ArchiMate data, and check the model against the document's relationship rules",
        "description": "For each table a layer's `cat-archimate.config.json` lists under `tables`, rewrites the block's Markdown table from an `archimate-relationship-rules/v1` file (`relationship-rules`: source, relationship, target, note; `relationship-types`: picture, verb, meaning), keeping the caption and footnotes. For each figure under `figures` that names an `svg`, writes the view as SVG (the same drawing as the view's page). For a rules table that names a `model`, reports the rules the model never uses, the relationships no rule covers, the rules ArchiMate's relationship table refuses, and the relationship types the rules use without a meaning. The rules are in charge: nothing is rewritten from the model.",
        "tags": [
          "archimate-models"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/archimate-blocks/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root whose config, models, rules and blocks are read."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write nothing; exit 1 when a block or SVG is not what the data draws."
                  },
                  "strict": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Also exit 1 when the model has relationships no rule covers, or a rule is one ArchiMate does not allow."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "blocks": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The rewritten table blocks and figure SVGs, at the paths the config names; the rules check on stdout."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/archimate-blocks.jsonld",
        "x-invoke": {
          "shell": "bun run cat archimate:blocks"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "archimate-models"
        ],
        "x-selection": {
          "when": "When a document's table or figure restates an ArchiMate model (the element and relationship types it uses, the rules between them, a view): generate it instead of typing it, and run `--check` in CI so it cannot drift.",
          "limits": "Draws relationship tables and view figures only; element-type tables and glossary tables are not covered yet. Checks a relationship's end types only, not derivation chains or viewpoints.",
          "cost": "One parse per model named, one table lookup per relationship; milliseconds. No network, no JVM."
        }
      }
    },
    "/tools/archimate-check": {
      "post": {
        "operationId": "archimate-check",
        "summary": "Check a layer's ArchiMate models against its config",
        "description": "The ArchiMate gate (graph typology `archimate`): every model a layer's `cat-archimate.config.json` names is held, parses (Archi's native XML or its zipped archive), and resolves — every box in every view draws an element the model holds, every relationship's ends are in the model — and no `.archimate` file is held that the config does not name.",
        "tags": [
          "archimate-models"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/archimate-check/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root whose `archimate` directory is checked."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "problems": {
                      "$ref": "#/components/schemas/Text",
                      "description": "One line per problem on stderr, exit 1; or one ✓ line, exit 0."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/archimate-check.jsonld",
        "x-invoke": {
          "shell": "bun run cat archimate:validate"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "archimate-models"
        ],
        "x-selection": {
          "when": "Before publishing a layer's ArchiMate models, and in its CI: a model that will not parse, draws an element it does not hold, or is held without being configured.",
          "limits": "Archi's native format only; the Open Group exchange format is not read yet.",
          "cost": "One parse per model. No network, no JVM."
        }
      }
    },
    "/tools/archimate-crossings": {
      "post": {
        "operationId": "archimate-crossings",
        "summary": "Count the tangles in ArchiMate views: lines crossing lines, and lines through boxes",
        "description": "For each view, as `render-view.ts` draws it, count the pairs of lines that cross and the lines that run through a box they do not connect (groups, and boxes that hold one of the line's ends, excepted). With `--view` it lists each tangle by the boxes it joins; with `--max` it is a gate.",
        "tags": [
          "archimate-models"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/archimate-crossings/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The `.archimate` file (plain XML or Archi's zipped archive)."
                  },
                  "view": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "One view, by its Archi id (`id-<hex>`) or its page slug (e.g. `1-central-health-workforce-registry`). A slug, not free text, so no shell payload can ride on it. Absent: every view in the model."
                  },
                  "max": {
                    "$ref": "#/components/schemas/Count",
                    "description": "Exit 1 if any view has more tangles than this."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print JSON instead of one line per view."
                  }
                },
                "required": [
                  "model"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tangles": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Per view: crossings and lines through a box."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/archimate-crossings.jsonld",
        "x-invoke": {
          "shell": "bun run cat archimate:crossings"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "archimate-models"
        ],
        "x-selection": {
          "when": "Before and after every change to an ArchiMate view, so a change never adds tangles (skill `archimate-models`, \"Untangle every view you touch\").",
          "limits": "Counts the lines as drawn by this harness's renderer, which draws a stale Archi route straight; Archi itself may draw the same view slightly differently.",
          "cost": "Milliseconds per view. No network, no JVM."
        }
      }
    },
    "/tools/archimate-detangle": {
      "post": {
        "operationId": "archimate-detangle",
        "summary": "Lower the tangles in ArchiMate views: re-route lines and swap same-size boxes in a row",
        "description": "Searches for a less tangled drawing of each view: a line may be re-routed straight or orthogonally (an L, or a Z through a free lane between boxes), and two same-size boxes in the same parent and row or column may swap places. A change is kept only if it lowers crossings + lines through boxes + lines drawn on top of each other. Without `--apply` it reports before and after per view; with it, the model is written back in place, only the moved boxes' bounds and the re-routed lines' bendpoints changing.",
        "tags": [
          "archimate-models"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/archimate-detangle/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The `.archimate` file (plain XML or Archi's zipped archive)."
                  },
                  "view": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "One view, by its Archi id (`id-<hex>`) or its page slug (e.g. `1-central-health-workforce-registry`). A slug, not free text, so no shell payload can ride on it. Absent: every view in the model."
                  },
                  "routes-only": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Never move a box; only re-route lines."
                  },
                  "apply": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write the model back in place."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print JSON instead of one line per view."
                  }
                },
                "required": [
                  "model"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Per view: tangles before and after, and the swaps and routes made."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/archimate-detangle.jsonld",
        "x-invoke": {
          "shell": "bun run cat archimate:detangle"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "archimate-models"
        ],
        "x-selection": {
          "when": "After drawing or changing an ArchiMate view, before committing it: run it, look at the drawing, keep what reads better (skill `archimate-models`).",
          "limits": "A greedy search, one line or one swap at a time: it lowers tangles but does not find the best layout, never adds, resizes or regroups boxes, and leaves lines that end on lines, or share both ends with another line, as they are. The author still looks at the result.",
          "cost": "Seconds for a large view (about 8 s for 20 views). No network, no JVM."
        }
      }
    },
    "/tools/archimate-from-glossary": {
      "post": {
        "operationId": "archimate-from-glossary",
        "summary": "ArchiMate model from the glossary",
        "description": "Make an ArchiMate model agree with the instance's folio-glossary/v1 terms whose `focus` is an ArchiMate element: elements matched by their `skosConcept` property (never by name) take the term's prefLabel and definition, a term with no element gets one on no view, and the relationships the terms list are added. A type that disagrees is reported, never changed. A relationship between two linked elements that no term lists is reported, and removed with `--prune` along with the lines that draw it. No box or line is moved. Without `--write` it only reports; `--check` fails when anything would change. `--seed` goes the other way once, and only from an ingested model held under `library/` (`--from`): an authored model is never a source of the glossary.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/archimate-from-glossary/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The instance root holding `glossary/*.glossary.json` and `archimate/cat-archimate.config.json`."
                  },
                  "model": {
                    "$ref": "#/components/schemas/ArchimateModelId",
                    "description": "The model's id in the ArchiMate config. Required except with `--seed --from`."
                  },
                  "write": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write the changes into the model file."
                  },
                  "prune": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Also remove relationships between linked elements that no term lists."
                  },
                  "seed": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Once: give linked terms without a focus the element type and relationships of an INGESTED model (under `library/`). Refused for an authored model."
                  },
                  "from": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "With `--seed`: the ingested model file, under the instance's `library/`."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if the model and the graph disagree."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "model": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The model file, rewritten in place with `--write`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/archimate-from-glossary.jsonld",
        "x-invoke": {
          "shell": "bun run cat archimate:from-glossary"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/archimate-metamodel": {
      "post": {
        "operationId": "archimate-metamodel",
        "summary": "Derive the metamodel an ArchiMate model uses, and check it against ArchiMate's relationship table",
        "description": "For each model a layer's `cat-archimate.config.json` names: the element types it uses, with counts; every (source type, relationship, target type) pattern its relationships follow, with counts and ids; whether ArchiMate's relationship table (Appendix B of ArchiMate 3.2, as Archi holds it, committed as `archimate/schemas/archimate-relationships.json` in the tools layer) allows each pattern; and the placeholder elements, named after their own type, that a hand-drawn metamodel leaves in a model. Prints a report, JSON, Graphviz DOT or a Mermaid class diagram. `archimate-pages` draws the same result on each model's \"Metamodel in use\" page, so the metamodel is derived, never drawn.",
        "tags": [
          "archimate-models"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/archimate-metamodel/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root whose ArchiMate models are read."
                  },
                  "model": {
                    "$ref": "#/components/schemas/ArchimateModelId",
                    "description": "One model's id from the config; absent, every model. Required for `--format dot` and `mmd`."
                  },
                  "format": {
                    "$ref": "#/components/schemas/ArchimateMetamodelFormat",
                    "description": "`text` (default), `json`, `dot` or `mmd`."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Exit 1 when any relationship follows a pattern ArchiMate does not allow. Placeholders are reported, never fatal."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "metamodel": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The report, or the metamodel as `archimate-metamodel/v1` JSON, DOT or Mermaid, on stdout."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/archimate-metamodel.jsonld",
        "x-invoke": {
          "shell": "bun run cat archimate:metamodel"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "archimate-models"
        ],
        "x-selection": {
          "when": "Before publishing an ArchiMate model (process `archimate-publish`, after `archimate-check`), in its CI, and whenever someone asks which element types and relationships a model actually uses — instead of drawing a metamodel view by hand.",
          "limits": "Checks each relationship's type against its ends' types only; it does not check derivation chains, viewpoints or properties. A type the table does not know is reported as not checked, never as refused.",
          "cost": "One parse per model and a table lookup per relationship; milliseconds. No network, no JVM."
        }
      }
    },
    "/tools/archimate-pages": {
      "post": {
        "operationId": "archimate-pages",
        "summary": "Give every ArchiMate view, element and relationship a page and an IRI, and draw every view",
        "description": "Write a JSON-LD node and a thin page for each model a layer's `cat-archimate.config.json` names and for every view, element and relationship in it — keyed by Archi's own ids — plus the normalised model the pages' one loader draws from, and every view drawn as SVG from the model's own bounds and bendpoints in ArchiMate's notation, each box a link to its element. `--out` writes into a site being built — the data at the graph's path, the pages at the route of the visualiser the layer declares for this Tool, `<locale>/<harness>/<id>/`; without it the files go into the graph and `--check` gates them.",
        "tags": [
          "archimate-models"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/archimate-pages/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: the data lands at `<out>/<graph path>/` and the pages at `<out>/<locale>/<harness>/<id>/`, the route of the layer's one visualiser `renderedBy` this Tool (none declared: nothing is written). Absent, they are written into the graph, which must be `served: true`."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Without `--out`: fail if a committed page is missing, stale or orphaned; write nothing."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Pages and view drawings written (or found current)."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/archimate-pages.jsonld",
        "x-invoke": {
          "shell": "bun run cat archimate:pages"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "archimate-models"
        ],
        "x-selection": {
          "when": "A folio's staging or publish build should show its ArchiMate models: run after the document site is built and before the navbar pass.",
          "limits": "Draws the notation, not Archi's icons, custom images or fonts; sketch and canvas views are skipped. Never replaced by Archi's CLI report (skill `archimate-models`).",
          "cost": "Milliseconds per view; four models of 5,809 pages and 131 drawings (~24 MB) take about 1.5 s. No network, no JVM."
        }
      }
    },
    "/tools/auto-docs-viewer": {
      "post": {
        "operationId": "auto-docs-viewer",
        "summary": "Generated index pages",
        "description": "Render index pages for the declared skills, docs and swimlane-glossary directories, one per directory.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/auto-docs-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  },
                  "scope": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "A scoped site build: the comma-separated instances whose pages this writer writes (the IG and the layer it lands on); every other instance's pages are linked on that layer's own site. Passed by the tools layer's `visualiser-writers.ts` (owner, 2026-11-08, Q-SZ-2 \"B\"). Absent: every instance."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/auto-docs-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat auto:docs"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/avatars-css": {
      "post": {
        "operationId": "avatars-css",
        "summary": "Avatar stylesheet",
        "description": "Render the declared avatar nodes — an actor's glyph and colours, including the overlay states — into the stylesheet the site serves.",
        "tags": [
          "site-presentation-assets"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/avatars-css/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Compare against the committed copy and fail if stale, instead of writing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stylesheet": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The generated stylesheet. Never hand-edited."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/avatars-css.jsonld",
        "x-invoke": {
          "shell": "bun run cat avatars:css"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "site-presentation-assets"
        ]
      }
    },
    "/tools/bean-claim-check": {
      "post": {
        "operationId": "bean-claim-check",
        "summary": "Check a bean is free, then claim it on every copy",
        "description": "For one bean: fetch every bean copy, read the last three commits on its file, skip it if another agent committed within the window or its last note is a claim, look for an open PR naming it in every listed repository, and only then set it in-progress with a dated claim note as a plain commit on every copy. A rejected push is fetched, rebased and re-checked, never forced.",
        "tags": [
          "bean-coordination"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/bean-claim-check/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "$ref": "#/components/schemas/BeanId",
                    "description": "The bean, full or short id."
                  },
                  "copy": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A local checkout of a bean copy. Repeat once per copy. Defaults to the current checkout."
                  },
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "A repository whose open PRs are searched for the id. Repeat. Defaults to the copies' repositories."
                  },
                  "minePr": {
                    "$ref": "#/components/schemas/Url",
                    "description": "The link of an open PR that is the caller's own, when resuming a bean it already holds. Every cloud thread's PR has the same author, so without this any open PR naming the bean is a skip."
                  },
                  "as": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "Which agent is asking, by its name in the agents table. Defaults to `cloud`."
                  },
                  "session": {
                    "$ref": "#/components/schemas/Url",
                    "description": "The caller's session link, matched against the `Claude-Session:` trailer so a sibling thread of the same agent is told apart. Defaults to $CLAUDE_SESSION_URL."
                  },
                  "agents": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A JSON file of agents and their commit authors, as in the skill's input schema."
                  },
                  "window": {
                    "$ref": "#/components/schemas/TimeWindow",
                    "description": "Defaults to 24h."
                  },
                  "dryRun": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Check only; report `would-claim` and write nothing."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Emit `definitions.claimCheck` as JSON."
                  }
                },
                "required": [
                  "id"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "check": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "One of claimed, would-claim, skip-recent-commit, skip-claim-note, skip-open-pr, skip-closed or unknown, with the evidence per copy and the open PRs found. Exit 0 for claimed or would-claim, 1 for a skip, 2 for unknown. Unknown is never reported as free. With --json, `definitions.claimCheck` of schemas/skills/bean-drain/output.schema.json."
                    },
                    "result": {
                      "$ref": "#/components/schemas/BeanClaimCheck",
                      "description": "With --json, the check as one `BeanClaimCheck` record: the state, the evidence per copy and the open PRs found. Programs and BPMN gateways read this; people read `check`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/bean-claim-check.jsonld",
        "x-invoke": {
          "shell": "bun run cat beans:claim-check",
          "inProcess": {
            "module": "scripts/bean-claim-check.ts"
          }
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "bean-coordination"
        ],
        "x-selection": {
          "when": "Before any work on a bean, when more than one agent may be draining the same store.",
          "limits": "It sees commits and open PRs, not an agent's intent: an agent that works without committing or opening a PR is invisible until it does. One bean per call. `beans:claim` is the right claim when the store has one copy and no other agents drain it.",
          "cost": "One fetch and one push per copy, and one paged GitHub REST listing of open PRs per repository."
        }
      }
    },
    "/tools/bean-query": {
      "post": {
        "operationId": "bean-query",
        "summary": "Query the beans knowledge graph",
        "description": "Query the beans knowledge graph using named graph analytics or arbitrary SPARQL 1.1.",
        "tags": [
          "todo-manager",
          "bean-coordination"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/bean-query/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "named": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Pre-defined named query (e.g. safe_drain_candidates, actionable_leaves)."
                  },
                  "sparql": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Arbitrary SPARQL 1.1 SELECT query over the bean store."
                  },
                  "format": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Output format: table, json, or ids."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Query results formatted as a table, JSON or IDs, for people to read."
                    },
                    "result": {
                      "$ref": "#/components/schemas/BeanQueryRows",
                      "description": "The rows as one `BeanQueryRows` record, each variable to its value with bean IRIs shortened to ids: `structuredContent.rows` over MCP in every format, and the text itself with format json. Programs and BPMN gateways read this; people read `report`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/bean-query.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "bean_query"
          },
          "inProcess": {
            "module": "src/tools/beans-prime.ts"
          }
        },
        "x-mcp-tools": [
          "bean_query"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "todo-manager",
          "bean-coordination"
        ]
      }
    },
    "/tools/beans-cli": {
      "post": {
        "operationId": "beans-cli",
        "summary": "beans CLI",
        "description": "Read and write the work plan with the `beans` binary. The normal mechanism when it is installed.",
        "tags": [
          "bean-coordination",
          "todo-manager",
          "pending-show",
          "session-intent",
          "continual-progress",
          "idle-backlog"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/beans-cli/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "$ref": "#/components/schemas/BeanId",
                    "description": "The bean to act on; absent for list/create."
                  },
                  "status": {
                    "$ref": "#/components/schemas/BeanStatus"
                  },
                  "body": {
                    "$ref": "#/components/schemas/Markdown"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bean": {
                      "$ref": "#/components/schemas/BeanId",
                      "description": "The bean created or updated."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/beans-cli.jsonld",
        "x-invoke": {
          "shell": "beans"
        },
        "x-install": {
          "cli": "scripts/install-beans.sh"
        },
        "x-requires": {
          "runtime": [
            "go"
          ],
          "network": true
        },
        "x-satisfies": [
          "bean-coordination",
          "todo-manager",
          "pending-show",
          "session-intent",
          "continual-progress",
          "idle-backlog"
        ],
        "x-selection": {
          "when": "The normal case, once `scripts/install-beans.sh` has run. It is the only arm that can answer what an item IS or what it waits on — the fallback gives titles and statuses and nothing else — so any work that involves choosing, claiming or reasoning about an item wants this one.",
          "limits": "Absent on a fresh container until installed, and the install can fail. It is third-party, which is why `.beans.yml` is one of the two configuration paths `check:harness-dirs` cannot remove. When it is missing, `beans-manual` writes the same store in the same layout and this reads back everything it wrote.",
          "cost": "One install step per container, and it wants network to fetch. Nothing at runtime after that."
        }
      }
    },
    "/tools/beans-manual": {
      "post": {
        "operationId": "beans-manual",
        "summary": "beans, by hand",
        "description": "Read and write the same work plan without the CLI — `scripts/beans-fallback.ts`, or editing a bean's front matter directly. Equal standing to the CLI, not a degraded mode.",
        "tags": [
          "bean-coordination",
          "todo-manager",
          "pending-show",
          "session-intent",
          "continual-progress",
          "idle-backlog"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/beans-manual/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "$ref": "#/components/schemas/BeanId"
                  },
                  "status": {
                    "$ref": "#/components/schemas/BeanStatus"
                  },
                  "body": {
                    "$ref": "#/components/schemas/Markdown"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bean": {
                      "$ref": "#/components/schemas/BeanId"
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/beans-manual.jsonld",
        "x-invoke": {
          "shell": "bun run cat beans:fallback",
          "manual": true
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "bean-coordination",
          "todo-manager",
          "pending-show",
          "session-intent",
          "continual-progress",
          "idle-backlog"
        ],
        "x-selection": {
          "when": "When the CLI is not installed and cannot be — not a rare case: a fresh container has no `beans` on PATH. Equal standing, not a degraded mode. An agent that knows only the CLI reads the plan and touches nothing, which is exactly the 2026-09-18 session that completed two merged PRs' worth of durable work UNCLAIMED.",
          "limits": "Titles and statuses only. It cannot say what an item is, what it depends on, or what it waits on — enough to CLAIM and to record, not enough to CHOOSE. Install `beans-cli` when the choice is the point.",
          "cost": "None. The store is files in the repository, so this needs a filesystem and nothing else — which is also why it is the arm that survives an air-gapped or sovereign-compute layer."
        }
      }
    },
    "/tools/bibliography-page": {
      "post": {
        "operationId": "bibliography-page",
        "summary": "Bibliography page",
        "description": "Render every reference in the checkout (each declared `references` directory's folio-reference/v1 nodes and each `catalogue` directory's Dublin Core records) as the bibliography page and one page per sub-graph, each with its BibTeX, CSL-JSON, RIS and Dublin Core JSON-LD exports and a per-reference export, at the route of the visualiser core declares for it.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/bibliography-page/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page or export is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under cat-harness's docs, as a repository's own site build does (`visualiser-writers.ts`)."
                  },
                  "scope": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "A scoped site build: the comma-separated instances whose pages this writer writes (the IG and the layer it lands on); every other instance's pages are linked on that layer's own site. Passed by the tools layer's `visualiser-writers.ts` (owner, 2026-11-08, Q-SZ-2 \"B\"). Absent: every instance."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The bibliography pages and their exports, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/bibliography-page.jsonld",
        "x-invoke": {
          "shell": "bun run cat bibliography:page"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/block-actions": {
      "post": {
        "operationId": "block-actions",
        "summary": "Block edit and feedback links",
        "description": "Each labelled block's links back to where it can be changed: [edit] opens the block's Markdown source in GitHub's editor on `main`, and [feedback] opens a new GitHub issue about the block, from the folio's `.github/ISSUE_TEMPLATE/block-feedback.yml` when it has one (prefilling only the fields it declares: block, section, source, page, url) or as a plain issue whose body carries the same facts. The document build draws these on every block; this Tool prints them as JSON for one block or all. Governed by the `block-actions` skill.",
        "tags": [
          "block-actions"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/block-actions/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio's repository root. Default: the working directory."
                  },
                  "block": {
                    "$ref": "#/components/schemas/NodeId",
                    "description": "One block's label. Absent: every block of every document. A label no block has exits 1."
                  },
                  "github": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "`owner/name` on GitHub. Default `GITHUB_REPOSITORY`, else the checkout's `origin`. None at all exits 2: no links rather than broken ones."
                  },
                  "edit-branch": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch [edit] opens. Default `main`."
                  },
                  "issue-template": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The issue form's file name under `.github/ISSUE_TEMPLATE/`. Default `block-feedback.yml`, used only if the folio has it."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "JSON on stdout: one `{ label, source, section, edit, feedback }` per block. A one-line summary goes to stderr."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/block-actions.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/block-actions.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "block-actions"
        ],
        "x-selection": {
          "when": "A reader, reviewer or agent wants to propose a change to, or give feedback on, one block of a document folio, and needs the link that lands on that block rather than on the repository.",
          "limits": "Builds URLs; it writes nothing to GitHub. Only labelled blocks get links. The issue form's fields are read by a line scan for `id:`, so a form must declare its ids plainly.",
          "cost": "Milliseconds: one walk of the document manifests. No network."
        }
      }
    },
    "/tools/bpmn-checklist": {
      "post": {
        "operationId": "bpmn-checklist",
        "summary": "BPMN checklist projection",
        "description": "Generate, per diagram, a checklist that walks the BPMN as a state machine: each task names the `workflow_complete` call that records it and ends with `next:` by node id; each decision lists its labelled branches (or the DMN that computes it); parallel forks name every branch and joins wait for all; start/end events are entry and exit lines. A rendering, never an authority: it says it is generated, and `--check` fails when one is stale.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/bpmn-checklist/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Write every `<stem>.checklist.md` into this one directory instead. Default: each beside its diagram, in the layer that owns it; the harness site's `assets/workflows/checklists` holds those of the layers below the harness."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Verify instead of write: exit 1 on a stale, missing or orphaned checklist."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "checklists": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "One committed `<stem>.checklist.md` per diagram in every layer, beside its `.bpmn`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/bpmn-checklist.jsonld",
        "x-invoke": {
          "shell": "bun run cat bpmn:checklist"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "docs-generation"
        ],
        "x-selection": {
          "when": "A coding agent needs a process in a form it can follow without reading BPMN XML, or without the engine's MCP server.",
          "limits": "Conditions are the flows' labels or the DMN's id; a condition expression the model does not carry is not reproduced. The engine stays the authority.",
          "cost": "One diagram load per process; no network."
        }
      }
    },
    "/tools/bpmn-engine": {
      "post": {
        "operationId": "bpmn-engine",
        "summary": "BPMN workflow engine",
        "description": "Run a declared BPMN process as an instance: `workflow_start` opens one for a subject, `workflow_next` reports what is enabled, `workflow_complete` records a step or answers a decision (a DMN-computed one from `facts`) and REFUSES a step that is not enabled. State is committed under the work plan, so which edge was taken is a record, not a memory.",
        "tags": [
          "process-state"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness-tools/bpmn-engine/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "process": {
                    "$ref": "#/components/schemas/ProcessId",
                    "description": "The process to run: a diagram's file stem or its `bpmn:process` id."
                  },
                  "node": {
                    "$ref": "#/components/schemas/NodeId",
                    "description": "The step or decision to complete, as `workflow_next` reported it."
                  }
                },
                "required": [
                  "process"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "$ref": "#/components/schemas/NodeId",
                      "description": "What may be worked next, after each call."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness-tools/tools/bpmn-engine.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "workflow_*"
          },
          "inProcess": {
            "module": "src/tools/workflow.ts",
            "register": "registerWorkflowTools"
          }
        },
        "x-mcp-tools": [
          "workflow_complete",
          "workflow_gate",
          "workflow_list",
          "workflow_next",
          "workflow_start"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "process-state"
        ],
        "x-selection": {
          "when": "Work follows a declared process and its order must be enforced and recorded: a step done out of order should be refused, not just discouraged.",
          "limits": "Reached over MCP; an agent without the server can walk the generated checklist (`bpmn-checklist`) by hand, but nothing then refuses a wrong turn.",
          "cost": "One diagram load per call; state is a small committed file."
        }
      }
    },
    "/tools/bpmn-render": {
      "post": {
        "operationId": "bpmn-render",
        "summary": "BPMN diagram rendering",
        "description": "Render each process diagram to SVG for the documentation site. The .bpmn file is the source of truth; the picture is generated from it, so a diagram and its image cannot disagree.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/bpmn-render/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if any committed SVG is stale, instead of writing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "diagrams": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The generated SVG directory. Never hand-edited."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/bpmn-render.jsonld",
        "x-invoke": {
          "shell": "bun run cat render:bpmn"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "chromium"
          ],
          "network": false
        },
        "x-satisfies": [
          "docs-generation"
        ]
      }
    },
    "/tools/build-instance-site": {
      "post": {
        "operationId": "build-instance-site",
        "summary": "Build, check and (on request) publish a layer's own site, or a branches/<branch> preview",
        "description": "From a checkout whose layers arrive by remote mount: mount the pinned closure, install, run the layer's own gates (`--pre`), compose the harness chrome for THIS layer, run its source steps, build with Jekyll at the base path read from the git remote (`/<repo>`, or `/<repo>/branches/<branch>` for a preview), run the post-build steps (mount-instance-docs, pdf-viewer, set-html-lang, publish-id-lookup, rail-standalone-pages), and check that every relative or base-rooted link in every page resolves to a file under the site, reading each page with an HTML parser. Any failing step stops the run; a link that does not resolve means nothing is published. It never decides to publish: only `--publish` does, and then a root publish keeps `branches/` and `_render-log/` on the branch, and a preview replaces only its own `branches/<branch>/`.",
        "tags": [
          "remote-mount"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/build-instance-site/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer checkout (holds `index.config.json`). Default: the working directory."
                  },
                  "instance": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "The declared layer name; must match the checkout's declaration."
                  },
                  "home": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A page that becomes the site's index.md."
                  },
                  "pre": {
                    "$ref": "#/components/schemas/ScriptName",
                    "description": "A package script to run in the checkout first, as `bun run <name>` (repeatable): the layer's own gates. Any non-zero exit stops the build."
                  },
                  "sourceStep": {
                    "$ref": "#/components/schemas/ScriptName",
                    "description": "A package script that writes into the site source, run as `bun run <name> <site source>` (repeatable)."
                  },
                  "siteStep": {
                    "$ref": "#/components/schemas/ScriptName",
                    "description": "A package script that writes finished pages into the BUILT site, run as `bun run <name> <built site>` after Jekyll (repeatable): Jekyll drops `_`-prefixed directories, so a generator whose pages sit under one runs here."
                  },
                  "staging": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "Build (and with --publish, publish) a preview of this branch at branches/<branch>/."
                  },
                  "noMount": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Use the mounts already on disk."
                  },
                  "publish": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Publish after every check passes; needs --remote."
                  },
                  "remote": {
                    "$ref": "#/components/schemas/Url",
                    "description": "The https git URL the caller can push the pages branch to."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "site": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The built site directory, and its base path."
                    },
                    "links": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Pages checked, unresolved links (must be 0), files."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/build-instance-site.jsonld",
        "x-invoke": {
          "shell": "bun run cat site:instance"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git",
            "ruby"
          ],
          "network": true
        },
        "x-satisfies": [
          "remote-mount"
        ],
        "x-selection": {
          "when": "Publishing a layer's site, or a branch preview of it, from an agent or a Routine: the agent-run replacement for a pages workflow.",
          "limits": "Layer sites only. A FHIR IG's site (the IG pipeline layer's `stage-ig-sites`) is not built here yet; it needs the IG's FHIR packages, which some environments cannot reach.",
          "cost": "A full mount, install and Jekyll build: minutes, not seconds. `--no-mount` reuses what is on disk."
        }
      }
    },
    "/tools/c-value-terms": {
      "post": {
        "operationId": "c-value-terms",
        "summary": "Rank candidate glossary terms in prose by C-value",
        "description": "The scoring step of the `automatic-term-extraction` method: count the word n-grams of one or more Markdown or text files (not across punctuation, front matter or code), and rank them by C-value as Frantzi & Ananiadou 1996 define it, so nested multi-word terms are not swamped by the longer phrases that contain them. Tested against the paper's own worked example (Table 2). Every row is a candidate; it writes nothing and promotes nothing.",
        "tags": [
          "glossary-terms",
          "ontologist"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/c-value-terms/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "files": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "One or more Markdown or text files whose prose is read."
                  },
                  "maxLength": {
                    "$ref": "#/components/schemas/Count",
                    "description": "Longest n-gram, in words; 1 or more. Default 5."
                  },
                  "minFreq": {
                    "$ref": "#/components/schemas/Count",
                    "description": "Fewest occurrences an n-gram needs to be scored. Default 3, the paper's cut-off; 1 or more."
                  },
                  "top": {
                    "$ref": "#/components/schemas/Count",
                    "description": "How many candidates to print; 1 or more. Default 50."
                  },
                  "edgeStopwords": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Drop n-grams that begin or end with a common English function word. Off by default, because the 1996 method has no such filter."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print the candidates as JSON, each with its frequency, nesting counts and C-value."
                  }
                },
                "required": [
                  "files"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "candidates": {
                      "$ref": "#/components/schemas/Text",
                      "description": "A ranked table, or JSON with `status: candidate`, of n-grams with a C-value above 0."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/c-value-terms.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/c-value.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "glossary-terms",
          "ontologist"
        ],
        "x-selection": {
          "when": "A person or agent wants candidate glossary terms from a body of prose, ranked, to review before writing any definitions.",
          "limits": "Statistics only, as the 1996 paper: no part-of-speech filter (the later C-value papers that add one are not held), English word splitting, and no reference corpus. On ordinary prose without --edge-stopwords the top rows are function phrases. A person decides what is a term.",
          "cost": "Milliseconds for a chapter; linear in words times --max-length. No network."
        }
      }
    },
    "/tools/cat-harness-schema": {
      "post": {
        "operationId": "cat-harness-schema",
        "summary": "Layer declaration schema",
        "description": "The zod definition of `<name>.json` — what a layer may declare about itself — and the published JSON Schema generated from it.",
        "tags": [
          "kg-export"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/cat-harness-schema/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "baseUrl": {
                    "$ref": "#/components/schemas/Url",
                    "description": "Publication base; a preview passes its own."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The written JSON Schema."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/cat-harness-schema.jsonld",
        "x-invoke": {
          "shell": "bun run cat kg:schema"
        },
        "x-install": {
          "none": true
        },
        "x-satisfies": [
          "kg-export"
        ]
      }
    },
    "/tools/catalogue-from-references": {
      "post": {
        "operationId": "catalogue-from-references",
        "summary": "Catalogue a library from its bibliography",
        "description": "Write one `folio-dublin-core/v1` record and one `folio-catalogue-node/v1` item per library entry that the source ledger joins to a CSL-JSON reference, into the folio's declared `catalogue` directory, so `gen-library-jsonld` reads the title from the catalogue's `dc.title` instead of falling to the PDF or the slug. The join is exact: a ledger row naming the entry's `structure.json` source file, one reference id, and the same sha256 where both record one. Unjoined entries are reported and left alone. Never touches a node it did not write.",
        "tags": [
          "filing-dublin-core"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/catalogue-from-references/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio instance's root. It must declare a `catalogue` and a `library` directory."
                  },
                  "apply": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write the records and nodes, and remove this tool's stale ones. Without it the run is a dry run."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write nothing. Exit 1 if any record or node on disk differs from what the bibliography gives."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print the plan as JSON."
                  },
                  "baseUrl": {
                    "$ref": "#/components/schemas/Url",
                    "description": "Where the bibliography is published. With `--apply`, writes `catalogue.json` when the catalogue directory has none; without it such a run is refused."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "catalogue": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`<catalogue>/records/<slug>.dc.json` and `<catalogue>/nodes/item-<slug>.json` per joined entry; `catalogue.json` when absent and `--base-url` is given. A summary of joined and left-alone entries goes to stdout."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/catalogue-from-references.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/catalogue-from-references.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "filing-dublin-core"
        ],
        "x-selection": {
          "when": "A folio keeps its bibliography as CSL-JSON and a source ledger, has no catalogue, and its library titles fall to `slug` or the PDF.",
          "limits": "Bibliographic layer only. Every publication gate is written `unknown`: it records what the bibliography says and decides no licence. Entries the ledger does not join to exactly one reference are left alone, never guessed.",
          "cost": "Milliseconds per entry. Reads the bibliography, the ledger and each entry's structure.json; no network."
        }
      }
    },
    "/tools/check-dsa-hash": {
      "post": {
        "operationId": "check-dsa-hash",
        "summary": "Verify Data Sharing Agreement hash, citation, and vocabulary terms",
        "description": "Verify a Data Sharing Agreement (DSA) directory or single version: checks that every JSON-LD term in `agreement.jsonld` and `dcat.jsonld` is defined in the SHA-256-pinned official W3C ODRL 2.2, W3C DCAT 3 (with SPDX 2.2.2 and ADMS), or DCMI Metadata Terms contexts; checks that the ODRL 2.2 Agreement's `uid` is the version's fixed-version URL and its `dcterms:source` cites the DCAT 3 `dcat:Distribution` whose `spdx:checksum` is checked; verifies that the SHA-256 digest of `agreement.md` matches `spdx:checksumValue`; and checks `dcat:previousVersion` and hash distinctness across versions.",
        "tags": [
          "dsa-checksum"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/check-dsa-hash/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dir": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Path to a versioned DSA directory (holding `v1/`, `v2/`, ...) or a single version directory holding `agreement.md`, `dcat.jsonld`, and `agreement.jsonld`. Defaults to `folio-assistant-core/scripts/test-fixtures/dsa`."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verdict": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Per-version verification line (`dcat:version`, `dcat:downloadURL`, `sha256`) on stdout when valid; diagnostic findings on stderr with exit code 1 when any check fails."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/check-dsa-hash.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/check-dsa-hash.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "dsa-checksum"
        ],
        "x-selection": {
          "when": "Verifying a Data Sharing Agreement's checksum, ODRL citation, DCAT 3 record and `dcat:previousVersion` chain, or `adms:status`.",
          "limits": "Checks structural, cryptographic, and vocabulary conformance of `agreement.md`, `dcat.jsonld`, and `agreement.jsonld`; does not evaluate legal prose semantics or sign Verifiable Credentials.",
          "cost": "Local file reads and SHA-256 hashing; runs in milliseconds with no network access."
        }
      }
    },
    "/tools/check-tools": {
      "post": {
        "operationId": "check-tools",
        "summary": "Do the Tool nodes agree with their skills?",
        "description": "Check every Tool node's joins: that each `satisfies` resolves to a real skill and agrees with that skill's declared contract, that every io port names a declared type, and that no argv input has a type able to express a shell payload.",
        "tags": [
          "code-node-review"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/check-tools/"
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The satisfies map, the count of skills with and without a Tool, then the verdict. Exit 0 every join holds, 1 at least one does not. A skill with NO Tool is reported and is NOT a failure: many skills are pure judgement, and failing on them would make the report unusable."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/check-tools.jsonld",
        "x-invoke": {
          "shell": "bun run cat check:tools"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "code-node-review"
        ],
        "x-selection": {
          "when": "Before pushing any change to `tools/`, and as the first of the three audits `code-node-review` lists. It is the check that refuses a contract nobody could satisfy.",
          "limits": "It checks the JOINS, not the truth: a node can pass while its `invoke` names a command that does something else entirely. That is a reviewer's to catch, which is why the skill exists and not a check script alone.",
          "cost": "Seconds. Loads the Tool graph and the skill corpus in-process."
        }
      }
    },
    "/tools/ci-agent-review": {
      "post": {
        "operationId": "ci-agent-review",
        "summary": "Run the agent review",
        "description": "Dispatch the index's `agent-review.yml`: have every configured LLM review a commit on main and file one summary issue. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "adversarial-code-review"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-agent-review/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-agent-review.jsonld",
        "x-invoke": {
          "shell": "gh workflow run agent-review.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "adversarial-code-review"
        ],
        "x-selection": {
          "when": "Running the `agent-review.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-bootstrap-pages": {
      "post": {
        "operationId": "ci-bootstrap-pages",
        "summary": "Publish bootstrap-tools' site",
        "description": "Dispatch bootstrap-tools' `pages.yml`: stage the README site and graph with `scripts/site.ts` and commit them onto `gh-pages`. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "kg-to-portal"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-bootstrap-pages/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-bootstrap-pages.jsonld",
        "x-invoke": {
          "shell": "gh workflow run pages.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "kg-to-portal"
        ],
        "x-selection": {
          "when": "Running the `pages.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-code-quality-gates": {
      "post": {
        "operationId": "ci-code-quality-gates",
        "summary": "Run the platform index's code-quality gates",
        "description": "Dispatch the index's `code-quality-gates.yml`: every gate over the whole mounted index, its cone, bundle cache and judge. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "platform-gates",
          "qa-reports"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-code-quality-gates/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-code-quality-gates.jsonld",
        "x-invoke": {
          "shell": "gh workflow run code-quality-gates.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "platform-gates",
          "qa-reports"
        ],
        "x-selection": {
          "when": "Running the `code-quality-gates.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-docs-site": {
      "post": {
        "operationId": "ci-docs-site",
        "summary": "Build and publish the platform docs site",
        "description": "Dispatch the index's `docs-site.yml`: security gate, regenerate, compose each layer's site, build, export the graph, verify, restore previews, publish to gh-pages, judge the built site. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "render-kg-to-cdn"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-docs-site/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-docs-site.jsonld",
        "x-invoke": {
          "shell": "gh workflow run docs-site.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "render-kg-to-cdn"
        ],
        "x-selection": {
          "when": "Running the `docs-site.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-feature-staging": {
      "post": {
        "operationId": "ci-feature-staging",
        "summary": "Build and publish a branch preview",
        "description": "Dispatch the index's `feature-staging.yml`: build a branch's site and publish it at `branches/<branch>/` on gh-pages. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "feature-staging"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-feature-staging/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-feature-staging.jsonld",
        "x-invoke": {
          "shell": "gh workflow run feature-staging.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "feature-staging"
        ],
        "x-selection": {
          "when": "Running the `feature-staging.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-health": {
      "post": {
        "operationId": "ci-health",
        "summary": "Is CI passing on the default branch?",
        "description": "Report each workflow's state on the default branch, which a checkout cannot see: a red workflow looks exactly like a green one from in here. One API call over the recent run history, not one request per workflow, so it stays inside the unauthenticated 60/hr limit and stays usable at session start.",
        "tags": [
          "ci-health"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-health/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "markdown": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Emit the block the session-start sweep prints. ALWAYS exits 0: the sweep runs it as `if ! …; then`, and a non-zero exit would print the report AND declare it unchecked every time CI is red."
                  },
                  "warn": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Report only, never fail. For a caller that wants the state without a verdict."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Write the markdown report to a file AND keep the exit code — which `--markdown` cannot do, since it always exits 0. Its own flag, so one API call is not spent twice."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "One row per workflow. Five verdicts, not two: green, red, `running`, `superseded` (a red whose workflow file changed after the failing run, so the verdict is against code that no longer exists), and possibly-stale (a red that has not re-run in a week). Three exit codes carry them to a caller that reads no rows: 0 nothing is red, 1 something is, 2 COULD NOT LOOK — the API was unreachable, or `--out` could not be written. A caller must never read 2 as either verdict. `--markdown` and `--warn` always exit 0 by design, so a caller wanting the verdict uses neither."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-health.jsonld",
        "x-invoke": {
          "shell": "bun run cat check:ci-health"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "ci-health"
        ],
        "x-selection": {
          "when": "Before trusting ANY workflow's outcome, and at session start: a workflow's result is invisible from a checkout.",
          "limits": "It reads the DEFAULT BRANCH, so on a PR it describes `main` and not the diff — which is why it is deliberately not one of the `gates`. `GITHUB_TOKEN`/`GH_TOKEN` is used when present; without one a public repo still works and a private one fails. A REFUSED OR FAILING API CALL EXITS 2 AND IS NEVER GREEN: could-not-look must stay distinguishable from looked-and-it-was-fine.",
          "cost": "One HTTP request; fast enough for the session-start sweep, which is why it makes a single call."
        }
      }
    },
    "/tools/ci-iris-cdn": {
      "post": {
        "operationId": "ci-iris-cdn",
        "summary": "Run the IRIS CDN export",
        "description": "Dispatch `iris-cdn.yml`: the nightly change ingest or the weekly reconciliation of the IRIS CDN (`scripts/iris-cdn/run.ts`), then verify the signed release. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "iris-cdn-exporter"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "who-iris/ci-iris-cdn/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/who-iris/tools/ci-iris-cdn.jsonld",
        "x-invoke": {
          "shell": "gh workflow run iris-cdn.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "iris-cdn-exporter"
        ],
        "x-selection": {
          "when": "Running the IRIS CDN nightly ingest or reconciliation on demand instead of waiting for its schedule. Pass the mode with `-f mode=nightly` or `-f mode=reconcile`.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-iris-cover-pdfs": {
      "post": {
        "operationId": "ci-iris-cover-pdfs",
        "summary": "Fetch IRIS cover PDFs",
        "description": "Dispatch `iris-cover-pdfs.yml`: fetch the PDFs the replica's home page references (`scripts/iris-covers/fetch-referenced-pdfs.py`) and render their cover previews (`scripts/iris-covers/render-previews.py`). Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "iris-dspace"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "who-iris/ci-iris-cover-pdfs/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/who-iris/tools/ci-iris-cover-pdfs.jsonld",
        "x-invoke": {
          "shell": "gh workflow run iris-cover-pdfs.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "iris-dspace"
        ],
        "x-selection": {
          "when": "Refreshing the replica's cover previews on demand. Pass `-f only=<slugs>` to limit it to some items.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-merge-main": {
      "post": {
        "operationId": "ci-merge-main",
        "summary": "Merge main into opted-in PRs",
        "description": "Dispatch the index's `merge-main.yml`: merge `main` into each opted-in PR branch when it moves, and comment where it cannot. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "prepare-merge"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-merge-main/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-merge-main.jsonld",
        "x-invoke": {
          "shell": "gh workflow run merge-main.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "prepare-merge"
        ],
        "x-selection": {
          "when": "Running the `merge-main.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-merge-train": {
      "post": {
        "operationId": "ci-merge-train",
        "summary": "Run the merge train",
        "description": "Dispatch the index's `merge-train.yml`: take the queued PRs through the merge train. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "merge-queue"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-merge-train/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-merge-train.jsonld",
        "x-invoke": {
          "shell": "gh workflow run merge-train.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "merge-queue"
        ],
        "x-selection": {
          "when": "Running the `merge-train.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-post-merge-regen": {
      "post": {
        "operationId": "ci-post-merge-regen",
        "summary": "Regenerate derived files after a merge",
        "description": "Dispatch `post-merge-regen.yml` (a layer's caller of `layer-post-merge-regen.yml`, or the index's own): regenerate every derived file from its source on main and open the regeneration PR. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-post-merge-regen/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-post-merge-regen.jsonld",
        "x-invoke": {
          "shell": "gh workflow run post-merge-regen.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "docs-generation"
        ],
        "x-selection": {
          "when": "Running the `post-merge-regen.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-pr-checks": {
      "post": {
        "operationId": "ci-pr-checks",
        "summary": "Run a layer's PR checks",
        "description": "Dispatch the layer's `harness-pr-checks.yml`, which calls the tools layer's reusable `layer-pr-checks.yml` (mount the pinned layers, run every gate of the layer's dependency harness, compare head against base) and, on main, `layer-main-qa.yml`. The workflow is the Tool: its helper scripts (run-gates, compare-gates, main-verdict, …) are its steps. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "cache-first-ci"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-pr-checks/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-pr-checks.jsonld",
        "x-invoke": {
          "shell": "gh workflow run harness-pr-checks.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "cache-first-ci"
        ],
        "x-selection": {
          "when": "Running the `harness-pr-checks.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-pr-tests": {
      "post": {
        "operationId": "ci-pr-tests",
        "summary": "Run the tools layer's own test suite",
        "description": "Dispatch the tools layer's `pr-tests.yml`: the unit and standalone tests, sharded, with the failures compared against main's. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "test-engineer"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-pr-tests/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-pr-tests.jsonld",
        "x-invoke": {
          "shell": "gh workflow run pr-tests.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "test-engineer"
        ],
        "x-selection": {
          "when": "Running the `pr-tests.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-publish-context": {
      "post": {
        "operationId": "ci-publish-context",
        "summary": "Publish a layer's JSON-LD context",
        "description": "Dispatch the layer's `publish-context.yml`, which calls the tools layer's reusable `layer-publish-context.yml` to publish the layer's graph context at the needs it is pinned to. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "kg-export"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-publish-context/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-publish-context.jsonld",
        "x-invoke": {
          "shell": "gh workflow run publish-context.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "kg-export"
        ],
        "x-selection": {
          "when": "Running the `publish-context.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-publish-subgraph-index": {
      "post": {
        "operationId": "ci-publish-subgraph-index",
        "summary": "Publish a layer's sub-graph index package",
        "description": "Dispatch the layer's `publish-subgraph-index.yml`, which calls `layer-publish-subgraph-index.yml` to package and publish the layer's sub-graph index. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "npm-kg-distribution"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-publish-subgraph-index/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-publish-subgraph-index.jsonld",
        "x-invoke": {
          "shell": "gh workflow run publish-subgraph-index.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "npm-kg-distribution"
        ],
        "x-selection": {
          "when": "Running the `publish-subgraph-index.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-repin-train": {
      "post": {
        "operationId": "ci-repin-train",
        "summary": "Run the re-pin train",
        "description": "Dispatch the index's `repin-train.yml`: write the standing-consent layer pins and the lock once, and open or refresh the re-pin train PR. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "upstream-version-adoption"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-repin-train/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-repin-train.jsonld",
        "x-invoke": {
          "shell": "gh workflow run repin-train.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "upstream-version-adoption"
        ],
        "x-selection": {
          "when": "Running the `repin-train.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-staging-publish": {
      "post": {
        "operationId": "ci-staging-publish",
        "summary": "Publish staged previews",
        "description": "Dispatch the index's `staging-publish.yml`: push the previews staged by feature-staging runs to gh-pages. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "ref-stewardship"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-staging-publish/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-staging-publish.jsonld",
        "x-invoke": {
          "shell": "gh workflow run staging-publish.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "ref-stewardship"
        ],
        "x-selection": {
          "when": "Running the `staging-publish.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-standing-repin": {
      "post": {
        "operationId": "ci-standing-repin",
        "summary": "Run a layer's standing re-pin",
        "description": "Dispatch a layer's `standing-repin.yml`: move the pins that carry a standing consent to their newest `main`. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "remote-mount"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-standing-repin/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-standing-repin.jsonld",
        "x-invoke": {
          "shell": "gh workflow run standing-repin.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "remote-mount"
        ],
        "x-selection": {
          "when": "Running the `standing-repin.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/ci-sweeps": {
      "post": {
        "operationId": "ci-sweeps",
        "summary": "Run the 15-minute sweeps",
        "description": "Dispatch the index's `sweeps.yml`: ask each sweep (staging publish, preview verify, re-pin train verdict, cache report) whether there is work, and start the workflow concerned only when there is. Started with the standard GitHub CLI; the run is watched with `gh run watch`.",
        "tags": [
          "publish-verification"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ci-sweeps/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository whose workflow is run. Default: the current one."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to run it on. Default: the default branch."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatched run; its outcome is read with `gh run watch` or `gh run view`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ci-sweeps.jsonld",
        "x-invoke": {
          "shell": "gh workflow run sweeps.yml"
        },
        "x-install": {
          "cli": "gh"
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "publish-verification"
        ],
        "x-selection": {
          "when": "Running the `sweeps.yml` workflow on demand instead of waiting for its trigger, or finding which workflow a CI step belongs to.",
          "limits": "Needs a token that may dispatch workflows (actions: write) on the repository.",
          "cost": "A full CI run on GitHub's runners."
        }
      }
    },
    "/tools/compose-docs": {
      "post": {
        "operationId": "compose-docs",
        "summary": "Compose the site's documentation tree from its declared docs layers",
        "description": "Write the Jekyll source the docs site is built from: the base docs layer, the repository overlay on top (an overlay's `_config.yml` merged, every override reported), and each `composed` layer under its own name. `--staging` keeps staging-only visualisations; `--changed-files` stubs layers a branch does not reach. `--shell` writes the CHROME only — the layers' Jekyll machinery and assets, no page, no layer, and the host's generated includes empty — which an IG repository composes its IG into so its own site wears the main site's chrome.",
        "tags": [
          "harness-tiles"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/compose-docs/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The Jekyll source to write (replaced)."
                  },
                  "staging": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "A local build or a staging preview: staging-only visualisations are included."
                  },
                  "changed-files": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The branch's changed paths, one per line: layers it does not reach are stubbed."
                  },
                  "shell": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "The chrome only: Jekyll machinery and assets, no page and no composed layer; generated includes written empty."
                  }
                },
                "required": [
                  "out"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "files": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Files composed, with every override, merge, withheld file and carried or stubbed layer named."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/compose-docs.jsonld",
        "x-invoke": {
          "shell": "bun run cat compose:docs"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "harness-tiles"
        ]
      }
    },
    "/tools/content-context": {
      "post": {
        "operationId": "content-context",
        "summary": "Content JSON-LD context",
        "description": "Emit the published JSON-LD `@context` that both populations share — authored block siblings and ingested `library/**` nodes reference it by URL — generated from its TypeScript definition rather than hand-kept.",
        "tags": [
          "kg-export"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/content-context/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Compare against the committed copy and fail if stale, instead of writing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "context": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`ns/content/v1.jsonld`, the document served at CONTENT_CONTEXT_URL."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/content-context.jsonld",
        "x-invoke": {
          "shell": "bun run cat jsonld:context"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "kg-export"
        ]
      }
    },
    "/tools/content-graph-analysis": {
      "post": {
        "operationId": "content-graph-analysis",
        "summary": "Editorial content-graph analysis",
        "description": "Build the block- and section-level editorial dependency graph of one paper from its `.ts` manifests and report forward references, cross-chapter coupling, sparse or dense sections and isolated blocks, ranked. Reads `uses[]`/`interprets` only — the editorial relation, never the formal one.",
        "tags": [
          "content-graph"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/content-graph-analysis/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "paper": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "The paper: a directory name under the folio directory, or a path to it. When omitted, the folio's only paper; required when the folio holds several."
                  },
                  "chapter": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "Restrict the analysis to one chapter directory."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Emit the whole graph as JSON on stdout and exit."
                  },
                  "md": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write the report to /tmp/content-graph-report.md."
                  },
                  "visualise": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Render the Graphviz SVGs (needs graphviz)."
                  },
                  "proposals": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write concrete reorganisation proposals to /tmp/content-graph-proposals.md."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The ranked findings, or the graph as JSON with `--json`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/content-graph-analysis.jsonld",
        "x-invoke": {
          "shell": "bun run cat content:graph-analysis"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "python3"
          ],
          "network": false
        },
        "x-satisfies": [
          "content-graph"
        ]
      }
    },
    "/tools/content-graph-build": {
      "post": {
        "operationId": "content-graph-build",
        "summary": "Content graph",
        "description": "Build the content graph under a path and report its edges, separated into the EDITORIAL relation an author maintains and the FORMAL one derived from Lean, never as one number, because a single count lets the formal edges overwrite the editorial signal.",
        "tags": [
          "content-validate"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/content-graph-build/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "targetPath": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Content root to walk; defaults to the folio's `content/`."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Block count, then edge counts reported separately and never summed: EDITORIAL (`uses[]`, `interprets` — author-maintained) and FORMAL (derived from `lean.ref`). The formal line distinguishes `0` from `cache ABSENT`, so an unavailable formal graph cannot be read as a graph with no formal edges."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/content-graph-build.jsonld",
        "x-invoke": {
          "shell": "bun run cat content:graph"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "content-validate"
        ],
        "x-skill-contracts": {
          "content-validate.input": {
            "$ref": "#/components/schemas/skill.content-validate.input"
          },
          "content-validate.output": {
            "$ref": "#/components/schemas/skill.content-validate.output"
          }
        }
      }
    },
    "/tools/content-graph-uml": {
      "post": {
        "operationId": "content-graph-uml",
        "summary": "A paper's block graph as UML",
        "description": "Draw a paper's block graph from buildContentGraph: chapters as packages, editorial edges (uses / interprets) solid and formal Lean edges (type / value) dashed purple, never one derived from the other, and each block filled by its formalization status from proof-objects.json when given. One diagram for the paper and one per chapter, each in portrait and landscape, stamped with its source's hash. Run from a folio: the platform carries no paper.",
        "tags": [
          "graph-rendering",
          "content-graph"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/content-graph-uml/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio's content directory, where the block manifests are."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write the .puml files and their SVGs."
                  },
                  "status": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "proof-objects.json, for status fills. Without it every block is drawn unfilled."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a diagram or SVG is stale or orphaned, instead of writing. Needs no Java."
                  }
                },
                "required": [
                  "root",
                  "out"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "diagrams": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "content-graph.puml and content-graph/<chapter>.puml, with portrait and landscape SVGs beside them."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/content-graph-uml.jsonld",
        "x-invoke": {
          "shell": "bun run cat content:graph:uml"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering",
          "content-graph"
        ]
      }
    },
    "/tools/context-prefixes": {
      "post": {
        "operationId": "context-prefixes",
        "summary": "JSON-LD content-key check",
        "description": "Check every committed JSON-LD document that names the content context, or a layer's own generated context: every plain key is a declared term (never descending into an `@json` value), and no file path sits under an `@id`-coerced term. An empty corpus is a finding, never a clean run. Prefixes are checked by `jsonld:contexts --check`.",
        "tags": [
          "kg-export"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/context-prefixes/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Emit both reports as JSON instead of the console summary."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Console (or JSON) report; exit 1 on an undeclared key, a path under an `@id` term, or an empty corpus."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/context-prefixes.jsonld",
        "x-invoke": {
          "shell": "bun run cat check:content-keys"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "kg-export"
        ]
      }
    },
    "/tools/corpus-search": {
      "post": {
        "operationId": "corpus-search",
        "summary": "Search the corpus and follow the graph",
        "description": "Seed lexically over the authored folio and every declared library, then expand along graph edges, labelling each hit MATCHED or REACHED and by which edge. Counts are split authored vs ingested, and a root that exists but holds no graph nodes is reported rather than read as an empty answer.",
        "tags": [
          "corpus-grep"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/corpus-search/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Words to seed on. Seeding is lexical, so a short phrase works; a long query no node contains seeds nothing."
                  },
                  "hops": {
                    "$ref": "#/components/schemas/Count",
                    "description": "Expansion depth, 0-4 (default 1). 0 is a plain lexical search."
                  },
                  "direction": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "`out`, `in` or `both` (default)."
                  },
                  "provenance": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "`authored` or `ingested`: restricts the seeds, not the expansion."
                  },
                  "searchText": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Also seed on companion Markdown bodies."
                  },
                  "limit": {
                    "$ref": "#/components/schemas/Count",
                    "description": "Seed cap before expansion (default 20)."
                  }
                },
                "required": [
                  "query"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "JSON: summary, emptyRoots, dangling, and hits each carrying a `why`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/corpus-search.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "corpus_search"
          },
          "inProcess": {
            "module": "src/tools/graph.ts"
          }
        },
        "x-mcp-tools": [
          "corpus_search"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "corpus-grep"
        ]
      }
    },
    "/tools/declaration-resolution": {
      "post": {
        "operationId": "declaration-resolution",
        "summary": "Every path a declaration names resolves — directories, assets, visualisers, needs",
        "description": "Read every layer declaration in the checkout and resolve what it names: `directories` (and those declared from within) through `check:declared-dirs`, `assets` through `check:declared-assets`, `visualisers[].renderedBy` through `check:visualiser-routes`, `needs` through the instance-graph resolver, and `visualisers[].coversKinds` against the graph typologies registered IN THIS CHECKOUT — its own and those a mounted layer contributes, read from the checkout under inspection rather than from where the harness module sits. A declaration that does not parse is a finding. One verdict per layer and field, naming the gate that decided it. Exit 0 every reference resolves, 1 one does not, 2 could not determine; a certain finding is reported before anything undetermined.",
        "tags": [
          "kg-separation",
          "kg-affordances"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/declaration-resolution/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The checkout to check; the script re-runs itself there, so kinds are read from it. Default: the working directory."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print the report as JSON."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "findings": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Unresolved references per layer and field, and what could not be determined; entries examined per field."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/declaration-resolution.jsonld",
        "x-invoke": {
          "shell": "bun run cat check:declaration-resolution"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "kg-separation",
          "kg-affordances"
        ]
      }
    },
    "/tools/diig-phases-svg": {
      "post": {
        "operationId": "diig-phases-svg",
        "summary": "DIIG phases, steps and resources chart",
        "description": "Draw a DIIG \"phases, steps and resources\" chart as SVG from `diig-phases-figure/v1` data on a who-iris library entry (DIIG Fig. 1.1.1, or a handbook's republished version such as the product catalogue handbook's Fig. 4), or from a folio's `diig-phases-adaptation/v1` file that adds its own tiles and marks itself \"(this document)\". Every label comes from the data; tiles link to their library entry or glossary concept.",
        "tags": [
          "figure-rebuild"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/diig-phases-svg/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "figure-or-adaptation": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A diig-phases-figure/v1 file, or a diig-phases-adaptation/v1 file whose `adapts` is a repository-root path to one."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write the SVG; stdout when absent."
                  }
                },
                "required": [
                  "figure-or-adaptation"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "svg": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The chart, with text as SVG text, one `<g id=\"tile-<resource>\">` per tile."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/diig-phases-svg.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/diig-phases-svg.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "figure-rebuild"
        ],
        "x-selection": {
          "when": "A folio shows the DIIG phases chart (every Digital Transformation Handbook does) and should draw it from the one transcription instead of a picture or a hand-kept copy.",
          "limits": "Draws the seven-row DIIG layout only. Whether the transcription matches the published figure is a person's review of the data.",
          "cost": "Reads one or two JSON files; no network."
        }
      }
    },
    "/tools/discuss": {
      "post": {
        "operationId": "discuss",
        "summary": "discussion",
        "description": "Put a question to a person or a sibling agent and receive an answer, to determine which harness this repository should become and which repositories are read from and written to. The two facts no file holds.",
        "tags": [
          "discussion"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/discuss/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "question": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The question as put, with its candidates named. One question where one will do."
                  },
                  "askedOf": {
                    "$ref": "#/components/schemas/Text",
                    "description": "`person` or `agent` — symmetric participants, recorded because the answers are evidence of different weight."
                  }
                },
                "required": [
                  "question",
                  "askedOf"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "answer": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The reply as received. Absent is a real result: it routes to `outcome: unsettled`, never to a guess."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/discuss.jsonld",
        "x-invoke": {
          "manual": true
        },
        "x-install": {
          "none": true
        },
        "x-requires": {},
        "x-satisfies": [
          "discussion"
        ],
        "x-selection": {
          "when": "A fact is needed that no file in reach holds — which harness, or which repositories. Narrow the candidates from context first; a repository already carrying `cat-harness/cat-harness.json` is not a blank slate, and a question the agent could have answered itself wastes the one it is entitled to.",
          "limits": "It cannot manufacture an answer. A participant may decline, and that is `outcome: unsettled` with what is still open — not an error and not a default. An agent that reaches for a documented default because nobody replied has produced a guess.",
          "cost": "One round trip through a person's attention, which is the most expensive input in the system and the reason the skill's rule is to ask once."
        }
      }
    },
    "/tools/document-kinds-viewer": {
      "post": {
        "operationId": "document-kinds-viewer",
        "summary": "Document kinds viewer",
        "description": "Render each declared document-kinds directory: every kind's structure, sections and sources, one page per subject layer.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/document-kinds-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/document-kinds-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat document-kinds:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/drain-queue": {
      "post": {
        "operationId": "drain-queue",
        "summary": "Build a bean drain queue",
        "description": "Read every bean copy, keep the drainable open beans (task, bug, feature in todo or in-progress, not blocked, not owner-held), group them by the owner already working in that area, mark the ones another agent touched within the window as skip, and list everything left out with its reason and every bean whose copies disagree. The newest updated_at wins where copies disagree.",
        "tags": [
          "bean-coordination",
          "idle-backlog"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/drain-queue/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "copy": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A local checkout of a bean copy, fetched by the tool to its bean ref. Repeat once per copy. Defaults to the current checkout."
                  },
                  "holdings": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A JSON file mapping each owner to the bean ids it holds (`holdings` in the skill's input schema)."
                  },
                  "agents": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A JSON file of the agents and their commit authors (`agents` in the skill's input schema). Defaults to the table in the bean-drain skill."
                  },
                  "window": {
                    "$ref": "#/components/schemas/TimeWindow",
                    "description": "Another agent's commit within this window marks a bean skip. Defaults to 24h."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Emit the queue as JSON matching `definitions.queue`, instead of Markdown."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "queue": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "The queue: sources with the tip each was read at, one section per owner in priority order, the spare pool, the excluded beans with reasons, and the copies that disagree. With --json, the same as `definitions.queue` of schemas/skills/bean-drain/output.schema.json. A copy that cannot be fetched is an error, never an empty queue."
                    },
                    "result": {
                      "$ref": "#/components/schemas/DrainQueue",
                      "description": "With --json, the queue as one `DrainQueue` record: sources, owner sections in priority order, the spare pool, exclusions and disagreeing copies. Programs read this; people read `queue`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/drain-queue.jsonld",
        "x-invoke": {
          "shell": "bun run cat beans:drain-queue",
          "inProcess": {
            "module": "scripts/drain-queue.ts"
          }
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "bean-coordination",
          "idle-backlog"
        ],
        "x-selection": {
          "when": "Starting or refreshing a drain with more than one agent, or giving an idle drainer its next beans.",
          "limits": "It proposes; it does not claim. Every bean taken from it still goes through `bean-claim-check`. Owner-held is read from the last note's wording and can miss; a person reviewing the queue is the backstop. For one agent picking one bean, `bean-query` named `safe_drain_candidates` is enough.",
          "cost": "One fetch per copy and one `git log` per open bean. No GitHub API calls."
        }
      }
    },
    "/tools/dublin-core-render": {
      "post": {
        "operationId": "dublin-core-render",
        "summary": "Dublin Core renderings",
        "description": "Render every `folio-dublin-core/v1` record a catalogue item names as Dublin Core XML (qualified DC, per DCMI's XML guidelines) and as JSON-LD bound to DCMI Metadata Terms. Both are written into the instance's published root (`<instanceRoot>/dublin-core/<stem>.dc.xml` and `.dc.jsonld`), so the site mount publishes them beside the item pages. Deterministic. `--check` fails on a missing, stale or orphaned rendering. Governed by the `dublin-core-renderings` skill.",
        "tags": [
          "dublin-core-renderings"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/dublin-core-render/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The catalogue instance's root, e.g. an IRIS mirror's directory. It must hold `catalogue/catalogue.json` and declare a directory with `instanceRoot: true`."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write nothing. Exit 1 if any rendering is missing, stale or orphaned."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "renderings": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`<published root>/dublin-core/`: one `.dc.xml` and one `.dc.jsonld` per record. A one-line summary goes to stdout."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/dublin-core-render.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/dc-render.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "dublin-core-renderings"
        ],
        "x-selection": {
          "when": "A catalogue record changed, a catalogue item was added or removed, or the DCMI mapping changed. The renderings must then be regenerated before the gate passes.",
          "limits": "Renders only records a catalogue item names. Fields with no DCMI term keep a minted predicate in JSON-LD and are reduced to their DC element in XML. A non-`dc` schema field cannot appear in XML at all, and is listed in a header comment. Not OAI-PMH `oai_dc`.",
          "cost": "Milliseconds per record. Reads the catalogue nodes and records; no network."
        }
      }
    },
    "/tools/external-schemas-viewer": {
      "post": {
        "operationId": "external-schemas-viewer",
        "summary": "External schemas viewer",
        "description": "Render the declared external schemas, and which of this instance's modules conform to each, as one page.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/external-schemas-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/external-schemas-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat external-schemas:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/feature-staging": {
      "post": {
        "operationId": "feature-staging",
        "summary": "Stage a branch's preview",
        "description": "Publish a branch's built site to `branches/<slug>/` on the publish branch, so a reviewer compares a rendered before and after rather than a description of one. Stamps the commit SHA, and removes the preview when its pull request closes.",
        "tags": [
          "feature-staging"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/feature-staging/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "branch": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to stage; blank stages the current one. On a pull request the workflow fires by itself and needs none of these."
                  },
                  "cleanup_slug": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "DELETION: the `branches/<slug>` to remove, instead of staging anything. For an orphan preview the health sweep reports: its pull request is already closed, so the close event cannot remove it."
                  },
                  "cleanup_confirm": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "The slug again, exactly. Anything else refuses, so a confirmation cannot carry over to a DIFFERENT preview, which a boolean would allow."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "preview": {
                      "$ref": "#/components/schemas/Url",
                      "description": "Where the preview is served."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/feature-staging.jsonld",
        "x-invoke": {
          "shell": "bun run cat site:workflow stage"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": true
        },
        "x-satisfies": [
          "feature-staging"
        ],
        "x-selection": {
          "when": "On a pull request touching the docs, schemas, content or skills it fires on its own — reach for the dispatch arm only to stage a branch that has no open pull request, or to remove a preview the close event could not reach.",
          "limits": "The removal arm is guarded THREE ways: `workflow_dispatch` is available only to an actor with write access; `cleanup_confirm` must repeat the slug exactly; and the removal is preflighted at removal time against the same liveness signals the health sweep uses: `deletion-requires-confirmation` applied to the tool most able to break it. This node does not claim that skill, because implementing the discipline once is not the same as stating it.",
          "cost": "A full site build plus a push to the publish branch. Concurrency is keyed on the branch or the cleanup slug, NOT the shared ref, so two cleanups of different previews do not cancel each other."
        }
      }
    },
    "/tools/figure-coverage": {
      "post": {
        "operationId": "figure-coverage",
        "summary": "Figure coverage and computability",
        "description": "For every figure a source publication declares, report whether the folio built from it has a block and how computable it is: missing, excluded (signed off), picture (a PNG crop), linked (a picture linked to a model view), computable (a diagram, a table or a figure rebuilt by ArchiMate, BPMN, DMN, Mermaid, a class diagram or a generator), or cited (a picture kept on purpose, signed off). Exits non-zero when any declared figure is missing; `--require-computable` also fails on pictures, linked or not.",
        "tags": [
          "figure-rebuild"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/figure-coverage/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "entry": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The L1 library entry directory; its `sections/*.md` give the declared figures, read with cat-harness-tools `declaredFigureCaptions`."
                  },
                  "folio": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio's document directory; every figure, diagram and table block naming a figure is read."
                  },
                  "exclusions": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "JSON `[{figure, scope: block|rebuild, reason, signedOffBy?, signedOffAt?}]`. Without `signedOffBy` an exclusion is a proposal and does not count."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write the report; stdout when absent."
                  }
                },
                "required": [
                  "entry",
                  "folio"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "A `figure-coverage-report/v1` JSON report: declared count, counts per state, one row per figure with its blocks, blocks naming undeclared figures, and problems. A per-figure table goes to stderr."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/figure-coverage.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/figure-coverage.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "figure-rebuild"
        ],
        "x-selection": {
          "when": "A folio has been seeded from an L1 library entry (for example a Digital Transformation Handbook), and somebody needs to know that every figure the publication declares has a block, and which are still only pictures.",
          "limits": "Figure numbers come from block captions and the first line of each block's Markdown. Whether a rebuild is faithful is a person's review, not this check.",
          "cost": "Reads an entry's sections and a folio's blocks; no network."
        }
      }
    },
    "/tools/folio-block-qa-summary": {
      "post": {
        "operationId": "folio-block-qa-summary",
        "summary": "Folio block QA summary",
        "description": "Summarise a folio's committed per-block QA verdicts into one `block-qa.json` a staging preview publishes: each block is failing (a FRESH verdict failed, with the worst severity), stale (a verdict predates the block's current files), passing, or unaudited. Freshness is the QA sweep's own rule, including the uses-graph hash for graph-scoped criteria. Runs no checker and writes no verdict.",
        "tags": [
          "review-heatmap"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/folio-block-qa-summary/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "folio": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio's `folio` graph directory."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write `block-qa.json`."
                  },
                  "repo": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio's instance root, where verdicts are anchored. Default: found from `folio` exactly as the QA sweep finds it."
                  }
                },
                "required": [
                  "folio",
                  "out"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "block-qa": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "A `folio-block-qa-summary/v1` file keyed by block label. Its counts go to stderr."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-block-qa-summary.jsonld",
        "x-invoke": {
          "shell": "bun run cat block-qa:publish"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "review-heatmap"
        ],
        "x-selection": {
          "when": "A staging preview is being built and its review page's heat map should show QA per section, from what the folio's QA sweep last recorded.",
          "limits": "Reports the LAST sweep: in a staging build, the sweep the job ran just before it; otherwise the committed verdicts. A folio never swept reads unaudited throughout. Verdicts are read at the instance root, so a folio in a subfolder is read at its own root, then in the folio directory.",
          "cost": "One text walk of the folio and one read per sidecar. No network."
        }
      }
    },
    "/tools/folio-block-screenshots": {
      "post": {
        "operationId": "folio-block-screenshots",
        "summary": "Folio block screenshots",
        "description": "Picture each changed figure, diagram, table, equation or simulator block on the published main site and on a staging build, and compare the two pictures pixel by pixel in Chromium's canvas. Writes `visual-diff.json` (`folio-visual-diff/v1`: per block, the share of pixels changed beyond anti-aliasing, and the before, after and diff pictures) and `visual/*.png`, which the review page's visual renderer shows. A side that cannot be pictured (page or anchor missing) is recorded as missing, never drawn blank. Drives Chromium through Playwright.",
        "tags": [
          "visual-diff"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/folio-block-screenshots/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "changeset": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The preview's `changeset.json`: which blocks changed, and their kind on each side."
                  },
                  "base": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The published main site, as a directory (the publish branch's root)."
                  },
                  "head": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The staging build's site directory."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write `visual-diff.json` and `visual/`: the site root, so the review page finds them."
                  },
                  "count": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print how many changed blocks would be pictured, and stop, so a caller installs a browser only when there is work."
                  }
                },
                "required": [
                  "changeset"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "visual-diff": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`<out>/visual-diff.json` and `<out>/visual/*.png`. A per-block summary goes to stderr."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-block-screenshots.jsonld",
        "x-invoke": {
          "shell": "bun run cat block:screenshots"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "chromium"
          ],
          "network": false
        },
        "x-satisfies": [
          "visual-diff"
        ],
        "x-selection": {
          "when": "A staging build changed a figure, diagram, table, equation or simulator, whose markup diff says little, and the reviewer needs to see before and after.",
          "limits": "The number is how MUCH changed, never whether the change is right. A block's picture is its anchor down to the next anchor, so a page whose anchors are missing or misplaced pictures the wrong region. Pictures are of the light theme.",
          "cost": "A Chromium launch and two page loads, one screenshot and one canvas compare per visual block. Nothing when no visual block changed."
        }
      }
    },
    "/tools/folio-changeset": {
      "post": {
        "operationId": "folio-changeset",
        "summary": "Folio ChangeSet",
        "description": "What changed in a folio between two git refs, block by block: each block added, removed, or changed — and for a changed block, every aspect that applies (renamed, prose, manifest, moved). Keyed on the block label, which the `id-unique` / `id-stable` QA criteria guard, not on file paths.",
        "tags": [
          "diff",
          "staging-review"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/folio-changeset/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "folio": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio's `folio` graph directory, relative to the repository — what `<slug>.json` declares for it, usually `folio/`."
                  },
                  "base": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The ref compared against. Default `origin/main`. An unresolvable base is an ERROR, never an empty ChangeSet."
                  },
                  "head": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The ref under review, or `worktree` (the default) for the files on disk, uncommitted edits included."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write the JSON. Absent: stdout."
                  },
                  "text-out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Also write `changeset-text.json`: the prose, source and rendered, of every block the ChangeSet lists, on each side that has it. The review page's diff renderers read it."
                  }
                },
                "required": [
                  "folio"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "changeset": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "A `folio-changeset/v1` document. Its one-line summary goes to stderr."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-changeset.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/schemas/changeset.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git",
            "tar"
          ],
          "network": false
        },
        "x-satisfies": [
          "diff",
          "staging-review"
        ],
        "x-skill-contracts": {
          "staging-review.input": {
            "$ref": "#/components/schemas/skill.staging-review.input"
          },
          "staging-review.output": {
            "$ref": "#/components/schemas/skill.staging-review.output"
          }
        },
        "x-selection": {
          "when": "A reviewer, or the review page, needs to know which BLOCKS a branch changed — not which files. Use it before building a before/after table, a change heat map, or a per-block diff report.",
          "limits": "Reads manifests as text and never executes the base ref, so a section whose blocks are computed rather than listed is invisible to it. An unlabelled block is identified by its slug, so renaming its file reads as removed plus added. Rendered assets (SVGs) are not compared.",
          "cost": "Seconds for a few thousand blocks: one `git archive` per committed ref, then a text walk. No network."
        }
      }
    },
    "/tools/folio-init": {
      "post": {
        "operationId": "folio-init",
        "summary": "Scaffold a folio",
        "description": "Create a new folio repository that uses this platform — folio/, uploads/, library/, the first manifests, the builder shim, agent files, and the link back to the platform.",
        "tags": [
          "repo-conversion",
          "getting-started",
          "folio-init"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/folio-init/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The folio's human title."
                  },
                  "authors": {
                    "$ref": "#/components/schemas/Text",
                    "description": "One entry per author. Repeated rather than a joined string: a name may contain the separator."
                  },
                  "content_type": {
                    "$ref": "#/components/schemas/ContentType"
                  },
                  "slug": {
                    "$ref": "#/components/schemas/Slug"
                  },
                  "dir": {
                    "$ref": "#/components/schemas/FilesystemPath",
                    "description": "Where to create the folio."
                  },
                  "link": {
                    "$ref": "#/components/schemas/LinkMode"
                  },
                  "assistant_path": {
                    "$ref": "#/components/schemas/FilesystemPath",
                    "description": "Path to the platform checkout, for a sibling link."
                  },
                  "force": {
                    "$ref": "#/components/schemas/Flag"
                  },
                  "dry_run": {
                    "$ref": "#/components/schemas/Flag"
                  }
                },
                "required": [
                  "title",
                  "authors"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "What was written, or what would have been under --dry-run."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/folio-init.jsonld",
        "x-invoke": {
          "shell": "bun run cat init-folio",
          "mcp": {
            "tool": "folio_init"
          },
          "inProcess": {
            "module": "src/tools/folio-init.ts"
          }
        },
        "x-mcp-tools": [
          "folio_init"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "repo-conversion",
          "getting-started",
          "folio-init"
        ]
      }
    },
    "/tools/folio-review-comment-move": {
      "post": {
        "operationId": "folio-review-comment-move",
        "summary": "Move a review comment's status",
        "description": "A review-process task moves one `review-comment/1.0.0` todo's status (address, send back, resolve, adjudicate, withdraw) through `transition()`, which refuses any move the named BPMN task may not make. The comment is written to the folio's todos graph (its declared `todo-feedback` directory) and, with `--commit`, committed to the edit-set's FEATURE branch. Refused on the base branch and on a detached HEAD.",
        "tags": [
          "review-comments"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/folio-review-comment-move/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "$ref": "#/components/schemas/NodeId",
                    "description": "The review comment's id, `review-pr<N>-c<commentId>`."
                  },
                  "to": {
                    "$ref": "#/components/schemas/NodeId",
                    "description": "The status to move it to: open, addressed, resolved, adjudicated or withdrawn, checked by the script against that closed list."
                  },
                  "process": {
                    "$ref": "#/components/schemas/ProcessId",
                    "description": "The BPMN process whose task is making the move."
                  },
                  "task": {
                    "$ref": "#/components/schemas/NodeId",
                    "description": "The task, in that process, making the move."
                  },
                  "decision": {
                    "$ref": "#/components/schemas/NodeId",
                    "description": "The Decision that closes it. Required to resolve or adjudicate."
                  },
                  "todos": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio's todos graph root. Default `todos`."
                  },
                  "published": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The published `review-comments.json`, for a comment not committed yet."
                  },
                  "commit": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Commit the file to the current feature branch."
                  },
                  "base": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The base branch a status may NOT be committed to. Default `main`."
                  }
                },
                "required": [
                  "id",
                  "to",
                  "process",
                  "task"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "comment": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`<todo-feedback dir>/<id>.json`, the moved node."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-review-comment-move.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/review-comment-move.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": false
        },
        "x-satisfies": [
          "review-comments"
        ],
        "x-selection": {
          "when": "An editor or adjudicator, acting in a review-process task, has decided what happens to a reviewer's comment and the decision must be recorded where the edit is: on the feature branch.",
          "limits": "Only the moves in `REVIEW_TRANSITIONS`, and only by the task each names. Anchor facts in a committed file are those of the last move; the published file is where re-anchoring shows.",
          "cost": "Reads one directory and writes one file; one git commit with `--commit`."
        }
      }
    },
    "/tools/folio-review-comments": {
      "post": {
        "operationId": "folio-review-comments",
        "summary": "Folio review comments",
        "description": "Ingest a pull request's tagged conversation comments (`block: <label>` on the first line) into `review-comment/1.0.0` todos, and write them as `review-comments.json`. Idempotent over its previous output, whose statuses it keeps. Re-anchors every comment against the head's blocks, following `renamedFrom`, and orphans a comment whose block is gone rather than dropping it.",
        "tags": [
          "review-comments"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/folio-review-comments/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "`owner/name` of the repository the pull request is in."
                  },
                  "pr": {
                    "$ref": "#/components/schemas/ChangeProposalNumber",
                    "description": "The edit-set's pull request."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write `review-comments.json`."
                  },
                  "folio": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Read the head's blocks from the folio's manifests (as text; nothing is executed). Give this OR `blocks`."
                  },
                  "blocks-out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "With `folio`: also write `blocks.json`, so a later run can anchor without checking the folio out."
                  },
                  "blocks": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A published `blocks.json`. The comment-triggered refresh uses this, so it never checks out the pull request's code."
                  },
                  "existing": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The previous `review-comments.json`. Every comment in it is kept, with its status."
                  },
                  "commit": {
                    "$ref": "#/components/schemas/CommitSha",
                    "description": "The head commit. Default `GITHUB_SHA`, else `git rev-parse HEAD`."
                  },
                  "todos": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio's todos graph root. Review comments committed under its `todo-feedback` directory, on the feature branch, win over the previously published copy."
                  },
                  "comments": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Read comments from this JSON file instead of GitHub: offline runs and tests."
                  }
                },
                "required": [
                  "repo",
                  "pr",
                  "out"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "review-comments": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "A `folio-review-comments/v1` file whose `comments` are `review-comment/1.0.0` todos. Its one-line summary goes to stderr."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-review-comments.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/review-comments.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "review-comments"
        ],
        "x-selection": {
          "when": "A pull request that edits a folio has reviewer comments, and the review page, the heat map, or an editor needs them as structured todos anchored to blocks.",
          "limits": "Reads conversation comments only, not line review comments (those anchor to a file line). A reviewer's edit to a comment after it was ingested is not re-read. Statuses are moved by review-process tasks, not by this Tool; it keeps whatever `existing` says.",
          "cost": "One paginated GitHub API call per 100 comments, plus a text walk of the manifests when `folio` is given."
        }
      }
    },
    "/tools/folio-review-coverage": {
      "post": {
        "operationId": "folio-review-coverage",
        "summary": "Folio review coverage",
        "description": "Compute the two facts `content-change-review.bpmn`'s coverage gate (`GW_Covered`) reads: `uncoveredBlocks`, the changed blocks with no reviewer verdict on their CURRENT hash, and `openDefects`. Reads a preview's `changeset.json`, `blocks.json` and `review-comments.json`. With `--commit`, writes the ingested `folio-review-verdict/v1` verdicts into the todos graph's declared `review-verdicts` directory and commits them to the edit-set's FEATURE branch; refused on the base branch and a detached HEAD. Prints the facts as JSON on stdout.",
        "tags": [
          "review-comments"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/folio-review-coverage/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "changeset": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The preview's `changeset.json`: which blocks changed."
                  },
                  "blocks": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The preview's `blocks.json`: each head block's current hash."
                  },
                  "comments": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The preview's `review-comments.json`: open defects, and the ingested verdicts."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Also write the full `folio-review-coverage/v1` report, with the uncovered labels and the stale verdicts."
                  },
                  "todos": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio's todos graph root. Verdicts committed under its `review-verdicts` directory win over the published copy."
                  },
                  "commit": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write the published verdicts into the declared directory and commit them to the current feature branch. Needs `todos`."
                  },
                  "base": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The base branch verdicts may NOT be committed to. Default `main`."
                  }
                },
                "required": [
                  "changeset",
                  "blocks",
                  "comments"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "coverage": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The `folio-review-coverage/v1` report at `out`. Its `facts` field, `{\"uncoveredBlocks\": n, \"openDefects\": n}`, is also printed alone on stdout: what `workflow_complete` takes for `GW_Covered`. The summary goes to stderr."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-review-coverage.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/review-coverage.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": false
        },
        "x-satisfies": [
          "review-comments"
        ],
        "x-selection": {
          "when": "The review coordinator reaches `GW_Covered` and needs to know, rather than guess, whether every changed block has been read at its current version and no defect is still open.",
          "limits": "Counts only what reviewers recorded as verdicts. A block nobody tagged is uncovered even if somebody read it. A verdict on an older hash is reported as stale and not counted.",
          "cost": "Reads three JSON files and one directory; one git commit with `--commit`."
        }
      }
    },
    "/tools/folio-viewer": {
      "post": {
        "operationId": "folio-viewer",
        "summary": "Folio viewer",
        "description": "Render each declared folio directory as a browsable page over its published index.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/folio-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/folio-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat folio:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/gates": {
      "post": {
        "operationId": "gates",
        "summary": "The platform's quality gates",
        "description": "Run the checks CI runs, derived from the workflow rather than listed here. One Tool for all of them, not one per gate: the list is computed from `.github/workflows/code-quality-gates.yml` at call time, so it cannot drift from what CI actually enforces.",
        "tags": [
          "platform-gates",
          "continual-progress"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/gates/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "all": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Add the jobs that need a browser; the default is the fast set."
                  },
                  "list": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print the derived gates and exit, running none."
                  }
                },
                "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 gate, then a pass count or the failures. Three exit codes, because two cannot carry the distinction: 0 every gate passed, 1 a gate failed, 2 the gate set could NOT BE DERIVED — the workflow it reads is absent or yields nothing. A caller must not read 2 as either verdict; it matters most downstream, where this Tool is inherited and `.github/workflows/` is not."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/gates.jsonld",
        "x-invoke": {
          "shell": "bun run cat gates"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "platform-gates",
          "continual-progress"
        ],
        "x-selection": {
          "when": "Before any push, and as the answer to \"what checks this?\". It matters most where CI is not: `tools/` is an INHERITED declaration and `.github/workflows/` is not, so a downstream layer gets this Tool and none of the gates it names.",
          "limits": "It runs what the workflow declares, so a check CI does not run is a check this does not run. The default omits the browser jobs; `--all` adds them, and `render:bpmn:check` needs Chromium.",
          "cost": "The fast set is about a minute, dominated by `bun test`. `--all` adds a browser render."
        }
      }
    },
    "/tools/gates-merged": {
      "post": {
        "operationId": "gates-merged",
        "summary": "Gates on the merged tree",
        "description": "Build this branch merged with the current base in a throwaway worktree and run the full `bun run cat gates` there — the state a merge will actually produce, which neither the branch's CI nor the base's CI evaluates. Exit 0 passes, 1 conflicts or fails, 2 could not determine (never read as clean). The working copy is never touched.",
        "tags": [
          "prepare-merge"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/gates-merged/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "base": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The base branch to merge with; `main` when omitted. Fetched first."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The gate report for the merged tree, or the conflicting paths."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/gates-merged.jsonld",
        "x-invoke": {
          "shell": "bun run cat check:merged"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "prepare-merge"
        ],
        "x-selection": {
          "when": "Immediately before asking for a merge, and again if the base has moved since. Not on every push: it is the full gate set, on a second tree.",
          "limits": "It tests the base as fetched NOW; the base can still move before the merge lands. The merge queue (`merge_group:` on the gating workflows) closes that last gap.",
          "cost": "One full `bun run cat gates`, plus a worktree; a `bun install` only when the merge changes the lockfile."
        }
      }
    },
    "/tools/get-graph-stats": {
      "post": {
        "operationId": "get-graph-stats",
        "summary": "Content graph counts",
        "description": "Node and edge counts for the content graph by provenance and kind, and whether each root exists. Tells 'nothing matched' from 'that population has not been built'.",
        "tags": [
          "corpus-grep"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/get-graph-stats/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "refresh": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Rebuild the index from disk first."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stats": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "JSON: node and edge counts, by provenance and kind, per root."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/get-graph-stats.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "get_graph_stats"
          },
          "inProcess": {
            "module": "src/tools/graph.ts"
          }
        },
        "x-mcp-tools": [
          "get_graph_stats"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "corpus-grep"
        ]
      }
    },
    "/tools/get-neighbors": {
      "post": {
        "operationId": "get-neighbors",
        "summary": "Walk the content graph from one node",
        "description": "List the nodes adjacent to one node, out (what it depends on) or in (what depends on it), to a given depth and optionally over named edge terms only. An unknown edge term is reported, never silently dropped.",
        "tags": [
          "corpus-grep"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/get-neighbors/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Node @id or authored label, e.g. `thm:main`."
                  },
                  "direction": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "`out` (default), `in` or `both`."
                  },
                  "hops": {
                    "$ref": "#/components/schemas/Count",
                    "description": "Traversal depth, 1-6 (default 1)."
                  },
                  "edges": {
                    "$ref": "#/components/schemas/Text",
                    "description": "A LIST of edge terms (uses, interprets, cites, contains, ...) to restrict to. Omit for all."
                  }
                },
                "required": [
                  "id"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "JSON: the neighbours, each with the edge path that reached it."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/get-neighbors.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "get_neighbors"
          },
          "inProcess": {
            "module": "src/tools/graph.ts"
          }
        },
        "x-mcp-tools": [
          "get_neighbors"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "corpus-grep"
        ]
      }
    },
    "/tools/gh-pages": {
      "post": {
        "operationId": "gh-pages",
        "summary": "GitHub Pages (gh-pages)",
        "description": "Push a rendered Knowledge Graph to GitHub Pages at a publication root URL — a staging preview (`branches/<slug>/`) or the release root, the same steps either way — and report the push: a status (pushed, not pushed, could not determine) and one message carrying the commit merged onto `gh-pages` and the QA result. Its steps are bootstrap-tools' `render-kg-to-github-pages` process, which first provisions the target: an orphan `gh-pages` branch, then Pages switched on to serve it.",
        "tags": [
          "render-kg-to-cdn"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/gh-pages/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root whose Knowledge Graph is rendered, or a tree a caller already rendered and verified."
                  },
                  "url": {
                    "$ref": "#/components/schemas/Url",
                    "description": "The publication root URL. Default: the declaration's `iriBase`, else `https://<owner>.github.io/<repo>/`."
                  },
                  "subgraph": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "A declared directory id to render; repeatable. Absent: the whole graph."
                  },
                  "sha": {
                    "$ref": "#/components/schemas/CommitSha",
                    "description": "The commit that is live: the commit on `gh-pages`."
                  }
                },
                "required": [
                  "root"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "$ref": "#/components/schemas/Text",
                      "description": "`pushed`, `not-pushed` or `could-not-determine` — never `pushed` over a check that could not look."
                    },
                    "message": {
                      "$ref": "#/components/schemas/Text",
                      "description": "One line: the live commit, the root URL, and the QA of both what was staged and what is served."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/gh-pages.jsonld",
        "x-invoke": {
          "manual": true
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "render-kg-to-cdn"
        ],
        "x-selection": {
          "when": "The CDN target is GitHub Pages: this repository's docs site and its review previews, and every layer whose declaration names a GitHub `repository`.",
          "limits": "GitHub only. Pages cannot serve server-side redirects or custom headers, and a full-replace push to the `gh-pages` branch deletes what the build did not produce unless the caller restores it first (`docs-site-publish`). Another CDN is another Tool satisfying `render-kg-to-cdn`.",
          "cost": "Free for a public repository: Pages and the Actions minutes its workflow uses. A deploy takes a minute or two to be served."
        }
      }
    },
    "/tools/github": {
      "post": {
        "operationId": "github",
        "summary": "GitHub (issues, Actions, pull requests)",
        "description": "GitHub as a Tool: the forge that carries an adjudication as an issue, runs the workflow that records it on Actions, and holds the record as a pull request for a maintainer to merge. One forge among possible others; the process names the skill, never GitHub.",
        "tags": [
          "translation-adjudication"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/github/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository holding the catalogues. Default: the current one."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "$ref": "#/components/schemas/Url",
                      "description": "The issue, workflow run or pull request."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/github.jsonld",
        "x-invoke": {
          "shell": "gh",
          "manual": true
        },
        "x-install": {
          "cli": "gh (optional; the web interface needs nothing)",
          "service": "github.com"
        },
        "x-requires": {
          "network": true
        },
        "x-satisfies": [
          "translation-adjudication"
        ],
        "x-selection": {
          "when": "The layer's repository is on GitHub: the review page files issues there, and its caller workflow runs on Actions.",
          "limits": "GitHub only. Identity is GitHub's `author_association`, so a reviewer must be an owner, member or collaborator of the repository. A PR opened with the workflow's token starts no other workflows. Another forge carrying the same `translation-adjudication/v1` record would be another Tool satisfying `translation-adjudication`.",
          "cost": "Free for a public repository: issues, pull requests and the Actions minutes of one short job per adjudication."
        }
      }
    },
    "/tools/glossary-build": {
      "post": {
        "operationId": "glossary-build",
        "summary": "Glossary build",
        "description": "Build a paper's glossary index from its manifests and render the LaTeX. `--check` reports drift instead of writing, comparing everything except the `generated` timestamp so a re-run is not mistaken for a change.",
        "tags": [
          "document-intake"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/glossary-build/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "targetPath": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The paper directory, which must hold a `<paper>.ts` manifest. Absent, the command exits 2 with its usage — could-not-determine, not an empty glossary."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Report drift and write nothing."
                  }
                },
                "required": [
                  "targetPath"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "glossary": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`glossary.json` beside the paper, and `chapters/glossary.tex` at the repo root."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/glossary-build.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/build-glossary.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "document-intake"
        ]
      }
    },
    "/tools/glossary-from-source": {
      "post": {
        "operationId": "glossary-from-source",
        "summary": "Glossary candidates from a source",
        "description": "Read a source's glossary and abbreviations sections (an L1 entry's sections/, or a folio block) into `candidate` terms of a folio-glossary/v1 scheme, verbatim, each with `source: <file>#L<line>`. Acronyms fold into the term they expand as `notation`. The scheme is merged: terms a person owns are never changed. `--check` writes nothing and fails when the scheme would change.",
        "tags": [
          "glossary-terms"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/glossary-from-source/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The scheme file to write or merge into: `glossary/<scheme>.glossary.json`."
                  },
                  "id": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "The scheme id, for a new file."
                  },
                  "title": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The scheme title, for a new file: free text, so it goes on stdin."
                  },
                  "from": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A directory whose glossary and abbreviations sections are read: an L1 entry's `sections/`."
                  },
                  "terms": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A Markdown file read as term and definition rows."
                  },
                  "abbreviations": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A Markdown file read as acronym and expansion rows."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if the scheme is stale, instead of writing."
                  }
                },
                "required": [
                  "out"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scheme": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The merged folio-glossary/v1 scheme."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/glossary-from-source.jsonld",
        "x-invoke": {
          "shell": "bun run cat glossary:from-source"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "glossary-terms"
        ]
      }
    },
    "/tools/glossary-page": {
      "post": {
        "operationId": "glossary-page",
        "summary": "Glossary page",
        "description": "Render every declared glossary — authored SKOS schemes, the swimlane ledger and the terms extracted from knowledge-graph assets — as the glossary page and one page per asset type, at the route of the visualiser core declares for it.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/glossary-page/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under cat-harness's docs, as a repository's own site build does (`visualiser-writers.ts`)."
                  },
                  "scope": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "A scoped site build: the comma-separated instances whose pages this writer writes (the IG and the layer it lands on); every other instance's pages are linked on that layer's own site. Passed by the tools layer's `visualiser-writers.ts` (owner, 2026-11-08, Q-SZ-2 \"B\"). Absent: every instance."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The glossary pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/glossary-page.jsonld",
        "x-invoke": {
          "shell": "bun run cat glossary:page"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/glossary-table": {
      "post": {
        "operationId": "glossary-table",
        "summary": "Glossary and acronyms tables",
        "description": "Rewrite the glossary and acronyms tables of a document from its folio-glossary/v1 schemes, as `glossary/glossary-tables.json` (folio-glossary-tables/v1) lists them: terms with their altLabels, definitions and editorial notes; acronyms (notation and prefLabel); or element types, the placeholder types an ArchiMate metamodel view shows, with each term's definition and skos:example. The block's caption and footnotes are left alone. `--check` writes nothing and fails when a table is stale.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/glossary-table/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The instance root holding `glossary/glossary-tables.json`."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a table is stale, instead of writing."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "blocks": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The rewritten table blocks, at the paths the config names."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/glossary-table.jsonld",
        "x-invoke": {
          "shell": "bun run cat glossary:table"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ],
        "x-selection": {
          "when": "A document's glossary, acronyms or element-types tables should come from its SKOS glossaries (and, for element types, its ArchiMate metamodel view). For a References list use references-render.",
          "limits": "Only the tables `glossary/glossary-tables.json` names; captions and footnotes are left alone.",
          "cost": "Milliseconds per table; reads the instance's glossary schemes and, for element types, one Archi model; no network."
        }
      }
    },
    "/tools/handover-screen": {
      "post": {
        "operationId": "handover-screen",
        "summary": "Screen a hand-over for injected instructions, field by field",
        "description": "Before a model reads a sub-agent's report, a delegated prompt, a tool result or a comment from someone who is not the principal, screen it against a declared schema whose top-level fields are `control` (steers what the receiver does) or `data` (content it reads). A finding in a control field, or any field the strict schema does not declare, is REFUSED, so a report cannot extend the delegator's plan. A finding in a data field is QUARANTINED: the original is kept and marked, never stripped. The patterns are a deterministic tripwire (instruction overrides, role and turn spoofs, fence breaks, tool-call syntax, hidden Unicode, exfiltration links, pipe-to-shell), a mitigation and not a guarantee. Exit 0 clean, 1 refused, 3 quarantined, 2 could not determine.",
        "tags": [
          "security"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/handover-screen/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "schema": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "JSON `{ fields: { name: \"control\" | \"data\" }, strict?: boolean }`."
                  },
                  "payload": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The hand-over, as a JSON object."
                  },
                  "text": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A single free-text input, screened as one DATA field."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verdict": {
                      "$ref": "#/components/schemas/Flag",
                      "description": "`clean`, `quarantined` or `refused`, with every finding's path, field role and kind; also the exit status."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/handover-screen.jsonld",
        "x-invoke": {
          "shell": "bun run cat handover:screen"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "security"
        ]
      }
    },
    "/tools/harness-state": {
      "post": {
        "operationId": "harness-state",
        "summary": "Per-harness setup position and health",
        "description": "For every harness in the checkout, run bootstrap's setup check without performing anything or touching the network, and write one `folio-harness-state/v1` file: each step in its state, the first step not done (its position) with what to do next, and health badges that are the harness's own (setup steps; the layer's committed health report, unknown without one). A recommendation is said, never acted on.",
        "tags": [
          "initialization-steps"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/harness-state/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where `<harness>.json` and `index.json` go. The deploy passes `./_site/assets/harnesses`. Absent: print the states and write nothing."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print the states as JSON and write nothing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "states": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "One `<harness>.json` per harness and an `index.json` listing them with their positions."
                    },
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "One line per harness: its position, the next step, and its badges."
                    },
                    "result": {
                      "$ref": "#/components/schemas/HarnessStates",
                      "description": "With --json, or with no --out, every harness's state as one `HarnessStates` record, in name order. Programs read this; people read `report`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/harness-state.jsonld",
        "x-invoke": {
          "shell": "bun run cat harness:state"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "initialization-steps"
        ],
        "x-selection": {
          "when": "A page or an agent needs to know, per harness, how far its setup got and what to do next, or whether the harness itself is healthy, as against its repository.",
          "limits": "Offline and dry-run: a step that needs the network (documents at their IRIs, Pages live) is could-not-determine, never done. In an index that mounts a layer in part, every step looking for a file in it is could-not-determine. Built at deploy and never committed, so it describes the tree the deploy published.",
          "cost": "About 6 seconds for 11 harnesses. Nothing to install, no network."
        }
      }
    },
    "/tools/ig-folio-site-workflow": {
      "post": {
        "operationId": "ig-folio-site-workflow",
        "summary": "Build and publish an IG repository's own site with its folio-site.yml workflow",
        "description": "Dispatch the IG repository's `folio-site.yml` (copied from the IG layer's `ig-repo-site` template): on a runner it composes the harness chrome for THIS layer (`compose-docs --shell --instance`, `gen-navbar-include`), composes the IG at the root of that Jekyll shell (`stage-ig-sites --compose-at-root`), builds it with Jekyll so every IG page wears the theme's side bar, search box and icon row, publishes the layer's served directories, rails any page Jekyll did not lay out (`rail-standalone-pages --foreign-site --instance`), stamps the platform that built it (`folio-build.json`), and on the default branch deploys the whole site to the `gh-pages` root. It reports platform drift against sibling sites and re-dispatches the IGs this one depends on when a token allows.",
        "tags": [
          "feature-staging",
          "harness-tiles"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ig-folio-site-workflow/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The IG repository whose workflow to dispatch. Default: the current repository."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to build. Only the default branch deploys; any other builds and reports."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The dispatch, and the run it starts; the site is served once that run and GitHub's Pages deploy have finished."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ig-folio-site-workflow.jsonld",
        "x-invoke": {
          "shell": "gh workflow run folio-site.yml"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "feature-staging",
          "harness-tiles"
        ],
        "x-selection": {
          "when": "A pipeline that carries `folio-site.yml` and builds on a runner rather than in the agent's checkout. `stage-local` gives an IG the same site — theme side bar and search, served directories, stamp — from the agent's checkout.",
          "limits": "Dispatch-only and runner-bound: it needs a runner, the `gh` CLI with a token that may run workflows, and the folio-assistant submodule the template expects. It builds the IG with `stage-ig-sites`, not the IG's own `ghbuild.yml`, and has no plan or dry-run: a run on the default branch deploys. The agent pipeline does not use it.",
          "cost": "One runner job, 8 to 15 minutes, plus GitHub's Pages deploy."
        }
      }
    },
    "/tools/index-config-migrate": {
      "post": {
        "operationId": "index-config-migrate",
        "summary": "Convert a checkout to a root index.config.json",
        "description": "Write the root `index.config.json` (`folio-index-config/v1`) that says which layers the checkout instantiates, where each comes from (`source.local` or `source.remote`) and which owns `/` (`site.landing`), from the root `*.config.json` files and the declaration's `remoteMounts`. With `--write` it moves `remoteMounts` off the declaration into `source.remote` entries, writes the generated `.gitignore` block, and renames a legacy `<name>.mount-lock.json` to `index.lock.json`. Without a flag it prints the index it would write. Idempotent: a re-run merges what the declaration gained, and refuses an entry the index already holds differently. A root config naming no layer is reported as `unmatched-config` and not imported, because what to do with it is a person's decision.",
        "tags": [
          "index-config",
          "remote-mount"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/index-config-migrate/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The checkout to convert; omitted, this one."
                  },
                  "write": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write the index, move the mounts, write the ignore block and rename the lock."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Exit 1 when --write would change anything; write nothing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "findings": {
                      "$ref": "#/components/schemas/Count",
                      "description": "The index it would write or wrote, and each finding (`unmatched-config`, `unreadable-config`, `landing-undetermined`). Exit 0 written, up to date or planned; 1 stale under --check; 2 could not convert."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/index-config-migrate.jsonld",
        "x-invoke": {
          "shell": "bun run cat index-config:migrate"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "index-config",
          "remote-mount"
        ]
      }
    },
    "/tools/ingest-extended": {
      "post": {
        "operationId": "ingest-extended",
        "summary": "Ingest, with PDF and image extensions",
        "description": "Ingest a PDF into `library/` — embedded outline, page text, OCR for scans, and image extraction — using PyMuPDF, tesseract and pypdf with Pillow.",
        "tags": [
          "library-ingestion"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ingest-extended/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The PDF to ingest, under the declared `uploads` graph."
                  },
                  "outdir": {
                    "$ref": "#/components/schemas/RepoPath"
                  },
                  "dryRun": {
                    "$ref": "#/components/schemas/Flag"
                  }
                },
                "required": [
                  "file"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "$ref": "#/components/schemas/Slug",
                      "description": "The library entry written."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ingest-extended.jsonld",
        "x-invoke": {
          "shell": "bun run cat ingest"
        },
        "x-install": {
          "cli": "bun run cat ingest:install-extended"
        },
        "x-requires": {
          "runtime": [
            "python3",
            "pymupdf",
            "tesseract"
          ],
          "network": false
        },
        "x-satisfies": [
          "library-ingestion"
        ],
        "x-selection": {
          "when": "Reach for this when the upload is a PDF and you need its CONTENT — an outline-bearing document read at chapter granularity, a text-layer document read at page granularity, or a scan that must be OCR'd first. Confirm the backend is present before relying on it: `bun run cat check-deps`, or simply run the pair's entry point, which reports `no PDF backend` rather than guessing.",
          "limits": "It adds nothing for archives, spreadsheets or metadata — `ingest-stdlib` does those, and does them where this cannot run. Its PDF rungs are tested in CI, which installs the lean set; the table rung (`pdf-tables.py`, camelot) is not, so anything gated on it is a path CI cannot exercise.",
          "cost": "The lean set is 144 MB and CI installs it. `camelot-py` for `pdf-tables.py` is the part CI skips — 912 KB itself, but 323 MB with numpy, pandas and OpenCV, more than the whole lean set. The dependencies are not independent either: `pypdf` image extraction needs `Pillow`, and `cryptography` panics under pyo3 on IMPORT when `cffi` is missing. All of it is declared in `schemas/sdlc/python-deps.ts`, so the cost is read rather than rediscovered."
        }
      }
    },
    "/tools/ingest-stdlib": {
      "post": {
        "operationId": "ingest-stdlib",
        "summary": "Ingest, standard library only",
        "description": "Ingest an upload into `library/` using only the Python standard library — archive listings, CSV and spreadsheet records, technical file metadata, and the content sniff that routes a file to its rung.",
        "tags": [
          "library-ingestion"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ingest-stdlib/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The upload to ingest, under the declared `uploads` graph."
                  },
                  "outdir": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Library root; defaults to the declared `library` graph."
                  },
                  "dryRun": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Report the chosen rung and stop."
                  }
                },
                "required": [
                  "file"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "$ref": "#/components/schemas/Slug",
                      "description": "The library entry written."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ingest-stdlib.jsonld",
        "x-invoke": {
          "shell": "bun run cat ingest"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "python3"
          ],
          "network": false
        },
        "x-satisfies": [
          "library-ingestion"
        ],
        "x-selection": {
          "when": "Reach for this first, and in CI always. It is the only one of the pair that runs where nothing has been installed — which is every fresh container and every CI job here, since the workflow installs `ruff` and nothing else. It covers archives, CSV and spreadsheets, technical metadata, and the sniff that decides which rung a file takes, including the OOXML/ODF container check that stops a workbook being listed as a bag of XML parts.",
          "limits": "It cannot read a PDF. Text layer, embedded outline, page rendering, OCR and image extraction all need a backend it deliberately does not have, so a PDF routes to `undetermined` and is REFUSED rather than half-ingested. `ingest-extended` is the sibling that does those.",
          "cost": "None beyond `python3` itself. No wheels, no C toolchain, no network, nothing to keep current, and no CI minutes spent installing."
        }
      }
    },
    "/tools/instantiate-harness": {
      "post": {
        "operationId": "instantiate-harness",
        "summary": "Instantiate a harness over a repository that has none: pin, mount, open the setup-only PR, render the preview",
        "description": "The scripted step of the initiation process (getting-started.bpmn, the repo-conversion skill §4). Reads the harness's declaration at its pin and every `needs`, transitively (a need beside the layer that needs it unless --repo-of says otherwise, at its default branch's tip unless --pin says otherwise, its declaration's name checked), seeds them all into the repository's index.config.json with the consent given (`remote-mount --seed --whole`), sets `site.landing` to the harness, `site.agentRun` and `mountApprovers`, mounts the closure (`remote-mount`: index.lock.json and the .gitignore mounts block), installs it as root workspaces with the hoisted linker, writes the root bootstrap (`.github/cat.ts` and `.github/mount-from-lock.sh` from cat-harness-tools `templates/root-bootstrap/`) and sets the root's `cat` script to `bun .github/cat.ts`, so `bun run cat …` mounts the layers itself on a later fresh clone, re-renders the agent surface from the mounted generators, runs the harness's `instantiate:<harness>` checkout script when a mounted layer declares it, and commits on a branch (default harness/<harness>). Then, unless --local, pushes the branch, provisions gh-pages when absent (`pages-bootstrap --provision`), opens the setup-only PR, runs `prepare:<harness>` when declared (what the site is built from and nobody commits, such as an IG's AST) and renders the branch's preview at gh-pages branches/<branch>/ (`stage-local`); with --local the site is built and composed and nothing is pushed. It imports only node:*, so it runs from a fresh clone of cat-harness-tools before anything is mounted: it lays the platform's own closure, at the pins the repository will mount, into a temporary root to run the mount from. On a repository with nothing mounted yet, run the same file from a fresh clone: `git clone --depth 1 https://github.com/litlfred/cat-harness-tools /tmp/cht && bun run /tmp/cht/scripts/instantiate-harness.ts …`. Two more flags, not declared as ports because no constrained type carries them yet: `--pin <name>=<sha>` pins one layer of the closure, `--repo-of <name>=<owner/repo>` says where a need lives.",
        "tags": [
          "repo-conversion",
          "remote-mount"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/instantiate-harness/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The checkout to harness: clean, with a GitHub origin. Default: the working directory."
                  },
                  "harness": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The harness, OWNER/REPO, pinned at its default branch's tip (pin it otherwise with --pin <name>=<sha>)."
                  },
                  "consentBy": {
                    "$ref": "#/components/schemas/Login",
                    "description": "Who consented to mounting the closure; also recorded as the one mountApprover. The evidence (where they consented, readable) is read from stdin."
                  },
                  "evidence": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Where the consent was given, readable (a session, an issue comment). On stdin because it is free prose: it quotes what was said."
                  },
                  "branch": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The setup branch. Default: harness/<harness>. Never the default branch."
                  },
                  "plan": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Resolve the closure, print every step, and stop."
                  },
                  "local": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Commit on the branch, push nothing; the site is built and composed (stage-local --dry-run)."
                  },
                  "noPr": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Push the branch and the preview, open no PR."
                  }
                },
                "required": [
                  "harness",
                  "consentBy"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "$ref": "#/components/schemas/Url",
                      "description": "The branch's preview, gh-pages branches/<branch>/, once GitHub's Pages deploy has run."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/instantiate-harness.jsonld",
        "x-invoke": {
          "shell": "bun run cat harness:instantiate"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": true
        },
        "x-satisfies": [
          "repo-conversion",
          "remote-mount"
        ],
        "x-selection": {
          "when": "A repository that mounts no harness yet is to be harnessed: an existing FHIR IG adopting a FHIR harness, a repository becoming a folio overlay. Its PR is the setup-only PR repo-conversion §4 asks for before any content PR.",
          "limits": "The harness's own adoption steps are its checkout scripts instantiate:<harness> and prepare:<harness>; a harness that declares neither is mounted and rendered with what its layers already declare, and a site that needs a build input nobody produced (an IG with no AST) is refused by the render step with its reason. Re-pinning an already harnessed repository is remote-mount --seed, not this.",
          "cost": "The mount: a blobless fetch of each layer of the closure and one install (a few minutes). Then the harness's prepare step (an IG's AST: a full IG Publisher run) and the render."
        }
      }
    },
    "/tools/iris-pages": {
      "post": {
        "operationId": "iris-pages",
        "summary": "who-iris catalogue and docs pages",
        "description": "Render who-iris's docs pages, the catalogue visualiser at its declared route (what the catalogue knows, and what it records that it does not know), the library's withheld list, and the IRIS replica's home page.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "who-iris/iris-pages/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built (the tree `compose-docs --shell` wrote): write only the catalogue page into it, at its route in who-iris's own site, plus a forwarding page at the declared route. A site build passes it (`visualiser-writers.ts`)."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The replica's home page at `site/index.html` (and its translations), the docs under `docs/`, and the catalogue page under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/who-iris/tools/iris-pages.jsonld",
        "x-invoke": {
          "shell": "bun run cat iris:pages"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/journey-refs": {
      "post": {
        "operationId": "journey-refs",
        "summary": "Every reference a journey or a workshop names resolves",
        "description": "Read every `user-scenario` and `workshop` node in the checkout through the layers' declared directories, with the journeys viewer's own resolver, and resolve what each names: actors (`personas`, a step's `lead`, `experiences[].actor`, `handoff.from`/`to`, `illustrationStyle.cast[].actor`), user stories, `realisedBy` BPMN files (instance-relative) and the element ids in them, `uses` blocks in a directory declaring `building-blocks`, `req:` requirements, FHIR examples and a step's `dak` assets (data sets, decision tables, indicators) in a `fhir-artifact-index` (could not determine while the index is built at publish), `illustration.src` files, `follows`/`partOf`/`parts`/`includes` journeys (parts and includes forming no cycle; an `includes` held against the call activity its step's `realisedBy` names, could not determine when the call names no process), the `trustLadder` code list and each `record.state` code of it, and ArchiMate `views`; and each workshop's `scenarios`, `steps[]` `{scenario, step}` and `<scenario>#<step>` refs; each device screen's `owner` and `personCard` actors, its `steps[]` `{scenario, step}`, and the FHIR examples its `qr` and `recordList` blocks name; and every persona's `avatar` image path. Every journey is a DAK user scenario (the kind `specialises` it): its DAK personas, the roles its persona actors play, must be non-empty and each a declared role; a persona may be an actor or (0.4.0) a role. What is derived is not also written: a listed part's `follows` or `partOf`, personas equal to the parts', a lead equal to the lanes' first actor, are each a redundant finding, and a 0.4.0 step with no experiences whose lanes no persona plays is a finding. A node that does not parse is a finding. One line per finding, naming the layer, file and step. Exit 0 every reference resolves (or no layer holds a journey or a workshop, which is said); 1 one does not; 2 the declarations could not be read.",
        "tags": [
          "journey-maps"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/journey-refs/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A directory in the checkout to check. Default: the working directory."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print the report as JSON."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "findings": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Unresolved references and unparsed nodes, one line each on stderr, with the count of references examined; or one ✓ line."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/journey-refs.jsonld",
        "x-invoke": {
          "shell": "bun run cat check:journey-refs"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "journey-maps"
        ],
        "x-selection": {
          "when": "In every layer pull request's checks (it is a `check:` script, so the gate set derives it), and before publishing a site whose layer declares a `journeys-viewer` visualiser: a journey that names a story, a BPMN task, a block or an image that is not there.",
          "limits": "A `realisedBy` process and an `illustration.src` are resolved in the journey's own layer only, as the viewer draws them; the other references are looked up in the journey's layer first, then in every layer the checkout mounts.",
          "cost": "One read of the checkout's declared directories, as the viewer makes; milliseconds per journey."
        }
      }
    },
    "/tools/journeys-viewer": {
      "post": {
        "operationId": "journeys-viewer",
        "summary": "Journeys viewer",
        "description": "Draw every journey (`user-scenario`) and workshop (`workshop`) in the checkout as static pages at the route of the visualiser a layer declares for this Tool, `<locale>/<instance>/<id>/`: an index of all journeys, grouped by layer (each a sub-graph page), each parent's `parts` nested under it in its order with optional and repeating parts marked (an older file's `partOf` children after them, ordered along `follows`), and a plain DAK user scenario with no steps listed as one; one page per journey, its parts in order and the journeys it is a part of, a journey map with a lane and a feeling curve per persona, then each step, linked to the journey it `includes`, with its BPMN drawing (the step's flow nodes highlighted), user stories, requirements, FHIR examples, building blocks, the DAK assets it uses (data sets, decision tables and indicators, linked into the IG) and ArchiMate views; and the workshop layer, the questions for the room on each step, a page per workshop and per module, job aids, and printable A3/A4 sheets; and each device screen (`device-screen`) that shows a step a workshop presents, drawn as a static device mock (phone, tablet, scanner, desktop, kiosk) with its owner beside it, in the workshop's Device Demo, linked both ways with the walkthrough. A persona's picture (`meta.persona.avatar`) is drawn wherever the persona appears. Layers below the declaring one are read through their declarations, so a downstream site shows the journeys of the layers it mounts too.",
        "tags": [
          "journey-maps"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/journeys-viewer/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer whose `visualisers` declare this Tool: the pages go to that visualiser's route. One that declares none gets nothing, and the run exits 78 (not applicable)."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: the pages are written at the declared route under it. Absent, under the layer's own site directory. The route is this Tool's alone and is replaced whole."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer's pages and its two assets (`assets/journeys.css`, `assets/journeys.js`), under the declared route."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/journeys-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat journeys:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "journey-maps"
        ],
        "x-selection": {
          "when": "A site build of a layer that declares a `journeys-viewer` visualiser over its `user-scenario`, `workshop` and `device-screen` directories; run with the other declared writers (`visualiser-writers.ts`), before the navbar pass.",
          "limits": "Static pages: the stepper, the filter and the remembered assessment ticks are a small dependency-free script, and every page reads complete without it. A FHIR example links to its page only where a layer declares a `fhir-artifact-index`; an ArchiMate view is drawn only where its layer declares `archimate-pages`. A device screen is drawn in the one state its node says: a toggle is drawn on or off, a button is a label; a workshop that declares no screen for its steps frames its own app (`presentation.deviceDemo`) instead.",
          "cost": "Milliseconds per journey; a BPMN drawing is inlined once per step that names it."
        }
      }
    },
    "/tools/judge-tree": {
      "post": {
        "operationId": "judge-tree",
        "summary": "Judge a tree and record the verdict by digest",
        "description": "Run the layer PR-check gates and tests on a composed tree (head) and on its base, or reuse a stored verdict whose digest is the base tree's, compare them with the layer-pr-checks compare scripts, and write a verdict record: {treeDigest, runner {kind agent|github-actions|local, id}, startedAt, finishedAt, gates [{name, exit, seconds, skipped?}], tests {total, failed, new}, verdict green|red|unknown}. With a token it publishes the verdict as the commit status `judge-tree`; `check` answers whether any runner judged a digest green; `sample` re-runs a seeded few gates of a record.",
        "tags": [
          "platform-gates",
          "prepare-merge"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/judge-tree/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lock": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The index.lock.json whose fixity digests name every layer but the caller."
                  },
                  "caller": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The caller as owner/name (or its lock layer): the entry replaced by its PR tree. Every runner must name it the same way."
                  },
                  "caller-dir": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The caller's git checkout; its HEAD^{tree} (or --sha's) is the PR tree."
                  },
                  "sha": {
                    "$ref": "#/components/schemas/CommitSha",
                    "description": "The head commit: whose tree is read from --caller-dir, and where the status is published."
                  },
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The mounted index with the caller swapped in, where run-gates.py runs."
                  },
                  "instance": {
                    "$ref": "#/components/schemas/InstanceId",
                    "description": "The own layer(s) run-gates.py judges; repeatable."
                  },
                  "base-verdict": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A stored verdict record standing in for the base run; refused unless its treeDigest is the base tree's (--base-tree)."
                  },
                  "base-root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A mounted base tree to run the gates on instead."
                  },
                  "test-path": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "What `bun test` runs on each side; none means no tests."
                  },
                  "publish": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Post the commit status `judge-tree` when GITHUB_TOKEN/GH_TOKEN is set; without one, the record file is the verdict."
                  }
                },
                "required": [
                  "lock",
                  "caller"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "record": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The verdict record, `<records-dir>/<treeDigest>.json` unless --out names it; valid against the tools layer's `schemas/verdict-record.schema.json`. Three exit codes: 0 green, 1 red, 2 COULD NOT DETERMINE (no judging scripts, a stored base verdict for another tree, a compare script that crashed, or no gate ran). 2 is never green, and neither is a verdict for another digest."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/judge-tree.jsonld",
        "x-invoke": {
          "shell": "bun run cat judge:tree judge"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "python3",
            "git"
          ],
          "network": false
        },
        "x-satisfies": [
          "platform-gates",
          "prepare-merge"
        ],
        "x-selection": {
          "when": "When a PR's tree must be judged and any runner can do it: an agent before pushing, a developer locally, or CI. Then `verdict-check.yml` passes the PR on the published verdict instead of re-running ~300 gates per side.",
          "limits": "The digest trusts the lock's fixity digests for every layer but the caller, so a run that takes lower layers at main instead of the lock judges a tree the digest does not name. A verdict answers only for its exact digest: a change to the judging scripts is a new digest and needs a new verdict.",
          "cost": "That of layer-pr-checks for one side, or two when no stored base verdict exists: gates dominate (minutes to tens of minutes). `digest` and `check` are one hash and at most one HTTP request."
        }
      }
    },
    "/tools/kg-audit": {
      "post": {
        "operationId": "kg-audit",
        "summary": "Knowledge-graph audit",
        "description": "Audit every join in the actor→role→skill→task sentence and write a committed QA sidecar per node. The sidecar distinguishes \"unbound since it was drawn\" from \"broken in the commit under review\".",
        "tags": [
          "code-node-review"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/kg-audit/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Compare against the committed sidecars and fail on a critical finding or a stale one, instead of writing."
                  },
                  "strict": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Promote `major` to failing as well. Not what CI runs; see the note on constant-red checks in `remote-skill-servable.test.ts`."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sidecars": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The QA tree, mirroring each subject's own path, because a flat tree would collide: several basenames occur twice."
                    },
                    "worstSeverity": {
                      "$ref": "#/components/schemas/Text",
                      "description": "critical, major, minor — or none. `unknown` findings are never a pass."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/kg-audit.jsonld",
        "x-invoke": {
          "shell": "bun run cat kg:audit"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "code-node-review"
        ]
      }
    },
    "/tools/kg-graph-export": {
      "post": {
        "operationId": "kg-graph-export",
        "summary": "Knowledge-graph export",
        "description": "Dump this layer's knowledge graph — skills, BPMN activities and their lanes, roles, actors, directories — to one JSON-LD document for publication. The export is data; something else draws it.",
        "tags": [
          "kg-export",
          "bootstrap-graph-emission",
          "bootstrap-graph-publication"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/kg-graph-export/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "baseUrl": {
                    "$ref": "#/components/schemas/Url",
                    "description": "Publication base the node IRIs are minted against; a preview passes its own."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write; defaults to `_kg/<stub>.jsonld`, which is build output and gitignored."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "graph": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The written JSON-LD document."
                    },
                    "problems": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Sources that could not be read, counted rather than silently omitted."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/kg-graph-export.jsonld",
        "x-invoke": {
          "shell": "bun run cat kg:export"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "kg-export",
          "bootstrap-graph-emission",
          "bootstrap-graph-publication"
        ]
      }
    },
    "/tools/kg-retrieve-npm": {
      "post": {
        "operationId": "kg-retrieve-npm",
        "summary": "Retrieve a remote Knowledge Graph via npm package or tarball",
        "description": "Retrieve and inspect a remote Knowledge Graph packaged as an npm package or tarball (.tgz), supporting both unhydrated source graph views (authored declarations, skills, schemas) and hydrated materialized graph views (subgraph JSON-LD, metadata indexes, dereferenced graph projections).",
        "tags": [
          "npm-kg-distribution",
          "remote-mount"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/kg-retrieve-npm/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "package": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Package name, npm tarball (.tgz) path, or URL."
                  },
                  "destination": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Directory to unpack or install into."
                  },
                  "view": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "Graph view to inspect/retrieve: 'unhydrated' (source graph), 'hydrated' (materialized JSON-LD/indexes), or 'both'."
                  },
                  "release": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Optional `folio-binary-release/v1` record to verify digest and size against."
                  }
                },
                "required": [
                  "package"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Retrieval status: 'retrieved', 'verified', or 'could-not-determine'."
                    },
                    "summary": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Summary of retrieved graphs, nodes, and assets."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/kg-retrieve-npm.jsonld",
        "x-invoke": {
          "shell": "bun run cat kg:retrieve:npm"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "npm-kg-distribution",
          "remote-mount"
        ]
      }
    },
    "/tools/kg-validate": {
      "post": {
        "operationId": "kg-validate",
        "summary": "Validate a node in the graph",
        "description": "Check one file against the schema for its graph typology. ONE tool for every schema: the kind is resolved from the declared directory that holds the file.",
        "tags": [
          "kg-navigation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/kg-validate/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "path": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The node to check. Its graph typology is resolved from the declared directory that contains it."
                  },
                  "lenient": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Accept partial coverage knowingly: downgrade could-not-determine from an error to a warning."
                  }
                },
                "required": [
                  "path"
                ],
                "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 file — valid, invalid with the failing paths, or could-not-determine with the reason. Exit 0 valid, 1 invalid or undetermined, 2 misuse."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/kg-validate.jsonld",
        "x-invoke": {
          "shell": "bun run cat kg:validate"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "kg-navigation"
        ],
        "x-selection": {
          "when": "Whenever a node's shape matters and you are not in this repository's CI: `tools/` is an INHERITED declaration and `.github/workflows/` is not, so a downstream layer gets this and none of the CI gates.",
          "limits": "It can only check a kind that declares a validator; a node of any other kind comes back UNDETERMINED and it exits non-zero saying so. `bun run cat check:kind-validators` reports the coverage.",
          "cost": "One module import per kind. Nothing to install, no network."
        }
      }
    },
    "/tools/kg-viewer": {
      "post": {
        "operationId": "kg-viewer",
        "summary": "Knowledge graph viewer",
        "description": "Render the layer's published knowledge graph as one page: facets by kind and sub-graph, search, a node's properties, its edges and back-links, and the graph's own gaps — reading the JSON-LD document at the site root rather than carrying a copy.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/kg-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/kg-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat kg:viewer"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/l1-complete-check": {
      "post": {
        "operationId": "l1-complete-check",
        "summary": "L1 source completeness",
        "description": "Is a `library/<bib-slug>/` entry complete as L1 source content? Each requirement is met, unmet, or NOT-DERIVABLE.",
        "tags": [
          "library-ingestion"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/l1-complete-check/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "targetPath": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "One `library/<bib-slug>/` entry. Absent, every entry the declared `library` graph holds."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Per requirement: met, unmet, or `not-derivable` — the third distinguishes a document that CANNOT yield an artefact from one that simply has not. Exit 2 means no `library` graph is declared anywhere, which the script states as \"This is NOT a pass. Treat it as unknown.\""
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/l1-complete-check.jsonld",
        "x-invoke": {
          "shell": "bun run cat check:l1-complete"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "library-ingestion"
        ]
      }
    },
    "/tools/l1-coverage": {
      "post": {
        "operationId": "l1-coverage",
        "summary": "L1 extraction coverage",
        "description": "Of the normative sentences in a publication (the closed marker list of the methodology `l1-coverage` §1), count how many an L1 extraction CAPTURED, how many are EXCLUDED for a fixed-list reason a person signed off, and how many are UNACCOUNTED — per page and in total. Writes the contract's §4 report and exits non-zero below 100% accounted-for.",
        "tags": [
          "l1-coverage"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/l1-coverage/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The publication's body text, page-tagged: `{\"pages\":[{\"page\":n,\"text\":\"…\"}]}` JSON, or plain text with a form feed between pages (what `pdftotext` writes). Headers, references and tables of contents are stripped by the caller."
                  },
                  "captured": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "JSON `[{\"id\",\"text\"}]`: every statement the extraction captured, verbatim."
                  },
                  "exclusions": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "JSON `[{location|text, reason, signedOffBy?, signedOffAt?}]`. An exclusion without `signedOffBy` is a proposal and leaves its sentence unaccounted."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write the report; stdout when absent."
                  }
                },
                "required": [
                  "text",
                  "captured"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "An `l1-coverage-report/v1` JSON report: definitionVersion, matchMethod, source and graph sha256, totals, pages[] and sentences[]. A per-page table goes to stderr."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/l1-coverage.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/l1-coverage.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "l1-coverage"
        ],
        "x-selection": {
          "when": "An L1 extraction of a publication (recommendations, remarks, schedule entries) is about to be reviewed or promoted, and somebody needs to know — rather than assume — that no normative sentence was silently missed.",
          "limits": "Matching is normalised substring, so a paraphrased capture reads as unaccounted. Body-text filtering is the caller's. The marker list is English.",
          "cost": "Reads three files; no network."
        }
      }
    },
    "/tools/library-viewer": {
      "post": {
        "operationId": "library-viewer",
        "summary": "Library viewer",
        "description": "Render each declared library directory — its entries, intakes and avatars — as a page per subject layer, and give every entry its own path IRI (<library>/<instance>/<id>/): a materialized thin shell that loads the entry from the published projection, with its JSON-LD manifest as the alternate.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/library-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  },
                  "scope": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "A scoped site build: the comma-separated instances whose pages this writer writes (the IG and the layer it lands on); every other instance's pages are linked on that layer's own site. Passed by the tools layer's `visualiser-writers.ts` (owner, 2026-11-08, Q-SZ-2 \"B\"). Absent: every instance."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/library-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat library:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/log-message": {
      "post": {
        "operationId": "log-message",
        "summary": "Log a message to the discussion",
        "description": "Write a log line where the human actor will read it: the discussion you are already in. Takes the five required fields and the optional body, and renders them as one entry.",
        "tags": [
          "log-message"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/log-message/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "timestamp": {
                    "$ref": "#/components/schemas/Timestamp",
                    "description": "When it happened, as an ISO-8601 UTC instant."
                  },
                  "actor": {
                    "$ref": "#/components/schemas/Text",
                    "description": "WHO acted. Never the Logger: it receives and records, so it cannot know."
                  },
                  "process": {
                    "$ref": "#/components/schemas/ProcessId",
                    "description": "The process the actor was inside, e.g. initialize-harness."
                  },
                  "task": {
                    "$ref": "#/components/schemas/NodeId",
                    "description": "The step within it, e.g. A_Install."
                  },
                  "message": {
                    "$ref": "#/components/schemas/Text",
                    "description": "What happened, in the one line somebody scanning will read."
                  },
                  "body": {
                    "$ref": "#/components/schemas/Markdown",
                    "description": "The detail — a diff, an error, what was not where it should have been."
                  }
                },
                "required": [
                  "timestamp",
                  "actor",
                  "process",
                  "task",
                  "message"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entry": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "The entry as posted."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/log-message.jsonld",
        "x-invoke": {
          "manual": true
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "log-message"
        ]
      }
    },
    "/tools/lsi-index": {
      "post": {
        "operationId": "lsi-index",
        "summary": "Build the Latent Semantic Indexing index of a prose graph",
        "description": "Build the per-graph LSI index sidecar for every declared prose graph (or the one named): input fingerprint, parameters, dimension summaries, nearest neighbours and near-duplicate findings, never the vectors. Records each run's outcome and input fingerprint, success or failure, as a `folio-tool-run/v1` record.",
        "tags": [
          "lsi-indexing"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/lsi-index/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "Layer declaring the graph, e.g. `cat-harness`."
                  },
                  "graph": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "Graph id within the layer, e.g. `skills`."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "index": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`test/results/lsi/<instance>/<graph>.lsi.json`, and the run record under `test/results/tool-runs/lsi-index/`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/lsi-index.jsonld",
        "x-invoke": {
          "shell": "bun run cat lsi index"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "lsi-indexing"
        ]
      }
    },
    "/tools/lsi-query": {
      "post": {
        "operationId": "lsi-query",
        "summary": "Latent Semantic Indexing over a prose graph",
        "description": "Find units of a declared prose graph (a library, the skills, the beans, docs) that discuss a query in OTHER words — the vocabulary gap lexical search cannot reach. Each hit is labelled lexical+latent or latent only, and the score is a cosine in the latent space, never merged with a lexical result.",
        "tags": [
          "lsi-indexing"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/lsi-query/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The query, in any words, on STDIN — free text never goes on a command line."
                  },
                  "instance": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "Layer declaring the graph, e.g. `cat-harness`."
                  },
                  "graph": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "Graph id within the layer, e.g. `library`."
                  }
                },
                "required": [
                  "text"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Per graph: the top hits by cosine, each marked lexical+latent or latent only."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/lsi-query.jsonld",
        "x-invoke": {
          "shell": "bun run cat lsi query",
          "mcp": {
            "tool": "lsi_query"
          },
          "inProcess": {
            "module": "src/tools/lsi-query.ts"
          }
        },
        "x-mcp-tools": [
          "lsi_query"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "lsi-indexing"
        ]
      }
    },
    "/tools/lsi-viewer": {
      "post": {
        "operationId": "lsi-viewer",
        "summary": "Indexing evidence viewer",
        "description": "Render the Indexing evidence page: for each indexing method, the held papers it rests on and the skills, Tools and processes that apply it, and the indexing skills with no evidence yet; and its Keywords page (`keywords/`), the derived keywords graph as an A–Z index with the six extraction variants side by side and their agreement with headings, author keywords and the glossaries. Index health is the `lsi-indexes` check of `bun run cat health`.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/lsi-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/lsi-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat lsi:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/memory-checkpoint": {
      "post": {
        "operationId": "memory-checkpoint",
        "summary": "Keep where the work stands",
        "description": "Before you stop or hand over, keep where the work stands: what is done, what is next, and anything the next person must know to carry on.",
        "tags": [
          "work-context"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/memory-checkpoint/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "$ref": "#/components/schemas/Markdown",
                    "description": "Where the work stands, in plain words."
                  },
                  "shared": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "true: the memory you share with the other agents working with you. Default: your own memory of this work."
                  }
                },
                "required": [
                  "note"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "kept": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Whether it was kept."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/memory-checkpoint.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "memory_checkpoint"
          },
          "inProcess": {
            "module": "src/tools/memory.ts"
          }
        },
        "x-mcp-tools": [
          "memory_checkpoint"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "work-context"
        ],
        "x-selection": {
          "when": "Before you stop or hand the work over — to record what is done, what is next, and what the next person needs to carry on.",
          "limits": "For stopping or handing over; for a quick note while you are still working, use memory-note.",
          "cost": "In-process call; no install or network."
        }
      }
    },
    "/tools/memory-note": {
      "post": {
        "operationId": "memory-note",
        "summary": "Keep a note on the work",
        "description": "Keep a short note on the work you are doing — what you did, what you decided and why, and what is left open — so it is there when the work is picked up again.",
        "tags": [
          "work-context"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/memory-note/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "$ref": "#/components/schemas/Markdown",
                    "description": "The note, in plain words. One paragraph is plenty."
                  },
                  "shared": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "true: the memory you share with the other agents working with you. Default: your own memory of this work."
                  }
                },
                "required": [
                  "note"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "kept": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Whether it was kept."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/memory-note.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "memory_note"
          },
          "inProcess": {
            "module": "src/tools/memory.ts"
          }
        },
        "x-mcp-tools": [
          "memory_note"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "work-context"
        ],
        "x-selection": {
          "when": "While you are working — to keep a decision, why you made it, or what you tried while it is fresh.",
          "limits": "Leaves a running note, not a hand-over summary; before you stop or hand over, use memory-checkpoint.",
          "cost": "In-process call; no install or network."
        }
      }
    },
    "/tools/memory-recall": {
      "post": {
        "operationId": "memory-recall",
        "summary": "Read what was kept",
        "description": "Read what has been kept about this work so far, oldest first, so you can start where the last person stopped.",
        "tags": [
          "work-context"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/memory-recall/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "shared": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "true: the memory you share with the other agents working with you. Default: your own memory of this work."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entries": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "What was kept, oldest first: when, who, what kind, and the text."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/memory-recall.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "memory_recall"
          },
          "inProcess": {
            "module": "src/tools/memory.ts"
          }
        },
        "x-mcp-tools": [
          "memory_recall"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "work-context"
        ]
      }
    },
    "/tools/merge-guard": {
      "post": {
        "operationId": "merge-guard",
        "summary": "Judge whether a pull request may land",
        "description": "The enforced merge guard: asks GitHub's live facts about one pull request whether it is finished (its checks, its tier, the session that marked it ready) before it reaches its base, and lands it only when every check passes. With `--status` it posts the verdict as the `merge-guard` commit status on the head, which is what the layer's merge-guard workflow does.",
        "tags": [
          "ci-health"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/merge-guard/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pr": {
                    "$ref": "#/components/schemas/Count",
                    "description": "The pull request number."
                  },
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository holding the pull request. Default: the checkout's own."
                  },
                  "merge": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Land the pull request, only if every check passes. Needs `--session`."
                  },
                  "status": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Post the verdict as the `merge-guard` commit status on the head."
                  },
                  "full_tier": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Require the full (release) tier of checks, not the fast tier a draft runs."
                  }
                },
                "required": [
                  "pr"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verdict": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Each check with its verdict; exit 0 when the pull request may land."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/merge-guard.jsonld",
        "x-invoke": {
          "shell": "bun run cat merge:guard"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "ci-health"
        ],
        "x-selection": {
          "when": "Before a pull request lands on its base, by the merge manager or a steward, and on every pull request event through the merge-guard workflow.",
          "limits": "Reads GitHub's live facts about one pull request; it judges no declared graph.",
          "cost": "A few GitHub REST calls."
        }
      }
    },
    "/tools/merge-leftover": {
      "post": {
        "operationId": "merge-leftover",
        "summary": "Merge leftover (has a PR's intent landed?)",
        "description": "After a train merged, compare a PR's head with the base path by path and say whether what it still changes is ONLY generated files, generated README regions, or changes the base already carries (its patch applies in reverse to the base): `landed`, `not-landed` with the authored paths still different, or `could-not-determine`, which is never shown as clean. Only reports; closing the PR stays a steward action.",
        "tags": [
          "merge-conflict-patterns"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/merge-leftover/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "member": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The PR number or branch. On the command line a PR may be pinned as `N:<sha>`."
                  },
                  "base": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The base the train landed on; default `origin/main`."
                  }
                },
                "required": [
                  "member"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "`merge-leftover/v1` on stdout. Exit 0 landed, 1 not-landed, 2 could not determine."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/merge-leftover.jsonld",
        "x-invoke": {
          "shell": "bun run cat merge:leftover"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "merge-conflict-patterns"
        ],
        "x-selection": {
          "when": "After a train lands, for each member PR still open, before the steward decides whether to close it.",
          "limits": "An authored path whose lines the base rewrote after the train reads `not-landed`: the reverse patch no longer applies, and only a person can say whether the rewrite kept the intent.",
          "cost": "One fetch, then one `git diff` and one `git apply --check` per authored path, in a throwaway index. No working tree is touched."
        }
      }
    },
    "/tools/merge-overlap": {
      "post": {
        "operationId": "merge-overlap",
        "summary": "Merge overlap (conflict prediction)",
        "description": "For the open PRs (via `gh`, or a list of branches), report which pairs would conflict: pairwise overlap on AUTHORED paths, with generated paths excluded using the merge-conflict-patterns declaration; which PRs touch a shared declaration (a layer's `<instance>.json`, `roles.json`, `package.json`, `bun.lock`, schemas, BPMN/DMN); and which touch the harness layer's directory or its tools layer's. A PR that could not be measured makes no pair independent. JSON (`merge-overlap/v1`), the conflict-prediction input for composing trains.",
        "tags": [
          "merge-conflict-patterns",
          "coordinate"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/merge-overlap/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "base": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The base each PR is diffed against from its fork point; default `origin/main`."
                  },
                  "branches": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "Branches to compare instead of the open PRs; with none, the open PRs come from `gh`."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "`merge-overlap/v1` on stdout: per member `authored_paths`, `region_paths`, `touches_shared`, the two harness flags; every pair that is not independent, with why."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/merge-overlap.jsonld",
        "x-invoke": {
          "shell": "bun run cat merge:overlap"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "merge-conflict-patterns",
          "coordinate"
        ],
        "x-selection": {
          "when": "Before composing a merge train, and whenever deciding which PRs can land together or must be ordered.",
          "limits": "Paths, not semantics: two PRs that change different files can still interact, which the shared-declaration list only partly covers. A README counts as authored when its prose changed, as a region when only generated regions did.",
          "cost": "One REST listing (`gh api …/pulls`; not `gh pr list`, which is GraphQL) and one `git fetch` of every open head, then a `git diff --name-only` per PR. No working tree is touched."
        }
      }
    },
    "/tools/merge-train": {
      "post": {
        "operationId": "merge-train",
        "summary": "Merge train",
        "description": "Build a train branch from a base SHA: merge each member (a PR number or branch) with `merge-base.ts --no-regen`, refusing — never hand-resolving — a member whose conflicts no declared pattern covers; then one `bun run cat regen`, `check:l1-complete --write`, every check a layer declares `afterMerge` (its declared writer run when red), and `kg:audit:all:check`; then merge `origin/main`, taking main's side of generated conflicts and regenerating once more. Emits a `merge-train-report/v1` JSON report. Never pushes, opens or merges a PR.",
        "tags": [
          "merge-conflict-patterns",
          "prepare-merge"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/merge-train/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "base": {
                    "$ref": "#/components/schemas/CommitSha",
                    "description": "The commit the train branch starts from."
                  },
                  "branch": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The train branch to create; default `merge-train/<base>-<time>`."
                  },
                  "dry-run": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Simulate with `git merge-tree`: classify each member's conflicts against the simulated train and change nothing."
                  },
                  "no-main": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Skip merging `origin/main` into the train."
                  },
                  "members": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "PR numbers or branches, in train order. On the command line a PR may be pinned to the head CI saw as `N:<sha>`."
                  }
                },
                "required": [
                  "base",
                  "members"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "`merge-train-report/v1` on stdout: members merged, refused with reasons and conflicted paths, the checks run, main's merge, and the head. Exit 0 built, 1 needs a person, 2 could not start."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/merge-train.jsonld",
        "x-invoke": {
          "shell": "bun run cat merge:train"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "merge-conflict-patterns",
          "prepare-merge"
        ],
        "x-selection": {
          "when": "The steward has chosen a batch of green, mutually independent PRs (see merge-overlap) and wants one branch that carries them all, regenerated once.",
          "limits": "Each member's merge commit is not proved on its own; the train is proved at its end by one regen. A refused member is left out and reported — handing it back to its owner is the steward's step. It does not push: CI on the train runs only after the steward pushes it.",
          "cost": "One `merge-base.ts` per member (seconds each), then one regen (5-13 min) and the three checks; a second regen if main had generated conflicts."
        }
      }
    },
    "/tools/mesh-authority": {
      "post": {
        "operationId": "mesh-authority",
        "summary": "Validate draft MeSH headings against NLM's authority",
        "description": "Stage three of `skill-pipeline-subject-indexing` for MeSH: look up every candidate heading of a draft (a preferred heading, an entry term, or a descriptor id, with an optional qualifier) in NLM's MeSH authority at id.nlm.nih.gov, current year. Each candidate comes back `resolved` (in the preferred form), `qualifier-not-allowed` (descriptor kept, qualifier dropped), `ambiguous` (options listed for a person) or `not-found` (dropped). It never adds a heading the draft did not propose and never emits one the authority lacks.",
        "tags": [
          "mesh-subject-indexing"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/mesh-authority/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "draft": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A JSON file: `{ \"candidates\": [{ \"label\"?, \"descriptor\"?, \"qualifier\"?, \"why\"? }] }`, in the order stage two ranked them."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print the full report as JSON instead of the review table."
                  }
                },
                "required": [
                  "draft"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "A review table with one row per candidate, or with `--json` the report: `results` per candidate and `validated`, the headings a reviewer sees."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/mesh-authority.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/mesh-authority.ts validate"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "mesh-subject-indexing"
        ],
        "x-selection": {
          "when": "A draft list of MeSH headings from stages one and two of `mesh-subject-indexing` is ready to be checked against the authority.",
          "limits": "Checks existence, preferred form and allowable qualifiers only. It does not judge whether a heading fits the work, and applies none of NLM's rules on heading count or major topics.",
          "cost": "Two or three HTTPS requests per candidate to id.nlm.nih.gov; about a second for a short draft."
        }
      }
    },
    "/tools/methodologies-viewer": {
      "post": {
        "operationId": "methodologies-viewer",
        "summary": "Methodologies viewer",
        "description": "Render the declared methodology graph as one page.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/methodologies-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  },
                  "scope": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "A scoped site build: the comma-separated instances whose pages this writer writes (the IG and the layer it lands on); every other instance's pages are linked on that layer's own site. Passed by the tools layer's `visualiser-writers.ts` (owner, 2026-11-08, Q-SZ-2 \"B\"). Absent: every instance."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/methodologies-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat methodologies:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/mount-from-lock": {
      "post": {
        "operationId": "mount-from-lock",
        "summary": "Replay a committed mount lock with nothing but Node",
        "description": "Lay down every remote mount `index.lock.json` records — each layer fetched at the lock's full SHA (sparse, blob-filtered), each directory verified against its `treeDigest`, a mismatch undone and reported — importing only `node:*`, so it runs on a fresh clone before any layer is present. It never decides what to mount: `remote-mount` writes the lock (and checks trust); this only replays it. Refuses to write over a path with tracked files or bytes that no longer hash to the lock. Exit 0 mounted/current, 1 missing, 2 could-not-determine.",
        "tags": [
          "remote-mount",
          "kg-separation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/mount-from-lock/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root whose lock is replayed. Default: the working directory."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "No network: is every locked mount on disk and intact?"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "outcomes": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Per layer: mounted, current, missing or could-not-determine."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/mount-from-lock.jsonld",
        "x-invoke": {
          "shell": "bun run cat mount:lock"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": true
        },
        "x-satisfies": [
          "remote-mount",
          "kg-separation"
        ],
        "x-selection": {
          "when": "First step of a CI job or session on a checkout whose layers arrive by remote mount, after the lock is committed.",
          "limits": "It lives in cat-harness, which is itself a mounted layer, so it cannot bootstrap a checkout that does not already hold cat-harness. The parent must carry its own dependency-free entry point that fetches this script at the pin (e.g. a `.github/mount-from-lock.sh`) — never call this path directly from a workflow in a repository that mounts cat-harness. A downstream root's `cat` script, `bun .github/cat.ts`, runs that entry point when the layers are missing, so `bun run cat <name>` works from `git clone`.",
          "cost": "One shallow, blob-filtered fetch per locked layer; a few seconds each. `--check` needs no network."
        }
      }
    },
    "/tools/narrative-queue": {
      "post": {
        "operationId": "narrative-queue",
        "summary": "What narratives are waiting on a person",
        "description": "List the agent-drafted narratives awaiting human confirmation, numbered, with the numbered rejection reasons beside them. The queue is the only place a draft's state is visible before someone accepts it.",
        "tags": [
          "library-ingestion"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/narrative-queue/"
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "queue": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Every narrative awaiting a person, NUMBERED, with its subject, its text and its file — then the two commands that act on a number, then the rejection reasons, also numbered. Numbered because the person this is for has very limited hand function, so every action is a selection, not a typed sentence (`interaction-modality`'s `low-dexterity` profile)."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/narrative-queue.jsonld",
        "x-invoke": {
          "shell": "bun run cat narratives"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "library-ingestion"
        ],
        "x-selection": {
          "when": "To find out what is waiting on a person, or how a person confirms a narrative.",
          "limits": "IT ONLY LISTS. Acting on a number is `bun run cat narratives:confirm <n>` or `bun run cat narratives:reject <n> --why <r>`, and both REFUSE outside a terminal: `reviewer()` throws with \"Confirming is a PERSON's act; an agent running this would be recorded as one\". The refusal is needed because `git config user.name` is the agent's, so an agent's confirmation would be recorded as a person's. So this node does not offer the confirming arms: an agent may read the queue and must not answer it. A rejection with no reason is refused too, not defaulted, because a reason-less rejection lets the next agent redraft the identical thing.",
          "cost": "Reads the narrative-bearing files under the declared graph. No network."
        }
      }
    },
    "/tools/navbar-include": {
      "post": {
        "operationId": "navbar-include",
        "summary": "Write the site sidebar's harness navbar include",
        "description": "Render `_includes/generated/navbar-footer.html` from `docs/_data/harness.json` with the same renderer every railed page uses. With `--instance`, render the navbar of an IG repository's OWN site instead — that layer first, then what it needs; its own pages at this site's root, every other link to the main site at `--link-root` — into the shell that site is built from.",
        "tags": [
          "harness-tiles"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/navbar-include/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if the committed include is stale; write nothing."
                  },
                  "instance": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "The layer whose own site this navbar is for."
                  },
                  "link-root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "With `--instance`: the main site's URL, for every link that is not this layer's own."
                  },
                  "title": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "With `--instance`: the label the navbar's home row carries."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "With `--instance`: where to write the include (the shell's `_includes/generated/navbar-footer.html`)."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "include": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The include written, or `up to date`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/navbar-include.jsonld",
        "x-invoke": {
          "shell": "bun run cat navbar:include"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "harness-tiles"
        ]
      }
    },
    "/tools/node-kind-pages": {
      "post": {
        "operationId": "node-kind-pages",
        "summary": "Node kind pages",
        "description": "Render a page for every node kind, every harness holding nodes of it, and every node, under /<locale>/<declaring>/<kind>/.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/node-kind-pages/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/node-kind-pages.jsonld",
        "x-invoke": {
          "shell": "bun run cat node-kind:pages"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/node-view-coverage": {
      "post": {
        "operationId": "node-view-coverage",
        "summary": "Does every node have an IRI, a .jsonld, a page and a row?",
        "description": "For each node a declared directory holds, per layer × folder × kind: whether it has an IRI in its layer's export (extensionless), its JSON-LD at `<iri>.jsonld` (and `.json` where its source is JSON), a view page at `<locale>/<harness>/<vis>/<instance>/<id>/`, and a row on its folder page that links to it; plus the folder page's dead links and raw-repository links, and whether a viewer is declared. Folder pages are read with their data files, so rows drawn by JavaScript count. Writes `node-view-coverage/v1`, one file per layer, under `test/results/node-views/`.",
        "tags": [
          "kg-viewer"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/node-view-coverage/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "`--site <dir>`: a built site (`_site`, or a preview's `branches/<slug>/`). With `--site-url`, the URL that directory is served at."
                  },
                  "base": {
                    "$ref": "#/components/schemas/Url",
                    "description": "`--base <url>`: a live site to probe instead of a directory. Optional; one of `site` or `base` is needed, or pages, rows and links are unknown."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "`--check` (`node-views:judge`): write nothing and judge. Exit 0 when no finding is new, 1 when one is new against the baseline, 2 when the run could not ask (JUDGEMENT_EXIT)."
                  },
                  "against": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "`--against <ref>`: the `qa-reports` entry to judge against (`main`, `main/<sha>`, `pr/<n>/<sha>`). Absent, the working copy; a missing baseline is UNKNOWN and not gated."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`<layer qa home>/node-views/<layer>.node-views.qa.json` (`node-view-coverage/v1`), and a Markdown summary table on stdout. Always exit 0: reports, never gates. Published to `qa-reports` by `qa:publish`, and read by each layer's QA page."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/node-view-coverage.jsonld",
        "x-invoke": {
          "shell": "bun run cat node-views:report"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "kg-viewer"
        ],
        "x-selection": {
          "when": "After a site build, before the review of a preview: to see which nodes of which folders have no IRI, no .jsonld, no page or no row, and which folder links are dead or point at the raw repository.",
          "limits": "It needs a built site or a live base; without one, pages, rows and links are unknown, never 0. Rows drawn in the browser are read from the folder's data files (`assets/<vis>/*.json`, inline JSON), not by running the page, so a row built from another source is not seen. The census per kind is a declared file rule (`CENSUS_RULES`) or the layer's export, recorded on each row. Counts past `--probe-limit` are unknown.",
          "cost": "Building each layer's export in memory (minutes over a whole composition), then one request per node page and IRI: thousands against a live base."
        }
      }
    },
    "/tools/npm": {
      "post": {
        "operationId": "npm",
        "summary": "Package manager and registry client for npm and GitHub Packages",
        "description": "Package, publish, inspect, and retrieve npm packages and Knowledge Graphs distributed as tarballs or packages from npm registry or GitHub Packages.",
        "tags": [
          "npm-kg-distribution",
          "remote-mount"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/npm/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "args": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Arguments passed to npm (e.g. 'pack', 'publish', 'view')."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stdout": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Standard output from npm invocation."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/npm.jsonld",
        "x-invoke": {
          "shell": "npm"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "node"
          ],
          "network": true
        },
        "x-satisfies": [
          "npm-kg-distribution",
          "remote-mount"
        ]
      }
    },
    "/tools/ns-vocabulary": {
      "post": {
        "operationId": "ns-vocabulary",
        "summary": "Namespace vocabulary",
        "description": "Emit the folio namespace as a document that dereferences — one node per class and property, each with an @id, a type, a label and a definition, so a consumer holding only the JSON-LD can resolve any term it meets.",
        "tags": [
          "kg-export"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/ns-vocabulary/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "layer": {
                    "$ref": "#/components/schemas/NamespaceLayer",
                    "description": "Emit one namespace layer — `bootstrap` for the layer that must resolve before anything else does."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write; defaults under `_kg/`, which is build output."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "vocabulary": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The written namespace document."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ns-vocabulary.jsonld",
        "x-invoke": {
          "shell": "bun run cat ns:export"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "kg-export"
        ]
      }
    },
    "/tools/open-work-lookup": {
      "post": {
        "operationId": "open-work-lookup",
        "summary": "Does a path or bean exist on main or any open PR",
        "description": "Answer whether a path, a path prefix or a bean id appears on a repository's default branch or on the head of any of its open pull requests, and where: the PR number, head branch, first commit author and creation time. A path or prefix matches files at the default branch and files each open PR changes; a bean id matches PR titles, bodies and head branch names. Repositories or PRs that could not be read are listed, so an empty answer is never mistaken for absence.",
        "tags": [
          "bean-coordination"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/open-work-lookup/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "path": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "An exact repository path."
                  },
                  "prefix": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A directory or file-name prefix; every path under or starting with it matches."
                  },
                  "bean": {
                    "$ref": "#/components/schemas/BeanId",
                    "description": "A bean id, full or short."
                  },
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "Repositories to search. Repeat. Defaults to the current checkout's origin."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Emit `definitions.lookup` as JSON."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lookup": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "One line per hit: repository, default branch or PR number, head, author, when, and what matched. Then what could not be read. Exactly one of path, prefix or bean must be given. With --json, `definitions.lookup` of schemas/skills/bean-drain/output.schema.json."
                    },
                    "result": {
                      "$ref": "#/components/schemas/OpenWorkLookup",
                      "description": "With --json, the hits as one `OpenWorkLookup` record, with what could not be read. Programs read this; people read `lookup`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/open-work-lookup.jsonld",
        "x-invoke": {
          "shell": "bun run cat lookup:open-work",
          "inProcess": {
            "module": "scripts/open-work-lookup.ts"
          }
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "bean-coordination"
        ],
        "x-selection": {
          "when": "Before starting work that a sibling may already have in flight, and before publishing that a path or a piece of work does not exist.",
          "limits": "Open PRs only, not unpushed local branches or closed PRs. It uses the GitHub REST API, not GraphQL, because cloud sessions are refused GraphQL. A PR's changed-file list is capped by the API at 3000 files; a bigger PR is listed under unread rather than guessed. For the current checkout alone, `git show origin/main:<path>` in its own command is enough.",
          "cost": "One paged REST listing of open PRs per repository, plus one files listing per open PR for a path or prefix query."
        }
      }
    },
    "/tools/openapi-ingest-rendered": {
      "post": {
        "operationId": "openapi-ingest-rendered",
        "summary": "OpenAPI ingest from a published spec",
        "description": "Ingest the OpenAPI documents a layer's `cat-openapi.config.json` lists under `rendered` by fetching each published spec URL (https), verbatim, with a provenance recording the URL, when it was fetched and the document's sha256 — a URL has no commit, so the digest pins the bytes. A failed fetch or bytes that are not OpenAPI 3 write nothing and never replace a held copy.",
        "tags": [
          "library-ingestion"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/openapi-ingest-rendered/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root holding `cat-openapi.config.json` and the declared `openapi` directory."
                  },
                  "only": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "Ingest just this document id."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "documents": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`<id>.openapi.json` and `<id>.source.json` per rendered document, in the declared `openapi` directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/openapi-ingest-rendered.jsonld",
        "x-invoke": {
          "shell": "bun run cat openapi:ingest:rendered"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "library-ingestion"
        ],
        "x-selection": {
          "when": "The spec is only available as a published document (a rendered IG or docs site), or the repository should stay remote while its spec is ingested.",
          "limits": "Reads what the publisher serves at fetch time; whether it has changed since is answered only by fetching again and comparing digests.",
          "cost": "One https GET and one JSON parse per document."
        }
      }
    },
    "/tools/openapi-ingest-source": {
      "post": {
        "operationId": "openapi-ingest-source",
        "summary": "OpenAPI ingest from source",
        "description": "Ingest the OpenAPI documents a layer's `cat-openapi.config.json` lists under `documents` from a local checkout of their repository, read AT a branch, tag or commit (`git show`), verbatim, with a provenance recording the resolved commit and the document's sha256. `--check` verifies the committed copies offline.",
        "tags": [
          "library-ingestion"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/openapi-ingest-source/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root holding `cat-openapi.config.json` and the declared `openapi` directory."
                  },
                  "source": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A local checkout of the documents' repository."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch, tag or commit to read each document at. Default: the checkout's HEAD."
                  }
                },
                "required": [
                  "instance",
                  "source"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "documents": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`<id>.openapi.json` and `<id>.source.json` per document, in the declared `openapi` directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/openapi-ingest-source.jsonld",
        "x-invoke": {
          "shell": "bun run cat openapi:ingest"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": false
        },
        "x-satisfies": [
          "library-ingestion"
        ],
        "x-selection": {
          "when": "A layer holds an OpenAPI spec whose source is a repository (e.g. a gateway's spec file) and the KG should describe it, pinned to a commit.",
          "limits": "Reads a LOCAL checkout; fetching the repository is the caller's. A document that is not OpenAPI 3 fails rather than being written.",
          "cost": "One git read and one JSON parse per document. No network."
        }
      }
    },
    "/tools/openapi-pages": {
      "post": {
        "operationId": "openapi-pages",
        "summary": "OpenAPI viewer",
        "description": "Render every OpenAPI document a layer's `openapi` graph holds at the visualiser's route: a hub, a page per layer listing its documents, and a page per document and per operation, drawn from the document copied beside them.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/openapi-pages/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/openapi-pages.jsonld",
        "x-invoke": {
          "shell": "bun run cat openapi:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/pack-tarball": {
      "post": {
        "operationId": "pack-tarball",
        "summary": "Package layer into an npm tarball and record binary release",
        "description": "Build an npm tarball (.tgz) of a layer using `bun pm pack`, compute its size and SHA-256 digest, and record it as a `folio-binary-release/v1` state node.",
        "tags": [
          "npm-kg-distribution"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/pack-tarball/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Layer root containing package.json (default: cwd)."
                  },
                  "destination": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Directory to save the tarball and release record."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Path to write the folio-binary-release/v1 JSON record."
                  },
                  "repository": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "Repository owner/repo for the release origin."
                  },
                  "release-url": {
                    "$ref": "#/components/schemas/Url",
                    "description": "Public URL where the tarball is published/hosted."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Emit the folio-binary-release/v1 JSON record to stdout."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "release": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "Path to the created folio-binary-release/v1 record."
                    },
                    "tarball": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "Path to the created .tgz tarball."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/pack-tarball.jsonld",
        "x-invoke": {
          "shell": "bun run cat pack:tarball"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "npm-kg-distribution"
        ]
      }
    },
    "/tools/package-exports": {
      "post": {
        "operationId": "package-exports",
        "summary": "A package's exports are its declared, shipped code directories",
        "description": "Derive a package's `package.json` `exports` from the layer declaration beside it: a directory declared with graph typology `code` (top level or from within) AND named in `files` is exported as `./<dir>/*.js → ./<dir>/*.ts` and `./<dir>/* → ./<dir>/*`; a declared code directory that is not shipped (`test/`) stays private. Keys without `*` are named entry points, kept as written and checked to point into an exported directory. Without `--write` it reports each difference; with it, it rewrites `exports`. Exit 0 in agreement, 1 drift, 2 cannot tell (no declaration, no `package.json`, or no shipped code directory).",
        "tags": [
          "kg-separation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/package-exports/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer whose package to check. Default: the layer holding the script."
                  },
                  "write": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Rewrite `exports` to the derived set."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "findings": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Each difference between the written and the derived `exports`, or the directories exported and those declared but not shipped."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/package-exports.jsonld",
        "x-invoke": {
          "shell": "bun run cat check:package-exports"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "kg-separation"
        ]
      }
    },
    "/tools/package-release-manual": {
      "post": {
        "operationId": "package-release-manual",
        "summary": "Package release by hand",
        "description": "A person follows the package-release skill: computes the bump, writes the CHANGELOG entry, tags `<package>-v<version>`, and creates the release on the host. The same four steps with nothing to configure.",
        "tags": [
          "npm-kg-distribution"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/package-release-manual/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "package": {
                    "$ref": "#/components/schemas/PackageName",
                    "description": "The package being released."
                  },
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "owner/name of the repository the release is made in; the current one when absent."
                  }
                },
                "required": [
                  "package"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tag": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The tag created, `<package>-v<version>`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/package-release-manual.jsonld",
        "x-invoke": {
          "manual": true
        },
        "x-install": {
          "none": true
        },
        "x-requires": {},
        "x-satisfies": [
          "npm-kg-distribution"
        ],
        "x-selection": {
          "when": "A first release, a rare one, or a repository whose commit messages carry no conventional prefixes.",
          "limits": "Every step is a person's, so each is a place to slip; the skill's rules (build first, no reused version) are checked by nobody.",
          "cost": "A few minutes of a person's time per release."
        }
      }
    },
    "/tools/package-release-workflow": {
      "post": {
        "operationId": "package-release-workflow",
        "summary": "Release package via GitHub Actions release workflow",
        "description": "Build, tag, and publish an npm package tarball to GitHub Releases and GitHub Packages registry via workflow_dispatch across any repository.",
        "tags": [
          "npm-kg-distribution"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/package-release-workflow/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "package": {
                    "$ref": "#/components/schemas/PackageName",
                    "description": "The package being released. Default: root package in the target repository."
                  },
                  "version": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The semver version string to release (e.g. '0.1.0')."
                  },
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "Target repository full name (e.g. 'litlfred/cat-harness', 'litlfred/bootstrap-tools'). If omitted, runs in the current repository."
                  },
                  "workflow": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The workflow file to trigger (default: 'release-npm.yml')."
                  }
                },
                "required": [
                  "version"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tag": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The tag created by the workflow, e.g. `<package>-v<version>` or `v<version>`."
                    },
                    "status": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Workflow dispatch status and run URL."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/package-release-workflow.jsonld",
        "x-invoke": {
          "shell": "gh workflow run release-npm.yml"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "npm-kg-distribution"
        ]
      }
    },
    "/tools/pages-index": {
      "post": {
        "operationId": "pages-index",
        "summary": "Published-paper index page",
        "description": "Write the gh-pages `index.html` for a built paper: a Paper tab embedding the PDF and, when given, a Visualizer tab, with download links and the build's branch and commit.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/pages-index/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "outputHtml": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write index.html."
                  },
                  "paperEmbed": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The file the Paper tab embeds, typically the PDF."
                  },
                  "pdf": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The PDF filename used in download links."
                  },
                  "md": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A Markdown rendering to link, when there is one."
                  },
                  "visualizer": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The visualizer page for the second tab."
                  },
                  "branch": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch the build is from."
                  },
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "owner/repo, for links back to the source."
                  },
                  "sha": {
                    "$ref": "#/components/schemas/CommitSha",
                    "description": "The commit the build is from."
                  }
                },
                "required": [
                  "outputHtml",
                  "paperEmbed",
                  "pdf"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "index": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The written index.html."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/pages-index.jsonld",
        "x-invoke": {
          "shell": "python3 .github/scripts/generate-index.py"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "python3"
          ],
          "network": false
        },
        "x-satisfies": [
          "docs-generation"
        ]
      }
    },
    "/tools/pages-publish": {
      "post": {
        "operationId": "pages-publish",
        "summary": "GitHub Pages publish",
        "description": "Push a built directory to the `gh-pages` branch, where it is served. How the knowledge graph and its schema reach a URL.",
        "tags": [
          "kg-export",
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/pages-publish/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "directory": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The built tree to publish."
                  },
                  "baseUrl": {
                    "$ref": "#/components/schemas/Url",
                    "description": "Publication base; a preview passes its own."
                  }
                },
                "required": [
                  "directory"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "$ref": "#/components/schemas/Url",
                      "description": "Where the tree is served."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/pages-publish.jsonld",
        "x-invoke": {
          "shell": "bun run cat site:workflow publish"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": true
        },
        "x-satisfies": [
          "kg-export",
          "docs-generation"
        ]
      }
    },
    "/tools/pdf-cover": {
      "post": {
        "operationId": "pdf-cover",
        "summary": "PDF page raster",
        "description": "Render one page of a PDF to a PNG — the thumbnail a repository listing shows — and print the provenance a catalogue needs to record it as DERIVED: source, digest, page, geometry, renderer.",
        "tags": [
          "asset-extraction"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/pdf-cover/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pdf": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The PDF to render from. Its bytes must be here; nothing is fetched."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The PNG to write."
                  },
                  "page": {
                    "$ref": "#/components/schemas/Count",
                    "description": "1-based page to render, default 1. Asking for a page past the end is refused, not clamped."
                  },
                  "width": {
                    "$ref": "#/components/schemas/Count",
                    "description": "Output width in pixels, default 300. `Count` admits zero and a zero width does not; the script refuses it rather than writing a 0x0 PNG, which is the tighter bound stated at the port as `CountSchema` asks. Height follows the page's own aspect and is never forced."
                  },
                  "checkOnly": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write nothing; exit non-zero if the target differs from what would be written."
                  }
                },
                "required": [
                  "pdf",
                  "out"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "facts": {
                      "$ref": "#/components/schemas/Text",
                      "description": "With `--json`: source path and sha256, page, page count, point geometry, pixel geometry, output bytes and sha256, media type, renderer version. Everything a provenance record needs and nothing it has to guess."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/pdf-cover.jsonld",
        "x-invoke": {
          "shell": "bun run cat pdf:cover"
        },
        "x-install": {
          "cli": "pip install pymupdf"
        },
        "x-requires": {
          "runtime": [
            "python3",
            "pymupdf"
          ],
          "network": false
        },
        "x-satisfies": [
          "asset-extraction"
        ],
        "x-selection": {
          "when": "A listing needs a cover and the bytes are already held. It renders page 1 by default and calls that the cover, because page 1 is a determined answer and \"the cover\" is not — the same choice `pdf-pages.py` makes about sections.",
          "limits": "It decides nothing beyond the raster. WHICH documents get a cover, where the file lands, and what the catalogue must say about the derivation are the catalogue's to declare — see the content core's `scripts/gen-covers.ts`, which reads them from a layer's catalogue and refuses to write bytes for a THUMBNAIL that does not declare itself derived. It also cannot tell you whether the page it rendered IS the cover; it can only tell you it is page 1.",
          "cost": "One PyMuPDF wheel, no network at run time, and a few milliseconds per page. Deterministic — identical input gives identical bytes, which is what lets a caller gate on `--check` rather than re-deciding."
        }
      }
    },
    "/tools/pdf-viewer-embed": {
      "post": {
        "operationId": "pdf-viewer-embed",
        "summary": "Embed a PDF inline in a page",
        "description": "Print the HTML fragment that shows a PDF in the installed viewer: a lazily loaded frame whose address is derived from the page's own location (so one page works at the site root, under a project base and under a staging preview), plus plain open and download links that work without it.",
        "tags": [
          "pdf-inline-viewer"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/pdf-viewer-embed/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "spec": {
                    "$ref": "#/components/schemas/Text",
                    "description": "One JSON object: `src` (the PDF's URL, which must fall under a prefix `pdf-viewer-install` was given, or the viewer refuses it on screen), `title` (what the document is; the frame's accessible name), `route` (a regular expression over the page's pathname whose group 1 is the site root — the `folio-mount.ts` convention) and optionally `page` (open at this 1-based page). On stdin because a title and a regular expression are free text."
                  }
                },
                "required": [
                  "spec"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "fragment": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The HTML fragment on stdout. TypeScript callers import `embed` from the module that implements this Tool instead."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/pdf-viewer-embed.jsonld",
        "x-invoke": {
          "shell": "bun run cat pdf:viewer --embed"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "pdf-inline-viewer"
        ],
        "x-selection": {
          "when": "A generated page should let a reader search, page through, print or download a PDF without leaving it. Only for a document whose publication gates permit linking it: an embed is a link that also renders.",
          "limits": "It renders PDFs only. It cannot tell whether the site it lands on had the viewer installed; when it did not, or the page is off the route, the frame says so and the plain links still work.",
          "cost": "Nothing until the reader scrolls to it; then the viewer and worker (~3 MB, cached after the first) and the PDF itself."
        }
      }
    },
    "/tools/pdf-viewer-install": {
      "post": {
        "operationId": "pdf-viewer-install",
        "summary": "Install the inline PDF viewer into a built site",
        "description": "Download the pinned pdf.js release (legacy build), verify its SHA-256, copy the parts a site needs into `<site>/assets/vendor/pdfjs/`, and add the shim that opens `?src=` only for the allowlisted URL prefixes or the site's own origin. Nothing is committed: the viewer exists only in the built site.",
        "tags": [
          "pdf-inline-viewer"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/pdf-viewer-install/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The built site directory, `_site` in both site workflows."
                  },
                  "allow": {
                    "$ref": "#/components/schemas/Url",
                    "description": "An https URL prefix the viewer may open, ending in `/`. Repeat the flag for more than one. `same-origin-only` is the explicit way to allow none — an omitted flag is a usage error, because a viewer that refuses every CDN document would otherwise ship green."
                  },
                  "zip": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A local copy of the release zip, for offline runs and tests. Its hash is checked exactly as a download's would be."
                  }
                },
                "required": [
                  "site",
                  "allow"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "$ref": "#/components/schemas/Text",
                      "description": "One line on stdout: version, destination, file count, and the prefixes it will open. Exit 2 on a usage error; a hash mismatch or a release missing a kept path throws, refusing the install."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/pdf-viewer-install.jsonld",
        "x-invoke": {
          "shell": "bun run cat pdf:viewer"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "unzip"
          ],
          "network": true
        },
        "x-satisfies": [
          "pdf-inline-viewer"
        ],
        "x-selection": {
          "when": "A site build that publishes pages carrying `pdf-viewer-embed` fragments. Run it after the site is assembled and before any pass that walks every page.",
          "limits": "It installs one pinned version and nothing else: moving the pin is `upstream-version-adoption`, with the hash re-measured. It does not decide which PDFs may be shown — the allowlist bounds where the viewer will FETCH from, and a page's publication gates decide whether a page embeds a document at all.",
          "cost": "One ~7 MB download per build and ~12 MB (404 files) added to the built site. Not committed, so no clone cost."
        }
      }
    },
    "/tools/pin-actions": {
      "post": {
        "operationId": "pin-actions",
        "summary": "Pin third-party GitHub Actions to full commit SHAs",
        "description": "Rewrite every third-party `uses: owner/repo@ref` outside the declared staging-only workflows to `@<full commit SHA> # <ref>`, so Dependabot keeps the pair current. A tag resolves to its PEELED commit (an annotated tag's object is never pinned), else a branch head, by `git ls-remote` with argv. A ref that resolves to nothing, or to more than one commit, is refused and reported, never guessed. This repository's own reusable workflows are first-party and left alone. Idempotent.",
        "tags": [
          "security"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/pin-actions/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dry-run": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Report what would be pinned and write nothing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pinned": {
                      "$ref": "#/components/schemas/Count",
                      "description": "uses: lines pinned, per workflow, with every refused ref named; exit 1 when any is refused."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/pin-actions.jsonld",
        "x-invoke": {
          "shell": "bun run cat actions:pin"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": true
        },
        "x-satisfies": [
          "security"
        ]
      }
    },
    "/tools/pin-spdx-license-list": {
      "post": {
        "operationId": "pin-spdx-license-list",
        "summary": "Snapshot the SPDX License List at its pinned version",
        "description": "Read `json/licenses.json` and `json/exceptions.json` from a copy of github.com/spdx/license-list-data at the pinned tag and write `cat-harness/external-schemas/spdx-license-list.terminology.json` (`folio-pinned-terminology/v1`): every licence and exception id with its name and deprecated flag — the offline, version-fixed list `check:source-licence` validates a `licence.json` id against.",
        "tags": [
          "vocabulary-authority"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/pin-spdx-license-list/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "licenseListCheckout": {
                    "$ref": "#/components/schemas/FilesystemPath",
                    "description": "A copy of github.com/spdx/license-list-data at tag `v<version>`, passed as `--from`. Named for what it is rather than `from`: with the same name it would share `pin-ig-terminology`'s signature and be DERIVED as its substitute, which it is not — an IG clone and a licence list are different inputs (`deriveAlternatives`). Refused unless both files declare the pin's `licenseListVersion`."
                  }
                },
                "required": [
                  "licenseListCheckout"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "snapshot": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`folio-pinned-terminology/v1`: the version, the source, and every `spdx-license#<id>` / `spdx-exception#<id>` with its name, sorted; `deprecated: true` where the List marks it."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/pin-spdx-license-list.jsonld",
        "x-invoke": {
          "shell": "bun run cat spdx:pin --from <license-list-data checkout>"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "vocabulary-authority"
        ],
        "x-selection": {
          "when": "A licence id must be checked against a fixed, named edition of the SPDX License List rather than against whatever spdx.org serves today.",
          "limits": "Ids, names and the deprecated flag only — not licence texts, URLs or OSI/FSF flags. The version comes from the pin record, never from this script; refreshing means moving the pin first.",
          "cost": "Two JSON files (~380 KB) fetched once by hand; the ~105 KB snapshot is committed, so nothing runs at check time."
        }
      }
    },
    "/tools/processes-viewer": {
      "post": {
        "operationId": "processes-viewer",
        "summary": "Processes viewer",
        "description": "Render the declared BPMN processes as an index page and one page per diagram.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/processes-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  },
                  "scope": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "A scoped site build: the comma-separated instances whose pages this writer writes (the IG and the layer it lands on); every other instance's pages are linked on that layer's own site. Passed by the tools layer's `visualiser-writers.ts` (owner, 2026-11-08, Q-SZ-2 \"B\"). Absent: every instance."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/processes-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat processes:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/public-comment-changesets": {
      "post": {
        "operationId": "public-comment-changesets",
        "summary": "Public-comment change-sets",
        "description": "Bring a public review's change-sets back in line with GitHub: open the primary issue of each change-set somebody has engaged with, link the other issues that discuss it, and re-render each issue's change-set section from its `changesets/CS-*.json` record. The nightly half of what the folio's public-comment workflow does on each issue event (`github`); `check` validates the records without writing.",
        "tags": [
          "public-comment"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/public-comment-changesets/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "operation": {
                    "$ref": "#/components/schemas/ChangeSetAction",
                    "description": "The command: `reconcile` (the nightly run), `check` (validate the records, write nothing) or `github` (one issue event, as the workflow does)."
                  },
                  "store": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The record's directory in the repository. Default `review/public-comment`."
                  }
                },
                "required": [
                  "operation"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "changesets": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The updated `changesets/CS-*.json` records under the store; the issues are updated on GitHub."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/public-comment-changesets.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/public-comment-changesets.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "gh"
          ],
          "network": true
        },
        "x-satisfies": [
          "public-comment"
        ],
        "x-skill-contracts": {
          "public-comment.input": {
            "$ref": "#/components/schemas/skill.public-comment.input"
          },
          "public-comment.output": {
            "$ref": "#/components/schemas/skill.public-comment.output"
          }
        },
        "x-selection": {
          "when": "Change-set records and their GitHub issues may have drifted: a recommendation made from the CLI, an issue edited by hand, or a missed workflow run.",
          "limits": "Writes only under the store and to issues of the current repository. One run at a time, like the workflow it backs.",
          "cost": "Seconds plus one GitHub API call per change-set that has issues."
        }
      }
    },
    "/tools/publish-extracted-statements": {
      "post": {
        "operationId": "publish-extracted-statements",
        "summary": "Publish extracted statements with source links",
        "description": "Render each declared page (a `folio-statement-page/v1` spec naming `folio-extracted-statements/v1` lists) as Markdown: every statement extracted from a library source, verbatim, with its kind and status, linked to its library entry and to the section it came from, labelled in the source's own unit (\"Catch up schedule, slide 7\"). A statement whose source does not resolve fails the run and nothing is written. `--check` fails when a committed page is stale.",
        "tags": [
          "publish-extracted-statements"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/publish-extracted-statements/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "page": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A `folio-statement-page/v1` spec (`schemas/extracted-statement.ts`): the statement lists to publish, the page to write, its title and introduction, the library viewer's and the sources' URL prefixes, and the content type's table look. Repeat the flag for several pages. A spec, not flags, because those are free text."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Compare instead of writing: exit 1 when a page is stale."
                  },
                  "instance-root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The citing instance, against which a source naming no instance resolves; the repository root when absent."
                  }
                },
                "required": [
                  "page"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "page": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "A generated Markdown page, one table per list: Id, Statement, Kind, Status, Source."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/publish-extracted-statements.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/publish-extracted-statements.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "publish-extracted-statements"
        ],
        "x-selection": {
          "when": "Source documents were added to a folio's working artifact (ingestion promoted an entry, or authoring took up a source) and the statements extracted from them must be readable with a link to where each came from, in the artifact and in the shared viewer.",
          "limits": "It renders what a collector hands it; turning a folio's own extraction format into a statement list is the collector's job. Pages and slides resolve to a section; a page several sections start on names only the page.",
          "cost": "Reads the lists and each entry's structure.json; no network."
        }
      }
    },
    "/tools/publish-gh-pages": {
      "post": {
        "operationId": "publish-gh-pages",
        "summary": "Publish a built site to gh-pages as a full replace",
        "description": "Lay a built `_site` onto a `gh-pages` checkout as a FULL REPLACE and push it, keeping the open pull requests' staging previews: each attempt re-reads the branch, re-runs restore-staging and keep-shared-payloads against what is on it now, replaces the tree, commits `docs(gh-pages): site from <sha>` and pushes. A rejected push is rebuilt, never rebased (a rebase would re-apply the replace over a preview a sibling just deployed), up to three attempts. A restore that cannot read the branch stops the publish. A site that matches the branch is a no-op, not a failure. It publishes and does not verify: the workflow's verify step runs after it.",
        "tags": [
          "render-kg-to-cdn"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/publish-gh-pages/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The built site to publish (env SITE)."
                  },
                  "state": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "restore-staging's record file; keep-shared-payloads keeps its directory at `<state>.keep` (env STATE)."
                  },
                  "commit": {
                    "$ref": "#/components/schemas/CommitSha",
                    "description": "The commit the site was built from, named in the pages commit message (env COMMIT_SHA)."
                  },
                  "pagesDir": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A git checkout whose `origin` holds the `gh-pages` branch (env PAGES_DIR)."
                  }
                },
                "required": [
                  "site",
                  "state",
                  "commit",
                  "pagesDir"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "$ref": "#/components/schemas/Text",
                      "description": "`published on attempt <n>`, or `nothing to publish`; any other exit is a publish that did not happen."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/publish-gh-pages.jsonld",
        "x-invoke": {
          "shell": "bun run cat pages:publish"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bash",
            "bun",
            "git"
          ],
          "network": true
        },
        "x-satisfies": [
          "render-kg-to-cdn"
        ],
        "x-selection": {
          "when": "The deploy step of a site publish: after the site is built and checked, to replace the live `gh-pages` tree without dropping the previews on it.",
          "limits": "A full replace of the whole branch. A branch preview (`branches/<branch>/`) is published by the staging route, which replaces only its own directory.",
          "cost": "A shallow fetch, a copy of the site and a push, repeated on a lost race."
        }
      }
    },
    "/tools/qa-sweep": {
      "post": {
        "operationId": "qa-sweep",
        "summary": "QA sweep",
        "description": "Run every registered criterion over the blocks under a path and write a per-block QA sidecar. A sidecar rather than a console report, because a printed verdict cannot distinguish \"never checked\" from \"checked and clean\".",
        "tags": [
          "content-test"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/qa-sweep/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "targetPath": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The content root to sweep. Absent, the command exits 2 with its usage — could-not-determine, not a clean sweep."
                  },
                  "dryRun": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Report what would change without writing sidecars."
                  },
                  "ci": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail on a finding rather than recording it."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag"
                  }
                },
                "required": [
                  "targetPath"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sidecars": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "One `<block>.qa.json` per block, committed beside its subject."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/qa-sweep.jsonld",
        "x-invoke": {
          "shell": "bun run cat qa:sweep"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "content-test"
        ],
        "x-skill-contracts": {
          "content-test.input": {
            "$ref": "#/components/schemas/skill.content-test.input"
          },
          "content-test.output": {
            "$ref": "#/components/schemas/skill.content-test.output"
          }
        }
      }
    },
    "/tools/rail-standalone-pages": {
      "post": {
        "operationId": "rail-standalone-pages",
        "summary": "Give every page Jekyll did not lay out the folio-assistant navbar",
        "description": "A LAST pass over the finished site: inject the shared navbar (`lib/navbar.ts`, the same component the site sidebar draws) into every page that carries none — standalone viewers, generated layer pages, and each IG site built by `stage-ig-sites`. A page under an `igSite` layer's route is railed as THAT layer's page (its name, mark and graphs); a page may declare its own section (`data-fa-visualiser-nav`) and its label (`fa-visualiser-label`). Mount routes are left to the mount pass, and a page that declines (`folio-navbar: none`) is left bare.",
        "tags": [
          "harness-tiles"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/rail-standalone-pages/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The finished site directory."
                  },
                  "built": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "The layer whose site this is (`cat-harness`)."
                  },
                  "foreign-site": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "The site is a folio's, not the platform's: platform links point at the platform's published site."
                  },
                  "instance": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "With `--foreign-site`: the layer whose own site this is. Its name, mark and graphs head the navbar, and Harnesses lists it (linking to this site's root) and the harnesses it is built on."
                  }
                },
                "required": [
                  "site",
                  "built"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "railed": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Pages given the navbar, beside those already navigated, redirect stubs, pages that declined, and pages with no <body> — each counted, none silently."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/rail-standalone-pages.jsonld",
        "x-invoke": {
          "shell": "bun run cat rail:standalone-pages"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "harness-tiles"
        ]
      }
    },
    "/tools/readme-audit": {
      "post": {
        "operationId": "readme-audit",
        "summary": "Audit README links",
        "description": "Verify every Markdown link in a folio's README still resolves — relative paths against the tree, repo refs against a real ls-tree, Pages URLs against the publish ref. Writes nothing.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/readme-audit/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The file to audit; the README by default."
                  },
                  "fetch": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Also dereference external URLs."
                  },
                  "dir": {
                    "$ref": "#/components/schemas/FilesystemPath",
                    "description": "The folio root, when not the working directory."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "findings": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Resolved, dead, or NOT CHECKED — the third state is never rendered as either of the other two."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/readme-audit.jsonld",
        "x-invoke": {
          "shell": "bun run cat readme:audit",
          "mcp": {
            "tool": "readme_audit"
          },
          "inProcess": {
            "module": "src/tools/readme-audit.ts"
          }
        },
        "x-mcp-tools": [
          "readme_audit"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "docs-generation"
        ]
      }
    },
    "/tools/readme-sync": {
      "post": {
        "operationId": "readme-sync",
        "summary": "Sync generated README sections",
        "description": "Rewrite each generated README region, and only where the README already carries that section's marker pair. Nothing outside a marked region is touched. The layer's AGENTS.md is synced too, for the `skills:index` index only: the skills the layer publishes, or, past 32 KiB, their directories with the full list in SKILLS.md.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/readme-sync/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if any section is stale; write nothing."
                  },
                  "only": {
                    "$ref": "#/components/schemas/ReadmeSection",
                    "description": "Restrict to these sections. Repeated: the flag is emitted once per section."
                  },
                  "link_style": {
                    "$ref": "#/components/schemas/LinkStyle"
                  },
                  "fetch": {
                    "$ref": "#/components/schemas/Flag"
                  },
                  "dir": {
                    "$ref": "#/components/schemas/FilesystemPath"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Per section: written, unchanged, or skipped because it could not be determined."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/readme-sync.jsonld",
        "x-invoke": {
          "shell": "bun run cat readme:sync",
          "mcp": {
            "tool": "readme_sync"
          },
          "inProcess": {
            "module": "src/tools/readme-sync.ts"
          }
        },
        "x-mcp-tools": [
          "readme_sync"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "docs-generation"
        ]
      }
    },
    "/tools/references-extract": {
      "post": {
        "operationId": "references-extract",
        "summary": "Reference lists to reference nodes",
        "description": "Split each library entry's reference lists (a References, Bibliography or Further reading section or heading, in the six UN languages and Portuguese) into folio-reference/v1 nodes in the instance's declared `references` directory, one per cited work, keyed `<doc-id>.<section>.<n>`: provenance extracted, derivedFrom the section file, printed the entry verbatim, and only the fields read without guessing (URL, DOI, ISBN, year, access date). The bibliography page lists them as the document's own bibliography. `--check` writes nothing and fails when a node is stale.",
        "tags": [
          "l1-document-ingestion"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/references-extract/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The instance root whose library sections are read and whose references directory is written."
                  },
                  "entry": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "One library entry's slug, to extract only its lists."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a node is stale, instead of writing."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "references": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The extracted reference nodes: `<references dir>/<doc-id>.<section>.<n>.json`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/references-extract.jsonld",
        "x-invoke": {
          "shell": "bun run cat references:extract"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "l1-document-ingestion"
        ],
        "x-selection": {
          "when": "A library entry's source prints a reference list and the document should have its own bibliography. For glossary and abbreviations sections use glossary-from-source.",
          "limits": "Reads L1 sections, not the PDF; no title or author is parsed (the node keeps the printed text). Only nodes with provenance extracted are written or removed.",
          "cost": "Seconds for a few hundred entries; reads sections, no network."
        }
      }
    },
    "/tools/references-render": {
      "post": {
        "operationId": "references-render",
        "summary": "Reference list from reference nodes",
        "description": "Rewrite each reference-list block of a document (a block whose `meta.referenceList` is set) from the folio-reference/v1 nodes its `cites` names, in that order: the node's `printed` text verbatim when it has one, otherwise WHO style (or the short `Authors. Title. Year.` form), as a numbered or bulleted list. The block's `.md` is generated whole. `--check` writes nothing and fails when a list is stale.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/references-render/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The instance root whose folio blocks and references directories are read."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a list is stale, instead of writing."
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "blocks": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The rewritten reference-list blocks: each block's `.md`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/references-render.jsonld",
        "x-invoke": {
          "shell": "bun run cat references:render"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ],
        "x-selection": {
          "when": "A document's References list should come from the reference nodes its block cites. For glossary or acronyms tables use glossary-table.",
          "limits": "Only blocks with `meta.referenceList`; the whole `.md` is regenerated. A cited key with no reference node fails the run.",
          "cost": "Milliseconds per block; reads the instance's blocks and reference nodes, no network."
        }
      }
    },
    "/tools/release-please": {
      "post": {
        "operationId": "release-please",
        "summary": "release-please (declared, not configured here)",
        "description": "Propose the next version of each package from conventional-commit messages, open a release PR with the CHANGELOG and version bump, and — when that PR is merged — create the tag and GitHub release. Does not publish to a registry. Declared here, not configured: no config file and no tag exist in this repository.",
        "tags": [
          "package-release",
          "npm-kg-distribution"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/release-please/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "package": {
                    "$ref": "#/components/schemas/PackageName",
                    "description": "The package being released. release-please proposes every package it is configured for; this is the one whose tag is wanted."
                  },
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "owner/name of the repository the release is made in; the current one when absent."
                  }
                },
                "required": [
                  "package"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tag": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The tag created when the release PR merges, `<package>-v<version>`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/release-please.jsonld",
        "x-invoke": {
          "shell": "release-please release-pr"
        },
        "x-install": {
          "cli": "npm install -g release-please (or the GitHub Action googleapis/release-please-action@v4)"
        },
        "x-requires": {
          "runtime": [
            "node",
            "release-please"
          ],
          "network": true
        },
        "x-satisfies": [
          "package-release",
          "npm-kg-distribution"
        ],
        "x-selection": {
          "when": "A repository whose commits follow conventional-commit messages and that releases often enough that doing it by hand is the bottleneck. Several packages in one repository, each with its own tag, is its strength.",
          "limits": "The bump comes from commit MESSAGES, not from what changed: a `feat:` that removed something gives a minor bump. Check it against the surface diff (skill step 1). With the default token it cannot open PRs unless the repository allows Actions to. It needs a config file (`--config-file`); a missing one falls back to defaults that find nothing. The tag appears only when its release PR is merged.",
          "cost": "Not configured here. One config file and one manifest per repository; each run is a few seconds of API calls."
        }
      }
    },
    "/tools/remote-mount": {
      "post": {
        "operationId": "remote-mount",
        "summary": "Mount remote harnesses at a pinned commit, only when trusted",
        "description": "Lay down each declared remote mount — a `source.remote` layer in the root `index.config.json`, or, in a folio with no index, a `remoteMounts` entry on its declaration (both at once is refused) — and its dependency closure, from another repository at a full commit SHA. Write the lock, `index.lock.json` (a legacy `<name>.mount-lock.json` is read, and renamed onto it when rewritten), and, with an index, regenerate the root `.gitignore` block that ignores each mount path. It READS the declared mounts and never writes them: a tool that changes a mount writes through `writeDeclaredMounts` into `index.config.json`. Before anything is checked out, each mount must pass the trust gate (`schemas/kg/mount-trust.ts`, rule H8): a person's consent recorded for THIS pin, or a signature in a declared trust network. No signature verifier exists yet, so a signature alone is could-not-determine and does not mount. Unsigned and unconsented is refused. `--staging` mounts for a preview and needs neither. A directory id an override or `mountDefaults` names may be one the layer declares in its `<name>.json` or one it declares FROM WITHIN a declared directory (`skills/skills.json` naming `voices`), resolved at the pin through `instanceDirectories`; an id in neither is refused at plan time. `tools` on an override names Tools by id and mounts each one runnable: its definition (`<tools dir>/<id>/<id>.ts`), its implementation (the `inProcess.module`, or the script its `bun run cat <key>` resolves to) and their import closure, walked by bootstrap-tools' `importClosure` (the one closure walker), as every declared directory that closure touches — the lock still records directories only. A `hydrated` mount lays each chosen directory down as its published `index.hydrated.jsonld` only: read from the pin's git tree when a commit carries it, otherwise fetched from the pin's subgraph index package (the `subgraph-index-<sha>` release asset `subgraph-index-package` publishes), its tarball checked against its `folio-binary-release/v1` record, its manifest against the repository, pin and harness asked for, and each file against its sha256, `SubgraphHydratedSchema` and the subgraph IRI; the lock records the package's URL and sha256 so a replay fetches the same bytes. `--check` compares the disk against the lock and never fetches. When a run CHANGES the lock, it then re-renders the agent surface (`skill:commands` → `.claude/commands/`, `agent-memory` → `.claude/agent-memory/` and `.agents/`) from the checkout root, so a re-pin commit carries the skills and memory the new layers define; a generator that fails fails the run, and `--no-agent-surface` opts out.",
        "tags": [
          "security",
          "agent-memory"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/remote-mount/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The downstream layer root; omitted, every declaring layer in the checkout."
                  },
                  "staging": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Mount for a staging preview: no signature or consent required."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Compare the disk against the lock; fetch nothing."
                  },
                  "noAgentSurface": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Do not re-render `.claude/commands/` and the agent memory after a mount that changed the lock."
                  },
                  "noInstall": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Lay the pinned bytes down without `bun install` in each mounted layer that carries a `package.json`. By default the install runs (`--production`; `--install-all` keeps devDependencies), so the mounted tools run; it writes only `node_modules/`, which no mount digest covers, so `--check` still passes."
                  },
                  "seed": {
                    "$ref": "#/components/schemas/MountSeed",
                    "description": "`<name>=<owner/repo>@<40-char sha>`: create or re-pin that remote layer in `index.config.json` instead of mounting, writing its `trust.consent` for that pin in the same write (needs `consentBy` and `evidence`; repeatable; `--whole` mounts every tracked file). Refused while a mount it moves has edits the lock does not hold, since the next mount would leave that mount at the old commit; `fresh` lets it through."
                  },
                  "fresh": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Replace a mount whose bytes no longer hash to the lock instead of leaving it untouched; with `seed`, re-pin over such edits. The edits are discarded."
                  },
                  "choose": {
                    "$ref": "#/components/schemas/MountChoice",
                    "description": "`<harness>[:<instance>]`: write a review's choice (`directories` and/or `tools`) into that mount entry's `overrides.<instance>` instead of mounting, so a fresh clone replays it. The pin and its consent are untouched; the next mount resolves the choice and the lock records what it resolved to."
                  },
                  "directories": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "With `choose`: comma-separated directory ids, nested ids or concern names."
                  },
                  "tools": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "With `choose`: comma-separated Tool ids, each mounted runnable."
                  },
                  "consentBy": {
                    "$ref": "#/components/schemas/Login",
                    "description": "With `seed`: who consented, as `consent.by`."
                  },
                  "evidence": {
                    "$ref": "#/components/schemas/Text",
                    "description": "With `seed`: where the consent was given, readable (a session, an issue comment), as `consent.evidence`. On stdin because it is free prose: it quotes what was said."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "outcomes": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Per layer: mounted, local, skipped, missing (including refused by the trust gate) or could-not-determine."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/remote-mount.jsonld",
        "x-invoke": {
          "shell": "bun run cat mount:remote"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git",
            "curl",
            "tar"
          ],
          "network": true
        },
        "x-satisfies": [
          "security",
          "agent-memory"
        ]
      }
    },
    "/tools/render-log": {
      "post": {
        "operationId": "render-log",
        "summary": "Record what the publish branch served",
        "description": "Append one entry to the render log on the publish branch: what was published or taken down, when, from which commit, and — for a removal or a retention — WHY. The log is the only place a preview that vanished leaves a trace.",
        "tags": [
          "render-logging"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/render-log/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dir": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A checkout of the publish branch, or a publish directory about to become one. This tool NEVER fetches, commits or pushes: the calling workflows hold the checkout with their own retry and concurrency handling, and a second pusher racing them could lose a deploy."
                  },
                  "event": {
                    "$ref": "#/components/schemas/RenderEvent",
                    "description": "`rendered`, `removed`, `restored` or `retained`. `retained` records a removal CONSIDERED and refused, which would otherwise leave no trace."
                  },
                  "kind": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "What was rendered — `staging-preview`, `site`, `export`. Open, not an enum: the publish branch carries more than previews, and an enum would make logging a new kind wait on a schema change."
                  },
                  "path": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The path on the publish branch. Checked as a VALUE, never trusted by provenance: the slug sanitiser can emit `..`, which is only safe for a slug taken from a git ref, and a dispatch input is not one."
                  },
                  "slug": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "The staging slug, where the subject has one."
                  },
                  "branch": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch the render came from."
                  },
                  "commit": {
                    "$ref": "#/components/schemas/CommitSha",
                    "description": "The commit the artefact was built from."
                  },
                  "run": {
                    "$ref": "#/components/schemas/Url",
                    "description": "The workflow run that wrote this, so a reader can open the log."
                  },
                  "prose": {
                    "$ref": "#/components/schemas/Markdown",
                    "description": "One JSON object on STDIN: `{summary, reason?, detail?, format?}`. `summary` is required and one line. `reason` is required by the SCRIPT for `removed` and `retained`, because an entry saying an artefact went and not why is the ambiguity the log exists to prevent. `format` declares how the prose reads (absent means plain text, never sniffed). Build it with `jq -n --arg`, never by concatenation."
                  }
                },
                "required": [
                  "dir",
                  "event",
                  "kind",
                  "path",
                  "prose"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entry": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The day's JSONL the entry was APPENDED to. Append is the only verb: there is no `--remove`, no `--edit` and no `--id`, so a takedown is a `removed` ENTRY rather than the erasure of the `rendered` one before it, and the never-delete rule is structural rather than a guard every cleanup path must remember."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/render-log.jsonld",
        "x-invoke": {
          "shell": "bun run cat render:log"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "jq"
          ],
          "network": false
        },
        "x-satisfies": [
          "render-logging"
        ],
        "x-selection": {
          "when": "Whenever something is published to or removed from the publish branch — including a removal that was refused. Called from `feature-staging.yml` at four points; `staging-render-log.bpmn` is the process.",
          "limits": "It writes into a directory and does not push, so a caller that forgets to commit the log has written nothing durable. It cannot edit or delete an entry, by design. `--summary` / `--reason` / `--detail` are REFUSED as flags at exit 2 rather than ignored: they go on stdin, and a caller still passing them is told instead of silently logging an entry with no summary.",
          "cost": "One appended line. No network."
        }
      }
    },
    "/tools/render-order": {
      "post": {
        "operationId": "render-order",
        "summary": "The render pipeline, in dependency order",
        "description": "Flatten the repository's renders into the order their `needs` imply, and optionally run them. Two stages: the current declared state as json/jsonld and the README derived from it are FATAL; the dynamic renderers (viewers, visualisers, doc pages, diagrams) skip and log; the dynamic-state export closes it. A cycle or a missing dependency yields NO order rather than a partial one.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/render-order/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dry_run": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print the flattened order and each step's failure policy without running anything."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Per step: ran, failed, skipped, or PENDING — declared with no implementation yet, which is never rendered as a pass."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/render-order.jsonld",
        "x-invoke": {
          "shell": "bun run cat render",
          "mcp": {
            "tool": "render_order"
          },
          "inProcess": {
            "module": "src/tools/render-order.ts"
          }
        },
        "x-mcp-tools": [
          "render_order"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "docs-generation"
        ]
      }
    },
    "/tools/review-log-watch": {
      "post": {
        "operationId": "review-log-watch",
        "summary": "Check a review log and its repository's issues for changes",
        "description": "The mechanical check a review-log watcher runs on every poll. Given a drafting sheet's Contributor Feedback values and the folio repository, it reads the repository's open and closed issues (leaving out pull requests, issues labelled `no-sheet` and, with `--author`, issues someone else opened) and compares a digest of them and of the cells people set (Title, Selected Sections, Contributor Feedback, Disposition, Ready for agent, Ready for merge, Dispositions confirmed; on a public-comment log also Committee Feedback, TWG (CS), TWG (human) and Change Set (human)) with the last check's. Unchanged: it prints `{\"status\":\"unchanged\"}` and exits 0. Changed: it exits 10 and lists what changed (issue opened, updated or closed; a cell's old and new text), the Contributor Feedback rows to append, one per issue that no row's Issue cell links yet (Title the issue's title, the first Contributor Feedback column `@login (#N): first paragraph`, Issue the issue's URL; a closed issue's row marked `closed`), and `closedRows`, the rows linking a closed issue, which the watcher hides with their text struck through. A read with no Issue column (a public-comment log's Review Change Sets) tracks only issues labelled `change-set` unless `--label` says otherwise, and appends no rows: each open issue is reported as an `issue-unlinked` change instead. It writes no sheet and no issue: the watcher appends the rows and does the agent pass. With `--accept` it stores the new state for the next poll to compare against.",
        "tags": [
          "review-log-watch"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/review-log-watch/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio repository, `owner/name`, whose issues, open and closed, are read with `gh api`."
                  },
                  "sheet": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The Contributor Feedback tab's values (a public-comment log: Review Change Sets) as JSON: the Sheets API `values` array (or the whole `get_values` answer), from row 1, so the header row (first cell `Change-set`) is found."
                  },
                  "state": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The last check's state file. Missing on the first check, which reports every open issue as opened."
                  },
                  "issues": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Issues as JSON (the issues API's shape), instead of reading them with `gh api`. For tests and offline runs."
                  },
                  "author": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Only issues this GitHub login opened. Default every author."
                  },
                  "sheetHash": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The sheet script's hash of the person-set cells, Watch!G1. Given, it stands for the cells, so `--sheet` needs only the header row and the Issue column."
                  },
                  "label": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Only issues with this label, e.g. `change-set`. Default every issue on a read with an Issue column, and `change-set` on one without (a public-comment log)."
                  },
                  "skipLabel": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The label that keeps an issue off the sheet. Default `no-sheet`."
                  }
                },
                "required": [
                  "repo",
                  "sheet",
                  "state"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "JSON on standard output: `status` (`unchanged` or `changed`), `digest`, and when changed `changes`, `append` (rows aligned to the header, each with `closed`), `closedRows` and `state`. Exit 0 unchanged, 10 changed, 2 usage."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/review-log-watch.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/tools/review-log-watch/watch.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "review-log-watch"
        ],
        "x-selection": {
          "when": "On every poll of a review-log watcher, before any agent work: the agent pass runs only when this reports `changed`.",
          "limits": "Reads one tab and one repository's issues; it never writes the sheet or GitHub. It sees an edit only in the watched headers, so the agent's own Green columns and the script's Grey ones never wake the watcher.",
          "cost": "One `gh api` call per 100 issues and one small JSON file; well under a second."
        }
      }
    },
    "/tools/review-sheet-sync": {
      "post": {
        "operationId": "review-sheet-sync",
        "summary": "Build the review sheet's Apps Script and a document's Config tab",
        "description": "Builds `Code.gs` (`--script`), the one Google Apps Script every review sheet runs (from `review-sheet.gs`), and one document's Config tab rows (`--config`), filled from the folio's `review/public-comment/sheet-sync.json`, its review anchors and the draft's `pdf-line-map.json`. The script keeps a public-comment review sheet's links and joins current: each comment No. links to its comment page; Sections, Page and Line no(s) link to the page of the frozen review draft; Review Change Sets joins its comments, suggested revisions, feedback and dispositions, each `No. n` linking to its row; and on both tabs Agentic status lists each pull request of the change-set, linked, with its status and what it changed, from the Agent tab. It reads the document's URLs, tab and column names and data from the sheet's Config tab (visible, locked to the owner), which the agent writes from these rows. A person pastes the script (one file) into the sheet once (Extensions > Apps Script) and runs `installTriggers`; from then on the sheet rebuilds itself within about a minute of an edit, with no agent. With `\"mode\": \"drafting\"` in the config it builds the drafting sheet instead: one Contributor Feedback tab where each row is a change set (ids assigned by the script), Sections picked from the document's table of contents and linked to it, and Issue and Agentic status from the Agent tab.",
        "tags": [
          "review-sheet-script"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/review-sheet-sync/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "script": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write the generic Code.gs. The same for every document."
                  },
                  "repo": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio repository. Default the current directory."
                  },
                  "config": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The folio's sheet settings, e.g. `review/public-comment/sheet-sync.json`: anchors, lineMap, draftUrl, commentUrl, and optional namedSections, aliases, tabs and columns. A drafting sheet's config (`review/drafting/sheet-sync.json`) has mode `drafting`, anchors and sectionUrl."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write the Config tab's rows (JSON). Default standard output."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "script": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "Code.gs, ready to paste into any review sheet's Apps Script editor. Never committed: it is rebuilt from the template."
                    },
                    "configRows": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The Config tab's rows for one document, which the agent writes into the sheet. Never committed: rebuilt from the config."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/review-sheet-sync.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/tools/review-sheet-sync/build-review-sheet-script.ts"
        },
        "x-install": {
          "service": "Google Apps Script bound to the review sheet: copy the template, have the agent write its Config tab, add editors to the \"Ready columns: editors\" lock, paste Code.gs, run installTriggers (skill review-sheet-script, \"Setting up a sheet for a new document\")"
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "review-sheet-script"
        ],
        "x-selection": {
          "when": "A public review is kept in a shared Google Sheet with the public-comment tabs (Review Public Comments, Review Change Sets, Agent - Comments, Agent - Change Sets), and its links or joined columns must stay current without an agent re-pasting them. Also after the review anchors, the draft's link prefix or a tab or column name changes: rewrite the Config tab (the script stays).",
          "limits": "Builds the script only; installing it is a person's step in the sheet, since the sheet's owner must authorise it. It reads only the tabs and headers named in the config. In the reviewers' columns the link text must be in the cell already: it links what reviewers wrote and does not rewrite their words. The joined columns and Agentic status it writes whole.",
          "cost": "Reads three JSON files and writes one file of about 20 kB. In the sheet, a full refresh of 800 rows takes about 20 seconds."
        }
      }
    },
    "/tools/rewrite-moved-paths": {
      "post": {
        "operationId": "rewrite-moved-paths",
        "summary": "Rewrite paths that still name a moved file's old layer — never in a record",
        "description": "After a move between two layers lands, find every mention `<from>/<prefix>/<rest>` in the scanned tree's tracked files and rewrite it to `<to>/<prefix>/<rest>` only when the file exists under the destination root and not under the source root. Records are never read: beans, todos, memory, proposals, wireframes, QA results, upstream pins, vocab mappings, provenance figures and terminologies, and test fixtures (`DEFAULT_RECORD_GLOBS`; the CLI's `--keep <glob>` adds more, generated trees among them, which their generators rewrite — a glob is not a shell-safe argument type, so it is not a declared input). Reports by default with file and line; `--write` applies; `--check` exits 1 while a rewrite is owed.",
        "tags": [
          "kg-separation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/rewrite-moved-paths/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fromName": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "The moved files' old layer, as paths spell it (e.g. the harness)."
                  },
                  "fromRoot": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "That layer's root on disk."
                  },
                  "toName": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "The layer the files moved to."
                  },
                  "toRoot": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "That layer's root on disk."
                  },
                  "prefix": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A moved directory, repeatable (e.g. `scripts`, `pipeline`)."
                  },
                  "scan": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The git checkout whose tracked files are read; default the source root."
                  },
                  "write": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Apply the rewrites."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Exit 1 while any rewrite is owed; write nothing."
                  }
                },
                "required": [
                  "fromName",
                  "fromRoot",
                  "toName",
                  "toRoot",
                  "prefix"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rewrites": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Rewrites made or owed, each with file and line; mentions left alone; record files not read."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/rewrite-moved-paths.jsonld",
        "x-invoke": {
          "shell": "bun run cat paths:rewrite-moved"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": false
        },
        "x-satisfies": [
          "kg-separation"
        ]
      }
    },
    "/tools/schema-docs": {
      "post": {
        "operationId": "schema-docs",
        "summary": "Skill contract reference",
        "description": "Render each skill's input/output JSON Schema as a browsable Markdown reference page, with an index. The generated pages are committed so they are readable on the forge as well as on the site.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/schema-docs/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Compare against the committed pages and fail if stale, instead of writing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schemaReference": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The generated reference directory. Never hand-edited."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/schema-docs.jsonld",
        "x-invoke": {
          "shell": "bun run cat schema:docs"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "docs-generation"
        ]
      }
    },
    "/tools/schemas-viewer": {
      "post": {
        "operationId": "schemas-viewer",
        "summary": "Schemas viewer",
        "description": "Render each declared schema directory as a page per subject layer, over one shared data index.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/schemas-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/schemas-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat schema:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/search-graph": {
      "post": {
        "operationId": "search-graph",
        "summary": "Lexical search over the content graph",
        "description": "Find graph nodes, authored or ingested, whose label, title, kind or tags contain a string, with no graph expansion. corpus-search composes this with a neighbour walk.",
        "tags": [
          "corpus-grep"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/search-graph/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Substring to look for."
                  },
                  "provenance": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "`authored` or `ingested`. Omit for both."
                  },
                  "searchText": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Also scan companion Markdown bodies."
                  },
                  "limit": {
                    "$ref": "#/components/schemas/Count",
                    "description": "Max hits (default 20)."
                  }
                },
                "required": [
                  "query"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "JSON: the matching nodes and which field matched."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/search-graph.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "search_graph"
          },
          "inProcess": {
            "module": "src/tools/graph.ts"
          }
        },
        "x-mcp-tools": [
          "search_graph"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "corpus-grep"
        ]
      }
    },
    "/tools/secrets-check": {
      "post": {
        "operationId": "secrets-check",
        "summary": "Check declared credential needs against workflow use and expiry, by name",
        "description": "Compare each repository's declared credential needs (`credentials/needs.json`, profile and registry) with the `secrets.NAME` expressions its workflows reference (GitHub Actions' dollar-and-double-brace form, said in words because this text is rendered on a Jekyll page), with the secret names GitHub lists when a token allows it, and with any recorded expiry. NAMES ONLY — no value is ever read. Findings: used-not-declared, declared-not-used, declared-not-present, present-not-declared (reported, never deleted), naming advisories, and expiry (≤30 days minor, ≤7 major, expired critical). Exits 2 when anything could not be determined, which outranks clean; else 1 on a major or critical finding; else 0.",
        "tags": [
          "security"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/secrets-check/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repos": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Repository checkouts to check. Default: every repository the index mounts."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print the result as JSON instead of the human report."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verdict": {
                      "$ref": "#/components/schemas/Flag",
                      "description": "The exit status: 0 clean, 1 a major or critical finding, 2 could not determine."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/secrets-check.jsonld",
        "x-invoke": {
          "shell": "bun run cat secrets:check"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "security"
        ],
        "x-selection": {
          "when": "Before relying on a workflow's credentials, or to see which secrets a repository needs, uses and lacks.",
          "limits": "Presence on GitHub is judged only when a token may list secret names (`list-secret-names`); without one that half is could-not-determine, never clean.",
          "cost": "Reads workflow and declaration files; one API call per repository when a token is present."
        }
      }
    },
    "/tools/security-gate": {
      "post": {
        "operationId": "security-gate",
        "summary": "Run every existing security check as one named release step",
        "description": "Run the repository's security checks — workflow injection, secret leaks, lockfile pinning, the toolchain pin, QA reviewer permission, materialised-asset fixity — plus two advisories (dependency advisories, third-party action SHA pinning), each by name as argv. Every check is reported as pass, fail or unknown; a blocking check that fails OR could not be run refuses the release, because could-not-check is never clean. Advisories are reported and never block. Called by `prepare-merge` before a push that will merge, and by any publish process before it publishes.",
        "tags": [
          "security"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/security-gate/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print a `folio-security-gate/v1` result on stdout instead of the human report."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "blocked": {
                      "$ref": "#/components/schemas/Flag",
                      "description": "Whether a blocking check failed or could not be run; also the exit status (1 when blocked)."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/security-gate.jsonld",
        "x-invoke": {
          "shell": "bun run cat security:gate"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "security"
        ]
      }
    },
    "/tools/separation-cutover-check": {
      "post": {
        "operationId": "separation-cutover-check",
        "summary": "Is this repository's cutover from the monorepo complete? Measured, condition by condition",
        "description": "Run in a separated repository. Six conditions, each decided by an existing gate: `mounts` (every declared layer on disk at its pin — `remote-mount --check`), `declarations` (every path a declaration names resolves — `declaration-resolution`), `monorepo-paths` (no wiring still names the monorepo: `livesAt` on it, a submodule of it, a reusable workflow called from it, a path into its old checkout — the one condition implemented here), `import-direction` and `reference-direction` (no layer reaches a layer above it), and `site` (the site builds from the mounts alone, every link resolving — `build-instance-site --no-mount`, only with `--site`). Findings inside a MOUNTED layer are listed and not counted: a defect in a layer pinned from upstream is fixed upstream and re-pinned. Exit 0 complete, 1 a condition failed, 2 a condition could not be determined or was not run — without `--site` the answer is never 0.",
        "tags": [
          "kg-separation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/separation-cutover-check/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The separated checkout. Default: the working directory."
                  },
                  "site": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Build the site from the mounts on disk (minutes); without it the `site` condition is not run and the verdict cannot be complete."
                  },
                  "monorepo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The repository the separation left, `<owner>/<repo>`. Default: litlfred/folio-assistant."
                  },
                  "monorepoDir": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "Its old checkout directory name, as paths spell it. Default: the repository's name."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print the report as JSON, mounted-layer findings included."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "conditions": {
                      "$ref": "#/components/schemas/Count",
                      "description": "Per condition: pass, fail, could-not-determine or not-run, the gate that decided it, and its findings."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/separation-cutover-check.jsonld",
        "x-invoke": {
          "shell": "bun run cat separation:cutover:check"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": false
        },
        "x-satisfies": [
          "kg-separation"
        ],
        "x-selection": {
          "when": "Before calling a separation's cutover (kg-separation stage 13) done, and after any re-pin of a separated repository's layers.",
          "limits": "It judges ONE repository. A downstream's own CI and the parent repository's retirement are not observed from here.",
          "cost": "Seconds without `--site`; a full Jekyll build with it."
        }
      }
    },
    "/tools/serve-rendering": {
      "post": {
        "operationId": "serve-rendering",
        "summary": "Local rendering server",
        "description": "Serve a layer's renderings over local HTTP with their declared media types. The publication host wherever GitHub Pages is absent, and the only host that can enforce `application/ld+json` at all.",
        "tags": [
          "serving-renderings"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/serve-rendering/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "directory": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Tree to serve; defaults to the built site when present."
                  },
                  "port": {
                    "$ref": "#/components/schemas/Port",
                    "description": "0 binds a free port, which is what the tests use."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "$ref": "#/components/schemas/Url",
                      "description": "Where the tree is being served."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/serve-rendering.jsonld",
        "x-invoke": {
          "shell": "bun run cat serve:rendering"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "serving-renderings"
        ],
        "x-selection": {
          "when": "Serving renderings in a Bun / JavaScript / TypeScript runtime environment.",
          "limits": "Requires Bun runtime. For Python-only environments without Bun, use `serve-rendering-py`.",
          "cost": "Zero install cost when Bun is already present."
        }
      }
    },
    "/tools/serve-rendering-py": {
      "post": {
        "operationId": "serve-rendering-py",
        "summary": "Local rendering server (Python)",
        "description": "Serve a layer's renderings over local HTTP with their declared media types using Python 3 standard library. The publication host wherever GitHub Pages is absent, and the only host that can enforce `application/ld+json` at all.",
        "tags": [
          "serving-renderings"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/serve-rendering-py/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "directory": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Tree to serve; defaults to the built site when present."
                  },
                  "port": {
                    "$ref": "#/components/schemas/Port",
                    "description": "0 binds a free port, which is what the tests use."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "$ref": "#/components/schemas/Url",
                      "description": "Where the tree is being served."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/serve-rendering-py.jsonld",
        "x-invoke": {
          "shell": "bun run cat serve:rendering:py"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "python3"
          ],
          "network": false
        },
        "x-satisfies": [
          "serving-renderings"
        ],
        "x-selection": {
          "when": "Serving renderings in a Python runtime environment without requiring Bun or Node.",
          "limits": "Requires Python 3. For Bun runtime environments, use `serve-rendering`.",
          "cost": "Zero external dependencies beyond standard library Python 3."
        }
      }
    },
    "/tools/shared-assets": {
      "post": {
        "operationId": "shared-assets",
        "summary": "Stage a site's shared asset directories where the host serves them",
        "description": "Write each shared directory of a built site (its `assets/…` laid out as a built site) to `<out>/shared/<dir>/<key>/` with a `.shared.json`, so sites on one host load one copy instead of one each. A directory already there is left alone. This is the host side of the shared-assets step `build-instance-site` runs when a checkout declares `site.sharedAssets`; run on its own, it stages an IG build, or any built site, into a host site root.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/shared-assets/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A directory laid out as a built site, holding `assets/…`."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The host site root the shared directories are written under."
                  }
                },
                "required": [
                  "site",
                  "out"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "staged": {
                      "$ref": "#/components/schemas/Text",
                      "description": "One line per shared directory: `staged` or `already there`, with its path under `shared/`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/shared-assets.jsonld",
        "x-invoke": {
          "shell": "bun run cat site:shared-assets stage"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ]
        },
        "x-satisfies": [
          "docs-generation"
        ],
        "x-selection": {
          "when": "Composing a layer's site for a host that serves shared assets, or staging an IG build's assets into such a host.",
          "limits": "Copies only; it does not rewrite the pages that load the assets. `build-instance-site` does both in one run.",
          "cost": "A local copy of the shared directories: seconds."
        }
      }
    },
    "/tools/sibling-sessions": {
      "post": {
        "operationId": "sibling-sessions",
        "summary": "Sibling sessions in a window",
        "description": "List the Claude Code sessions that have committed to this repository in a time window, from the `Claude-Session:` trailer on commits across ALL branches — with each one's commit count, first and last commit, latest subject, and the branches containing its tip. The session API cannot see a sibling session, so the trailer is the only durable session identity here and a session's state is INFERRED from its branch; whether a session is still running is not knowable from a checkout and is deliberately not reported.",
        "tags": [
          "bean-coordination"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/sibling-sessions/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "since": {
                    "$ref": "#/components/schemas/TimeWindow",
                    "description": "The window: `4h`, `2d`, `1w`, or an ISO date. Defaults to one day."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Emit the sweep as JSON rather than the report."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "One entry per session, most recently active first, plus the number of commits examined and how many carried no trailer. A window with NO commits exits non-zero rather than reporting 'no siblings' — a sweep over nothing has not found anything."
                    },
                    "result": {
                      "$ref": "#/components/schemas/SessionSweep",
                      "description": "With --json, the sweep as one `SessionSweep` record: the sessions, the commits examined and how many carried no trailer. Programs read this; people read `report`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/sibling-sessions.jsonld",
        "x-invoke": {
          "shell": "bun run cat sessions",
          "inProcess": {
            "module": "scripts/sibling-sessions.ts"
          }
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "bean-coordination"
        ]
      }
    },
    "/tools/site-build-local": {
      "post": {
        "operationId": "site-build-local",
        "summary": "Build the docs site locally",
        "description": "Build the published site on this machine, so a page can be looked at rather than described: the same Jekyll build `pages-publish` runs in CI, into a directory of your choosing, and never pushed. The local half of the two site builds: local and GitHub builds are two Tools for one skill.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/site-build-local/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dest": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write the built site. Default: a temporary directory."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "site": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The built site, as `pages-publish` would publish it."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/site-build-local.jsonld",
        "x-invoke": {
          "shell": "bun run cat preview:site"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bash"
          ],
          "network": false
        },
        "x-satisfies": [
          "docs-generation"
        ],
        "x-selection": {
          "when": "Looking at a rendered page before pushing it: a layout, an anchor, a generated index.",
          "limits": "Not what CI builds: it uses the installed just-the-docs gem rather than the pinned remote theme, so chrome can differ, while Liquid and kramdown do not. It runs the cheap post-Jekyll steps and names the rest it skipped. Read a layout question off the staging preview.",
          "cost": "Local Ruby and Jekyll; a minute or two."
        }
      }
    },
    "/tools/site-search-index": {
      "post": {
        "operationId": "site-search-index",
        "summary": "Site search index",
        "description": "The just-the-docs search index, `assets/js/search-data.json`, which the theme writes as part of the Jekyll site build: one entry per page section, searched by every page's search box. Built implicitly by the build rather than by a command of its own.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/site-search-index/"
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "index": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`_site/assets/js/search-data.json` in the assembled site."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/site-search-index.jsonld",
        "x-invoke": {
          "shell": "bun run cat preview:site"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "ruby"
          ],
          "network": false
        },
        "x-satisfies": [
          "docs-generation"
        ]
      }
    },
    "/tools/site-search-scopes": {
      "post": {
        "operationId": "site-search-scopes",
        "summary": "Site search scopes",
        "description": "The site search index cut into one index per scope — each declared layer, each target locale, and the platform — plus `assets/js/search/manifest.json` naming them, so a reader's search loads its own scope rather than the whole site. Run on the assembled site after the index is written or borrowed.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/site-search-scopes/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "index": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "`_site/assets/js/search-data.json`, as the theme wrote it or as staging borrowed it."
                  }
                },
                "required": [
                  "index"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scopes": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`_site/assets/js/search/` — `manifest.json` and one `<scope>.json` per scope."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/site-search-scopes.jsonld",
        "x-invoke": {
          "shell": "bun run cat search:split --dir _site"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "docs-generation"
        ]
      }
    },
    "/tools/site-viewer": {
      "post": {
        "operationId": "site-viewer",
        "summary": "Published site viewer",
        "description": "List the published site's top-level routes and staging previews, with the pages and files under each, as read from the branch that keeps the site — saying so when the branch is empty or could not be read, never drawing zeros in its place.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/site-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/site-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat site:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": true
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/skill-docs": {
      "post": {
        "operationId": "skill-docs",
        "summary": "Skill instruction reference",
        "description": "Render the skill instruction bodies — the prose an agent actually loads — as browsable pages with an index, so a reader can see what an agent is told without cloning the repository.",
        "tags": [
          "docs-generation"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/skill-docs/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Compare against the committed pages and fail if stale, instead of writing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "skillInstructions": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The generated instruction directory. Never hand-edited."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/skill-docs.jsonld",
        "x-invoke": {
          "shell": "bun run cat skills:docs"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "docs-generation"
        ]
      }
    },
    "/tools/skill-fetch": {
      "post": {
        "operationId": "skill-fetch",
        "summary": "Fetch a skill",
        "description": "Load one skill's instruction body for the agent to follow, from the local packages or an external bundle.",
        "tags": [
          "skills-and-tools"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/skill-fetch/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "skill": {
                    "$ref": "#/components/schemas/SkillName"
                  },
                  "package_name": {
                    "$ref": "#/components/schemas/PackageName"
                  }
                },
                "required": [
                  "skill"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "instructions": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "The skill's instruction body."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/skill-fetch.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "skill_fetch"
          },
          "inProcess": {
            "module": "src/tools/skill-fetch.ts"
          }
        },
        "x-mcp-tools": [
          "skill_fetch"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "skills-and-tools"
        ]
      }
    },
    "/tools/skill-list": {
      "post": {
        "operationId": "skill-list",
        "summary": "List skills",
        "description": "Every skill this layer can resolve, with its one-line summary. The entry point AGENTS.md sends an agent to first.",
        "tags": [
          "skills-and-tools"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/skill-list/"
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "skills": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Name and summary per skill."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/skill-list.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "skill_list"
          },
          "inProcess": {
            "module": "src/tools/skill-fetch.ts"
          }
        },
        "x-mcp-tools": [
          "skill_list"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "skills-and-tools"
        ]
      }
    },
    "/tools/skill-update": {
      "post": {
        "operationId": "skill-update",
        "summary": "Edit a skill",
        "description": "Change one existing local skill's instruction file through a gate: it must resolve as skill-fetch serves it, be tracked in the working repository, not be generated, be granted `skill-update` to the actor by a policy, be unchanged since it was read, keep its name and parse, and add only links that resolve. A gate that cannot decide refuses. Writes the working tree; the caller commits.",
        "tags": [
          "skills-and-tools"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/skill-update/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "skill": {
                    "$ref": "#/components/schemas/SkillName"
                  },
                  "package_name": {
                    "$ref": "#/components/schemas/PackageName"
                  },
                  "new_content": {
                    "$ref": "#/components/schemas/Markdown",
                    "description": "The whole new file: front matter and body."
                  },
                  "base_sha256": {
                    "$ref": "#/components/schemas/Text",
                    "description": "SHA-256 hex of the file as the caller read it."
                  },
                  "reason": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Why the skill changes."
                  },
                  "actor": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The declared actor making the write; a policy must grant it skill-update."
                  },
                  "process": {
                    "$ref": "#/components/schemas/ProcessId",
                    "description": "The BPMN process the write is a step of, for the PROV-O activity."
                  },
                  "task": {
                    "$ref": "#/components/schemas/NodeId",
                    "description": "The task in that process."
                  },
                  "role": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The role the lane binds."
                  }
                },
                "required": [
                  "skill",
                  "new_content",
                  "base_sha256",
                  "reason"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verdict": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Written or not, every gate's verdict with its reason, findings, and the PROV-O activity of an accepted write when a step was named."
                    },
                    "activity": {
                      "$ref": "#/components/schemas/ProvActivity",
                      "description": "The PROV-O activity of an accepted write that named its process, task and role; absent otherwise. Pass it to workflow_complete's `activities` for that step."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/skill-update.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "skill_update"
          },
          "inProcess": {
            "module": "src/tools/skill-update.ts"
          }
        },
        "x-mcp-tools": [
          "skill_update"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "skills-and-tools"
        ]
      }
    },
    "/tools/slice-sqlite": {
      "post": {
        "operationId": "slice-sqlite",
        "summary": "Per-slice SQLite builder",
        "description": "Build a named slice of a graph (beans, todos, library, or the whole-repo kg) as one SQLite file a browser mounts without parsing it, beside a manifest carrying its sha256, a row-content digest, its row counts and the search block the one search page reads. Heavy text is indexed by a contentless FTS5 and not stored; each row points at a content-addressed payload. `--check` builds every slice twice, requires one sha256, and requires the row digest read back from the file to equal the one computed from the source.",
        "tags": [
          "kg-export"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/slice-sqlite/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "slice": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "A slice to build; repeatable. Absent: every slice in the builder's table."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where the files and `index.json` go; defaults to the gitignored `docs/assets/slices/`. The deploy passes `./_site/assets/slices`."
                  },
                  "payloadOut": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where the deploy payloads are written (`<hex>` plus its `<hex>.json` sidecar). Never the committed `docs/payload/`."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Build twice and verify instead of writing: one sha256, the row digest against the source, an FTS5 phrase query, the payload audit."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slices": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`<slice>.<sha256>.sqlite3` (content-addressed) and its fixed-name `<slice>.sqlite3.json` manifest per slice, and `index.json` listing them."
                    },
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "One line per slice: bytes, row counts, payloads, and any source findings; with `--check`, one verdict line per slice. Exit 1 on a red slice or an unreadable source."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/slice-sqlite.jsonld",
        "x-invoke": {
          "shell": "bun run cat slice:sqlite"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "kg-export"
        ],
        "x-selection": {
          "when": "A corpus is too large to ship as JSON for a reader's search, or a reader needs to search it with no server: the work plan, the todos, the library, the knowledge graph.",
          "limits": "Built at deploy and never committed, so a slice describes the tree the deploy published and nothing later. A slice over the ~5 MB budget is reported (`overBudget` in the manifest), not refused. The file's sha256 is stable for one SQLite version; `contentDigest` is the cross-version identity.",
          "cost": "Seconds: the kg slice re-runs `kg-export` in-process (about 5 s); the other three take a quarter of a second each. Nothing to install, no network."
        }
      }
    },
    "/tools/smart-approach-svg": {
      "post": {
        "operationId": "smart-approach-svg",
        "summary": "WHO SMART Guidelines approach chart",
        "description": "Draw the WHO SMART Guidelines approach chart (knowledge layers L1–L5 with their products, and their country adaptations, between the research, localisation and impact bands) as SVG from `smart-guidelines-approach-figure/v1` data on a who-iris library entry, such as the product catalogue handbook's Fig. 5. Every label comes from the data.",
        "tags": [
          "figure-rebuild"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/smart-approach-svg/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "figure": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A smart-guidelines-approach-figure/v1 file."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write the SVG; stdout when absent."
                  }
                },
                "required": [
                  "figure"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "svg": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The chart, with text as SVG text, one `<g id=\"cell-l<n>-<name>\">` per layer cell."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/smart-approach-svg.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/smart-approach-svg.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "figure-rebuild"
        ],
        "x-selection": {
          "when": "A folio reprints the SMART Guidelines approach chart and should draw it from the one transcription instead of a picture.",
          "limits": "Draws the three-band, two-row layout only. Whether the transcription matches the published figure is a person's review of the data.",
          "cost": "Reads one JSON file; no network."
        }
      }
    },
    "/tools/stage-local": {
      "post": {
        "operationId": "stage-local",
        "summary": "Publish a folio's or an IG's site from the agent's own checkout — the one agent publish path",
        "description": "Build a repository's site in the agent's checkout and push it to the publish branch, as a preview or as the main site, without an Actions runner. Which build is read from the repository: a declared `site.build` recipe (built by `build-instance-site`), else the reusable workflow its own workflow files call — `folio-staging.yml` for a folio, the WHO SMART Base IG's `ghbuild.yml` for a FHIR IG, whose `build` job is planned step by step and run as written. For an IG it then applies the harness chrome over the built output (`sync-docs-harness`, then `rail-standalone-pages --foreign-site --instance <the IG>`): every page gains the rail and the icon row `#fa-navbar-row`, and the IG's own content is left byte for byte. A root publish is REFUSED when the chrome cannot be applied, and a clean root deploy is refused over any root whose `index.html` wears the icon row unless the new output does too, so a chromed root is never replaced by bare IG Publisher pages. Every run prints its plan first, and the plan lists the chrome step; `--plan` stops there, `--dry-run` composes the commit in a temporary worktree and pushes nothing, `--artifact` writes a claude.ai Artifact bundle instead.",
        "tags": [
          "feature-staging",
          "harness-tiles"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/stage-local/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The checkout to publish, with the platform's layers mounted at its root. Default: the working directory."
                  },
                  "branch": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch to publish. Default: the checkout's. The default branch publishes the main site; any other a preview."
                  },
                  "base": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "A folio preview's base branch, for its ChangeSet and rendered impact."
                  },
                  "main": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Publish the main site at the root. Implied on the default branch, refused off it."
                  },
                  "plan": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Print what would be built and where, every step named, and stop."
                  },
                  "dryRun": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Build and compose the commit in a temporary publish-branch worktree; push nothing."
                  },
                  "artifact": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Write a claude.ai Artifact bundle here instead of pushing."
                  },
                  "workflowSource": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "An IG: read the reusable workflow from this local checkout instead of fetching it at the ref its caller names."
                  },
                  "publisher": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "`folio` or `ig`, when the repository's workflows call both (the folio by default)."
                  },
                  "runUrl": {
                    "$ref": "#/components/schemas/Url",
                    "description": "What the commit and render log name as the run. Default: the commit's URL."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "$ref": "#/components/schemas/Url",
                      "description": "Where the site is served once GitHub's Pages deploy has run, with the commit pushed (or, with --dry-run, the commit composed and discarded)."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/stage-local.jsonld",
        "x-invoke": {
          "shell": "bun run cat stage:local"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": true
        },
        "x-satisfies": [
          "feature-staging",
          "harness-tiles"
        ],
        "x-selection": {
          "when": "Every agent-run publish of a folio's or an IG's site, preview or main: it is what the current build pipeline uses (the IG repositories' `site-publish.yml` run this same command on a runner).",
          "limits": "An IG repository's main site is built from its AST, read from the cache branch fhir-harness's `ig-ast-refresh` keeps current, by the steps its `site.build` recipe declares (`profile: ig-repo-site`): the theme side bar and search, the harness rail and icon row, the served directories and the `folio-build.json` stamp, measured against the live root (https://github.com/litlfred/cat-harness-tools/pull/202). A stale AST is refused, never built from Publisher HTML. A root publish is refused when the composed site lacks anything the current root has (`site-parity`), judged on the pages. Without a `site.build` recipe an IG falls back to its own workflow's Publisher steps, which need a Docker daemon and give the rail and icon row only.",
          "cost": "An IG: the whole IG Publisher build (tens of minutes), then about two minutes of rail over ~3,600 pages. A folio: its build command. Then one push, and GitHub's own Pages deploy."
        }
      }
    },
    "/tools/staging-graph-viewer": {
      "post": {
        "operationId": "staging-graph-viewer",
        "summary": "Staging-only graph viewer",
        "description": "Render a kept-but-unpublished workspace graph as one page, for a local build or a staging preview only; a canonical deploy withholds it.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/staging-graph-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/staging-graph-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat staging-graph:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/stakeholder-map": {
      "post": {
        "operationId": "stakeholder-map",
        "summary": "Stakeholder map",
        "description": "Given the paths a proposed change touches, report which skills change, which roles declare them, and who therefore has a stake in the review.",
        "tags": [
          "role-model"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/stakeholder-map/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "paths": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The changed paths. A repeated positional, so it is last on the command line."
                  }
                },
                "required": [
                  "paths"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stakeholders": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Skills, roles and the people each role names."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/stakeholder-map.jsonld",
        "x-invoke": {
          "shell": "bun run cat stakeholder-map",
          "mcp": {
            "tool": "stakeholder_map"
          },
          "inProcess": {
            "module": "src/tools/stakeholder-map.ts"
          }
        },
        "x-mcp-tools": [
          "stakeholder_map"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "role-model"
        ]
      }
    },
    "/tools/state-viewer": {
      "post": {
        "operationId": "state-viewer",
        "summary": "State graph viewer",
        "description": "Render each declared state graph with a projection as a dashboard page: what the work plan holds, and what state it is in.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/state-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  },
                  "scope": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "A scoped site build: the comma-separated instances whose pages this writer writes (the IG and the layer it lands on); every other instance's pages are linked on that layer's own site. Passed by the tools layer's `visualiser-writers.ts` (owner, 2026-11-08, Q-SZ-2 \"B\"). Absent: every instance."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/state-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat state:visualizer"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/sub-kg-verify-clone": {
      "post": {
        "operationId": "sub-kg-verify-clone",
        "summary": "Verify a separated repository from a fresh clone",
        "description": "Clone a separated sub-KG's repository (with submodules, and any sibling checkouts it needs) into an empty scratch directory, install, and run its gates: its `gates` script, else its `test` script (a person may pass `--gate` on the command line instead; it is not part of this contract because it is a shell command). Reports `green`, `red` or `unknown`; an empty tree, a failed clone or a repository with no gate is `unknown`, never green. Catches what a rehearsal inside this checkout cannot, because a rehearsal shares this checkout's `node_modules` and environment. Writes only inside the scratch directory.",
        "tags": [
          "sub-kg-lifecycle"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/sub-kg-verify-clone/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "The separated repository, `owner/name`. (The script also takes a git URL or a local path, for tests.)"
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch or tag to clone, e.g. the seeding PR's branch."
                  },
                  "sibling": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "A repository to clone beside it, for a platform linked as a sibling checkout. Repeatable."
                  },
                  "work": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Scratch directory, kept afterwards. Absent: a temporary directory, removed afterwards."
                  },
                  "text": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "A report for a person instead of JSON."
                  }
                },
                "required": [
                  "repo"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "`sub-kg-verify-clone/v1`: the commit cloned, each step with its status and output tail, and the verdict. Exit 0 green, 1 red, 2 unknown."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/sub-kg-verify-clone.jsonld",
        "x-invoke": {
          "shell": "bun run cat sub-kg:verify-clone"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": true
        },
        "x-satisfies": [
          "sub-kg-lifecycle"
        ],
        "x-selection": {
          "when": "After a sub-KG's staged contents are seeded into its new repository and re-pointed, before asking the owner about the cutover.",
          "limits": "Runs the repository's own gates as written; a gate that needs credentials or a service the clone cannot reach fails as it would for any new contributor.",
          "cost": "A clone plus an install plus the gates: minutes for a small repository."
        }
      }
    },
    "/tools/subgraph-index-package": {
      "post": {
        "operationId": "subgraph-index-package",
        "summary": "Package one pin's subgraph index files for a hydrated mount",
        "description": "Pack every built `index.jsonld` and `index.hydrated.jsonld` under a layer's `<docs>/subgraph/<harness>/` into ONE npm package for one pin — `<harness>-subgraph-index@0.0.0-pin.<sha>`, with a `folio-subgraph-index/v1` manifest giving each file's sha256 — through `pack-tarball` (`bun pm pack`), which also writes the tarball's `folio-binary-release/v1` record. The reusable workflow `layer-publish-subgraph-index.yml` attaches both to the GitHub release `subgraph-index-<sha>`, where `remote-mount` finds them for a `hydrated` source whose pin's git tree holds no index file (they are `builtAtPublish`, so none does). It builds nothing: run `subgraph:jsonld` first. No subgraph files under the layer is a refusal, never an empty package.",
        "tags": [
          "npm-kg-distribution",
          "remote-mount"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/subgraph-index-package/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root whose `<docs>/subgraph/<name>/` is packed."
                  },
                  "repository": {
                    "$ref": "#/components/schemas/RepoFullName",
                    "description": "owner/name of the repository the pin is a commit of."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/CommitSha",
                    "description": "The pin: the full 40-character commit the files were built from."
                  },
                  "outDir": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where the tarball and its release record are written."
                  },
                  "builtIn": {
                    "$ref": "#/components/schemas/PinnedRepo",
                    "description": "`<owner/name>@<40-char sha>` of the checkout the files were built in, recorded as provenance."
                  }
                },
                "required": [
                  "root",
                  "repository",
                  "ref",
                  "outDir"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tarball": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The package `.tgz`."
                    },
                    "release": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "Its `folio-binary-release/v1` record."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/subgraph-index-package.jsonld",
        "x-invoke": {
          "shell": "bun run cat subgraph-index:pack"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "npm-kg-distribution",
          "remote-mount"
        ]
      }
    },
    "/tools/subgraph-readmes": {
      "post": {
        "operationId": "subgraph-readmes",
        "summary": "Directory READMEs from the Knowledge Graph",
        "description": "Write a README for every directory a layer declares, from the declaration and the files themselves: the declared title and description, the Graph Typologies, and one row per file described from the file, with 'used by' only where a diagram records it. Renders the Liquid templates in `tools/templates/readme/`, part of the tools graph, which may include one another with Jekyll-style include tags. Writes only between `<!-- kg:subgraph:begin -->` and `:end`; a README without the markers is left alone and reported. Records every missing title, missing or over-long description, absent directory and unmarked README in `test/results/subgraph-readmes.qa-results.json`.",
        "tags": [
          "docs-generation",
          "upload-routes"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/subgraph-readmes/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if any directory README or the QA record is stale; write nothing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "readmes": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`<directory>/README.md` for each declared directory, and the QA record."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/subgraph-readmes.jsonld",
        "x-invoke": {
          "shell": "bun run cat readme:subgraphs"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "docs-generation",
          "upload-routes"
        ]
      }
    },
    "/tools/subgraph-resolve": {
      "post": {
        "operationId": "subgraph-resolve",
        "summary": "Resolve a declared subgraph's content source",
        "description": "Say where a declared subgraph gets its content — the checkout's own directory, a declared repository branch (with its keying), or a branch family (with its prefix, key and repository) — after the layer config's `subgraphSources` override by id, and which layer answered. The same `declaredSubgraph` resolver the KG export, the publishers and the mount tool use, so a shell sees the answer they act on.",
        "tags": [
          "directory-conventions"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/subgraph-resolve/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "A declared directory id. Repeatable; absent with `--all`."
                  },
                  "all": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Every subgraph the checkout declares."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Machine-readable output."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "source": {
                      "$ref": "#/components/schemas/Text",
                      "description": "One line per subgraph: its source kind and location, its declarer, and `declaredIn`. Exit 1 when no layer declares the id, 2 when the declaration contradicts itself or names an undeclared branch."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/subgraph-resolve.jsonld",
        "x-invoke": {
          "shell": "bun run cat subgraph:resolve"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "directory-conventions"
        ]
      }
    },
    "/tools/tabular-csv": {
      "post": {
        "operationId": "tabular-csv",
        "summary": "CSV tabular metadata",
        "description": "Read a delimited text file into a `folio-tabular-csvw/v1` record: one table, its columns and their CSVW datatypes, each measured or explicitly undetermined. Routing is by content, never by extension: the first rows must agree on one field count of two or more, under exactly one of `,` `;` TAB `|`. A CSV's `fac:anchor` sheet and cell are a determined null. Governed by the `tabular-metadata` skill.",
        "tags": [
          "tabular-metadata"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/tabular-csv/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "$ref": "#/components/schemas/DelimitedTextPath",
                    "description": "Path to the delimited text file."
                  },
                  "doc-id": {
                    "$ref": "#/components/schemas/DocId",
                    "description": "The record's `doc_id`. Default: the file name without its extension."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write `tabular.csvw.json`. Default: stdout."
                  }
                },
                "required": [
                  "file"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "record": {
                      "$ref": "#/components/schemas/Text",
                      "description": "A `folio-tabular-csvw/v1` document. Exit 2 when the file is not shown to be a table."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/tabular-csv.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/tabular-csv.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "tabular-metadata"
        ]
      }
    },
    "/tools/tabular-xlsx": {
      "post": {
        "operationId": "tabular-xlsx",
        "summary": "Spreadsheet tabular metadata",
        "description": "Read a workbook into a `folio-tabular-csvw/v1` record, one CSVW table per rectangular block of cells. Blocks are split on empty rows, then on empty columns, so several tables on one sheet are found, each anchored at its real top-left cell (`fac:anchor`: sheet, A1 cell, row, column). Dates are read through the number formats in `styles.xml`, not misread as integer serials. A malformed part is refused rather than half-read. Reads the ZIP with `node:zlib` and SpreadsheetML with `fast-xml-parser`. Governed by the `tabular-metadata` skill.",
        "tags": [
          "tabular-metadata"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "folio-assistant-core/tabular-xlsx/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "$ref": "#/components/schemas/WorkbookPath",
                    "description": "Path to the `.xlsx` workbook."
                  },
                  "doc-id": {
                    "$ref": "#/components/schemas/DocId",
                    "description": "The record's `doc_id`. Default: the file name without its extension."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where to write `tabular.csvw.json`. Default: stdout."
                  }
                },
                "required": [
                  "file"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "record": {
                      "$ref": "#/components/schemas/Text",
                      "description": "A `folio-tabular-csvw/v1` document, one table per block. Exit 2 when the file is not a SpreadsheetML workbook."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/tabular-xlsx.jsonld",
        "x-invoke": {
          "shell": "bun run folio-assistant-core/scripts/tabular-xlsx.ts"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "tabular-metadata"
        ]
      }
    },
    "/tools/theme-viewer": {
      "post": {
        "operationId": "theme-viewer",
        "summary": "Themes viewer",
        "description": "Render every theme in the checkout, the platform's and each layer's declared themes, with palette, contrast and art.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/theme-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/theme-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat theme:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/themes-css": {
      "post": {
        "operationId": "themes-css",
        "summary": "Theme stylesheet",
        "description": "Render the declared theme nodes into the stylesheet the site serves. The nodes are the source: a colour has one home, and light and dark are two valuations of one token set rather than two hand-kept blocks.",
        "tags": [
          "site-presentation-assets"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/themes-css/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Compare against the committed copy and fail if stale, instead of writing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stylesheet": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The generated stylesheet. Build output that happens to be committed, so it is readable on the forge — never hand-edited."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/themes-css.jsonld",
        "x-invoke": {
          "shell": "bun run cat themes:css"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "site-presentation-assets"
        ]
      }
    },
    "/tools/tool-coverage": {
      "post": {
        "operationId": "tool-coverage",
        "summary": "Which uncovered skills warrant a Tool?",
        "description": "Triage the skills that have no Tool by EVIDENCE rather than by grep: a serviceTask naming it or an I/O contract puts it in tier A, a userTask only in B, a shell block or a declared script in C, and nothing in D. The answer to \"which of these still have their mechanism inlined in their prose\".",
        "tags": [
          "code-node-review"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/tool-coverage/"
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "triage": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Four tiers with A, B and C listed by name and their evidence, D as a count. Always exit 0: this REPORTS a judgement queue and never gates; an uncovered skill is not a defect, and failing on one would turn CI red for stubbing a gap."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/tool-coverage.jsonld",
        "x-invoke": {
          "shell": "bun run cat tools:coverage"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "code-node-review"
        ],
        "x-selection": {
          "when": "When choosing what to give a Tool node next. Tier C is the read: its own label says THE READ GOES HERE, and tier A is the list to act on.",
          "limits": "It enumerates SKILLS and asks which lack Tools, so a capability nobody has stated generically is absent from the list it walks. It also cannot see a folio's entry points: `pipeline/*.ts` are invoked from a FOLIO's package.json, which is not readable from the platform.",
          "cost": "Seconds, plus loading every BPMN diagram to read task types."
        }
      }
    },
    "/tools/tool-schema": {
      "post": {
        "operationId": "tool-schema",
        "summary": "Tool node schema",
        "description": "The zod definition of a Tool node — what `defineTool` accepts — and the published JSON Schema generated from it.",
        "tags": [
          "kg-export"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/tool-schema/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "baseUrl": {
                    "$ref": "#/components/schemas/Url"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema": {
                      "$ref": "#/components/schemas/RepoPath"
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/tool-schema.jsonld",
        "x-invoke": {
          "shell": "bun run cat kg:schema"
        },
        "x-install": {
          "none": true
        },
        "x-satisfies": [
          "kg-export"
        ]
      }
    },
    "/tools/tool-types-schema": {
      "post": {
        "operationId": "tool-types-schema",
        "summary": "Tool I/O type vocabulary",
        "description": "The zod definitions of the shared types a Tool's inputs and outputs reference by IRI, and the published JSON Schemas those IRIs name: one document per type, `tool-types/<Name>.schema.json`, plus the combined `tool-types.schema.json`.",
        "tags": [
          "kg-export"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/tool-types-schema/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "baseUrl": {
                    "$ref": "#/components/schemas/Url"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema": {
                      "$ref": "#/components/schemas/RepoPath"
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/tool-types-schema.jsonld",
        "x-invoke": {
          "shell": "bun run cat kg:schema"
        },
        "x-install": {
          "none": true
        },
        "x-satisfies": [
          "kg-export"
        ]
      }
    },
    "/tools/tools-viewer": {
      "post": {
        "operationId": "tools-viewer",
        "summary": "Tools viewer",
        "description": "Render this layer's Tool nodes, and the skills each satisfies, as one page.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/tools-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  },
                  "scope": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "A scoped site build: the comma-separated instances whose per-layer Tools pages this writer writes; every other layer's Tools pages are linked on the platform's site, not copied (owner, 2026-11-13: \"other harnesses should be referenced not included\"). The combined index and API documents are still written. Passed by the tools layer's `visualiser-writers.ts`. Absent: every instance."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/tools-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat tools:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/transcribe-faster-whisper": {
      "post": {
        "operationId": "transcribe-faster-whisper",
        "summary": "Transcribe audio — faster-whisper (option, not installed)",
        "description": "Transcribe an audio file with faster-whisper (the Whisper models on CTranslate2), from Python. A declared OPTION: not installed in this repository.",
        "tags": [
          "library-ingestion"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/transcribe-faster-whisper/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "$ref": "#/components/schemas/RepoPath"
                  },
                  "language": {
                    "$ref": "#/components/schemas/Locale"
                  }
                },
                "required": [
                  "file"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transcript": {
                      "$ref": "#/components/schemas/RepoPath"
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/transcribe-faster-whisper.jsonld",
        "x-invoke": {
          "shell": "python3 -m faster_whisper"
        },
        "x-install": {
          "cli": "pip install faster-whisper (model weights download on first use)"
        },
        "x-requires": {
          "runtime": [
            "python3",
            "faster-whisper"
          ],
          "network": true
        },
        "x-satisfies": [
          "library-ingestion"
        ],
        "x-selection": {
          "when": "When the ingestion pipeline should stay in Python beside the PDF arms and `schemas/sdlc/python-deps.ts` is the one place dependencies are declared. Same models as whisper.cpp, typically faster on CPU.",
          "limits": "Weights download on first use unless pre-fetched — a network dependency in a gate that must run offline. A heavier wheel set than anything in `requirements.txt` today.",
          "cost": "Not installed. A pip install of several wheels plus the model; the CI install time must be re-measured before it is gated."
        }
      }
    },
    "/tools/transcribe-vosk": {
      "post": {
        "operationId": "transcribe-vosk",
        "summary": "Transcribe audio — vosk (option, not installed)",
        "description": "Transcribe an audio file with vosk (Kaldi-based), offline, from Python, with small per-language models. A declared OPTION: not installed in this repository.",
        "tags": [
          "library-ingestion"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/transcribe-vosk/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "$ref": "#/components/schemas/RepoPath"
                  },
                  "language": {
                    "$ref": "#/components/schemas/Locale"
                  }
                },
                "required": [
                  "file"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transcript": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "Written where `-o` names."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/transcribe-vosk.jsonld",
        "x-invoke": {
          "shell": "vosk-transcriber"
        },
        "x-install": {
          "cli": "pip install vosk, plus a per-language model (small ≈ 40–50 MB)"
        },
        "x-requires": {
          "runtime": [
            "python3",
            "vosk"
          ],
          "network": false
        },
        "x-satisfies": [
          "library-ingestion"
        ],
        "x-selection": {
          "when": "When size and speed matter more than accuracy: the lightest offline option, with a separate small model per language.",
          "limits": "Noticeably lower accuracy than the Whisper family on varied recordings; one model per language to fetch and keep.",
          "cost": "Not installed. Small wheel; ≈ 40–50 MB per language model."
        }
      }
    },
    "/tools/transcribe-whisper-cpp": {
      "post": {
        "operationId": "transcribe-whisper-cpp",
        "summary": "Transcribe audio — whisper.cpp (option, not installed)",
        "description": "Transcribe an audio file to a timed transcript with whisper.cpp, offline, on CPU. A declared OPTION: not installed in this repository until the first audio upload.",
        "tags": [
          "library-ingestion"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/transcribe-whisper-cpp/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The recording, under the declared `uploads` graph."
                  },
                  "language": {
                    "$ref": "#/components/schemas/Locale"
                  }
                },
                "required": [
                  "file"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transcript": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "Timed transcript under the entry's `transcript/`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/transcribe-whisper-cpp.jsonld",
        "x-invoke": {
          "shell": "whisper-cli"
        },
        "x-install": {
          "cli": "build whisper.cpp from source and download a ggml model (tiny ≈ 75 MB, base ≈ 142 MB)"
        },
        "x-requires": {
          "runtime": [
            "whisper-cli"
          ],
          "network": false
        },
        "x-satisfies": [
          "library-ingestion"
        ],
        "x-selection": {
          "when": "The default candidate: offline, no Python, good accuracy from the tiny model up, and timestamps per segment — what a transcript that can be translated segment by segment needs.",
          "limits": "A C++ build and a model file per container; weights are either vendored (repository size) or fetched at run time (a third-party host in the gate). Speaker labels are not included.",
          "cost": "Not installed. Build ≈ 1–2 min; tiny model ≈ 75 MB. CPU transcription runs near real time for tiny, slower for larger models."
        }
      }
    },
    "/tools/translation-adjudicate": {
      "post": {
        "operationId": "translation-adjudicate",
        "summary": "Record a translation adjudication",
        "description": "Turn one translation-review issue into the recorded adjudication: read the `issues` event (never the body from a shell variable), refuse an author who is not an owner, member or collaborator, refuse an item whose catalogue hash changed since the page showed it, then write the translation node's sign-off, the fuzzy suggestions and an append-only `translation-qa` attestation, and leave a Markdown summary. Exit 0 recorded, 3 nothing recorded, 2 could not determine.",
        "tags": [
          "translation-adjudication"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-adjudicate/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root holding the catalogues. Default: the current directory."
                  },
                  "event": {
                    "$ref": "#/components/schemas/FilesystemPath",
                    "description": "The `issues` event file GitHub wrote. Absent: `$GITHUB_EVENT_PATH`, which is how the workflow passes it."
                  },
                  "dry_run": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Plan and report, write nothing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "records": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The files written: catalogues, translation nodes and attestations under the layer's translations and attestation directories."
                    },
                    "summary": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "What was recorded and what was refused, with each reason — the issue comment and the PR body."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-adjudicate.jsonld",
        "x-invoke": {
          "shell": "bun run cat translation:adjudicate"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "translation-adjudication"
        ]
      }
    },
    "/tools/translation-adjudication-workflow": {
      "post": {
        "operationId": "translation-adjudication-workflow",
        "summary": "Translation adjudication workflow (reusable)",
        "description": "The tools layer's reusable `layer-translation-adjudication.yml`, called by a layer on `issues` events: runs once per issue labelled `translation-adjudication` or titled `[translation review] …`, mounts the platform's layers, runs `translation:adjudicate` on the event, and either commits the records on `translation-adjudication/issue-<n>` (authored by the issue's author) and opens a ready PR, or comments why nothing was recorded. It never merges.",
        "tags": [
          "translation-adjudication"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-adjudication-workflow/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "path_in_repo": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where the layer sits in the calling repository; `.` for the root."
                  },
                  "index_ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The folio-assistant ref whose lock mounts the platform's layers. Default `main`."
                  },
                  "tools_ref": {
                    "$ref": "#/components/schemas/Text",
                    "description": "`lock` (the caller's lock pin of the tools layer) or a 40-hex commit."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pull_request": {
                      "$ref": "#/components/schemas/Url",
                      "description": "The ready PR carrying the records, when anything was recorded."
                    },
                    "summary": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "The comment on the issue: what was recorded and what was refused."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-adjudication-workflow.jsonld",
        "x-invoke": {
          "manual": true
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": true
        },
        "x-satisfies": [
          "translation-adjudication"
        ]
      }
    },
    "/tools/translation-candidates": {
      "post": {
        "operationId": "translation-candidates",
        "summary": "Collect candidate translations from open engines",
        "description": "Ask one or more open, self-hosted machine translators — OPUS-MT (Helsinki-NLP Marian models, CC-BY 4.0, run locally) and/or a self-hosted LibreTranslate (AGPL, Argos models) — for CANDIDATE translations of each empty or fuzzy string, so no freemium API quota is involved. Candidates are appended to `<locale>/<catalogue>.candidates.json` (`translation-candidates/v1`) for a reviewer to choose among on the translation review page; a candidate whose placeholders or markup do not round-trip is not recorded. Candidates are never a barrier to having a translation: an EMPTY msgstr gets the first good candidate, marked `#, fuzzy`; a non-empty msgstr is never overwritten. The translation node records the source (`generatedBy: \"machine\"`, model, time); `official` is never set, and a candidate is never a verdict. A catalogue that says DO NOT MACHINE-FILL, or whose node is official, gets candidates but no fill.",
        "tags": [
          "translation-refresh",
          "translation-candidate-source"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-candidates/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root whose declared `translation-sources` directory is filled. Default: the current directory."
                  },
                  "engines": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "Comma-separated candidate sources, tried in this order for an empty msgstr: `opus-mt` (the local runner `scripts/translation/opus_mt_runner.py`, shared with `translate-pot`, which needs the extended Python tier) and/or `libretranslate` (the URL below). Absent, the command exits 2."
                  },
                  "url": {
                    "$ref": "#/components/schemas/Url",
                    "description": "A self-hosted LibreTranslate's base URL (default `http://localhost:5000`). The hosted libretranslate.com / .de services are refused."
                  },
                  "locales": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "Comma-separated locales to fill, e.g. `es,fr`. Default: every locale directory except the source locale."
                  },
                  "init": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Start a `.po` from each template that has none (locale named, `X-Folio-Official: no`, every msgstr empty), then collect candidates for it. Never the default: starting a catalogue is a decision."
                  },
                  "noCreateNode": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Record candidates for a catalogue with no translation node beside it, but fill nothing there, instead of writing a minimal `translation-node/v1` for it."
                  },
                  "noMask": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Send placeholders to the engine as they are, instead of as numbered stand-ins. The round-trip check runs either way."
                  },
                  "dryRun": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Translate and report, writing nothing."
                  }
                },
                "required": [
                  "engines"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "candidates": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`translations/<locale>/<catalogue>.candidates.json` (`translation-candidates/v1`), appended to: each candidate carries its text and source `{kind: \"open-mt\", id: <model>, version?, at}`. Identical text from the same source is not added twice."
                    },
                    "catalogues": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The `.po` catalogues whose empty msgstr got the first good candidate, `#, fuzzy`, and their `<name>.json` translation nodes. Exit 0 something was recorded · 3 nothing was · 2 could not determine · 1 an engine failed."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-candidates.jsonld",
        "x-invoke": {
          "shell": "bun run cat translation:candidates"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": true
        },
        "x-satisfies": [
          "translation-refresh",
          "translation-candidate-source"
        ],
        "x-selection": {
          "when": "A catalogue has empty or fuzzy entries and machine drafts are wanted for a reviewer to choose among on the translation review page. Every candidate is a draft; a person's adjudication decides.",
          "limits": "Singular entries only: plural entries are left for a person. Catalogues that say DO NOT MACHINE-FILL, and catalogues whose node is official, are refused. Machine output into a language nobody on the project reads cannot be checked here; it is a draft for review, never a sign-off. The LibreTranslate host is whatever `--url` names (normally one on this machine), so it has no fixed remedy; without one, use `--engine opus-mt`.",
          "cost": "OPUS-MT: a model download per language pair on first use (hundreds of MB) and CPU time, no per-string fee. LibreTranslate: whatever running your own instance costs."
        }
      }
    },
    "/tools/translation-candidates-agent": {
      "post": {
        "operationId": "translation-candidates-agent",
        "summary": "Candidate translations — agent model",
        "description": "An agent model proposes a translation for each string of a layer's catalogues, with the locale term base and the string's source context in front of it, and appends them to each catalogue's candidates sidecar with `source.kind: agent` and the model's id. Seeds an empty `msgstr` with the first candidate, fuzzy.",
        "tags": [
          "translation-candidate-source"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-candidates-agent/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root whose catalogues to propose for. Default: the current layer."
                  },
                  "locales": {
                    "$ref": "#/components/schemas/IdList",
                    "description": "The target locales. Absent: every locale the layer declares."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "candidates": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "`translations/<locale>/<catalogue>.candidates.json` (`translation-candidates/v1`), appended to; each candidate carries `source: {kind: \"agent\", id: <model>}`."
                    },
                    "catalogues": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The `.po` catalogues whose empty `msgstr` got the first candidate, `#, fuzzy`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-candidates-agent.jsonld",
        "x-invoke": {
          "manual": true
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "translation-candidate-source"
        ],
        "x-selection": {
          "when": "Prose that needs the surrounding meaning — paragraphs, diagram labels whose sense depends on the process, terms the locale term base fixes — and an agent session is already running.",
          "limits": "Not reproducible run to run, and its output is as unreviewed as any engine's. For many short, literal strings an open machine-translation model (OPUS-MT, LibreTranslate / Argos, through `translation:candidates`) is cheaper and repeatable.",
          "cost": "Model tokens per string, in a session that has a model; nothing to install."
        }
      }
    },
    "/tools/translation-extract": {
      "post": {
        "operationId": "translation-extract",
        "summary": "Extract translatable strings",
        "description": "Segment a folio's prose into a GNU gettext .pot template, leaving code, math and identifiers untranslated.",
        "tags": [
          "translation-manager"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-extract/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "path": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A markdown file or a directory of them."
                  },
                  "locale": {
                    "$ref": "#/components/schemas/Locale"
                  },
                  "project_name": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Recorded in the .pot header."
                  }
                },
                "required": [
                  "path"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pot": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The template written."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-extract.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "translation_extract"
          },
          "inProcess": {
            "module": "src/tools/translation.ts"
          }
        },
        "x-mcp-tools": [
          "translation_extract"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "translation-manager"
        ]
      }
    },
    "/tools/translation-inject": {
      "post": {
        "operationId": "translation-inject",
        "summary": "Inject translations",
        "description": "Produce a translated copy of a source markdown file from a .po, using the same segmentation the extractor used.",
        "tags": [
          "translation-manager"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-inject/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "source": {
                    "$ref": "#/components/schemas/RepoPath"
                  },
                  "po_file": {
                    "$ref": "#/components/schemas/RepoPath"
                  },
                  "locale": {
                    "$ref": "#/components/schemas/Locale"
                  }
                },
                "required": [
                  "source",
                  "po_file",
                  "locale"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "translated": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The translated copy written."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-inject.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "translation_inject"
          },
          "inProcess": {
            "module": "src/tools/translation.ts"
          }
        },
        "x-mcp-tools": [
          "translation_inject"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "translation-manager"
        ]
      }
    },
    "/tools/translation-platforms": {
      "post": {
        "operationId": "translation-platforms",
        "summary": "Exchange catalogues with a translation platform",
        "description": "For Weblate, Crowdin and Transifex: `export` writes the layout file a platform reads from the layer's declared `translation-sources` directory; `import` turns the `.po` changes a platform pushed onto the checked-out branch into CANDIDATES, never adjudications. Nothing here talks to a platform or the network. Exit 0 done, 1 `--check` found drift, 3 import found nothing to rewrite, 2 could not determine.",
        "tags": [
          "translation-candidate-source",
          "translation-manager"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-platforms/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "`export` or `import`."
                  },
                  "platform": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "`weblate`, `crowdin` or `transifex`."
                  },
                  "root": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "The layer root. Default: the current directory."
                  },
                  "base": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "import: the git ref the platform's changes are compared against."
                  },
                  "write": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "export: write the platform's file rather than print it."
                  },
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "export: fail when the committed file differs from what would be written."
                  },
                  "dry_run": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "import: plan and report, write nothing."
                  }
                },
                "required": [
                  "action",
                  "platform"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "The file written or the candidates recorded."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-platforms.jsonld",
        "x-invoke": {
          "shell": "bun run cat translation:platforms"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "translation-candidate-source",
          "translation-manager"
        ],
        "x-selection": {
          "when": "When a layer offers its catalogues to a translation platform, and when the platform's import workflow brings its changes back as candidates.",
          "limits": "Reads and writes files only; the platform's own push and pull happen outside it.",
          "cost": "One read of the layer's catalogues. No network."
        }
      }
    },
    "/tools/translation-qa-prune": {
      "post": {
        "operationId": "translation-qa-prune",
        "summary": "Prune round-trip rulings of removed strings",
        "description": "Drop the translation-semantic-roundtrip rulings of strings the catalogues no longer hold, and renumber the rest to catalogue order. Rulings are paired with strings by the hash of their msgid, so removing strings invalidates none and needs no agent re-run; this is the upkeep that follows. It only drops or renumbers: a verdict is never changed or invented, and a ruling for a string the ref's history never held (one recorded ahead of its PR) is kept.",
        "tags": [
          "translation-manager"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "who-iris/translation-qa-prune/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "write": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Apply the change to test/attestations/translation-qa/. Absent, it is a dry run that prints each dropped ruling and the renumbered spans."
                  },
                  "ref": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "Whose catalogues decide what was removed. Default origin/main: the state branch serves main and every branch, so a ruling goes only once main no longer holds its string."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "attestations": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "With --write, the rewritten `test/attestations/translation-qa/<catalogue>.<locale>.attestations.json`, to be pushed to `cat/who-iris/attestations`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/who-iris/tools/translation-qa-prune.jsonld",
        "x-invoke": {
          "shell": "bun run cat translation-qa:prune"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "git"
          ],
          "network": false
        },
        "x-satisfies": [
          "translation-manager"
        ]
      }
    },
    "/tools/translation-review-page": {
      "post": {
        "operationId": "translation-review-page",
        "summary": "Translation review page",
        "description": "The page a reviewer adjudicates on: `review.html` beside the translation status page, showing every catalogue × locale with its state (machine, flagged, reviewed, stale, official), each string's candidates, and the hash of the catalogue's bytes. Submitting opens GitHub's new-issue form prefilled with a `translation-adjudication/v1` record, or copies the body when it is too long for a URL.",
        "tags": [
          "translation-adjudication"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-review-page/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "page": {
                    "$ref": "#/components/schemas/Url",
                    "description": "The review page, `review.html` beside the translation status page of the published site."
                  }
                },
                "required": [
                  "page"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "issue": {
                      "$ref": "#/components/schemas/Url",
                      "description": "The new-issue form, prefilled; filing it is the adjudication."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-review-page.jsonld",
        "x-invoke": {
          "manual": true
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": true
        },
        "x-satisfies": [
          "translation-adjudication"
        ]
      }
    },
    "/tools/translation-roundtrip-record": {
      "post": {
        "operationId": "translation-roundtrip-record",
        "summary": "Record a round-trip translation verdict",
        "description": "Write a back-translation verdict, produced by a pair of translation agents, into a block's existing translation-QA sidecar. It records a judgement rather than making one, and refuses where no sidecar exists — a round trip cannot be what decides a block is translated.",
        "tags": [
          "translation-manager"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-roundtrip-record/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payload": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "JSON carrying the block, locale, verdict and the agent pair. Absent, the command exits 2 with its usage — measured, not assumed."
                  }
                },
                "required": [
                  "payload"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sidecar": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The `<block>.<locale>.translation-qa.json` written, under criterion `translation-semantic-roundtrip`. An AGENT entry replaces a previous agent entry — a re-run is a re-measurement of the same pair on the same text, not another line in a log — while a human ruling already recorded is kept, because this process does not supersede one."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-roundtrip-record.jsonld",
        "x-invoke": {
          "shell": "bun run cat translation:roundtrip"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "translation-manager"
        ]
      }
    },
    "/tools/translation-signoff": {
      "post": {
        "operationId": "translation-signoff",
        "summary": "Sign off a translation",
        "description": "Record a translation as official — who signed off, when, and the hash of the source it was signed against, so a later source edit is detectable.",
        "tags": [
          "translation-manager",
          "decision-audit"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-signoff/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "locale": {
                    "$ref": "#/components/schemas/Locale"
                  },
                  "source": {
                    "$ref": "#/components/schemas/RepoPath"
                  },
                  "signed_off_by": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Who is signing off."
                  },
                  "level": {
                    "$ref": "#/components/schemas/TranslationLevel"
                  }
                },
                "required": [
                  "locale",
                  "source",
                  "signed_off_by"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "record": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "The sign-off recorded, including the source hash."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-signoff.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "translation_signoff"
          },
          "inProcess": {
            "module": "src/tools/translation.ts"
          }
        },
        "x-mcp-tools": [
          "translation_signoff"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "translation-manager",
          "decision-audit"
        ]
      }
    },
    "/tools/translation-status": {
      "post": {
        "operationId": "translation-status",
        "summary": "Translation coverage",
        "description": "Per-locale translation coverage, computed from the .po files under the translations directory.",
        "tags": [
          "translation-manager"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-status/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "locale": {
                    "$ref": "#/components/schemas/Locale",
                    "description": "Absent means every locale."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "coverage": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Translated, fuzzy and untranslated counts per locale."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-status.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "translation_status"
          },
          "inProcess": {
            "module": "src/tools/translation.ts"
          }
        },
        "x-mcp-tools": [
          "translation_status"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "translation-manager"
        ]
      }
    },
    "/tools/translation-status-viewer": {
      "post": {
        "operationId": "translation-status-viewer",
        "summary": "Translation status viewer",
        "description": "Render the translation status of every declared translation-sources directory, per locale, as one page, and beside it the review page (`review.html`, with `assets/translation-status/review.json`) a reviewer adjudicates on.",
        "tags": [
          "graph-rendering",
          "translation-adjudication"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-status-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-status-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat translation:status"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering",
          "translation-adjudication"
        ]
      }
    },
    "/tools/translation-validate": {
      "post": {
        "operationId": "translation-validate",
        "summary": "Validate a translation",
        "description": "Check a .po against its .pot — every msgid present, none obsolete, placeholders preserved.",
        "tags": [
          "translation-manager"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/translation-validate/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pot_file": {
                    "$ref": "#/components/schemas/RepoPath"
                  },
                  "po_file": {
                    "$ref": "#/components/schemas/RepoPath"
                  },
                  "source": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Also check the .pot is current for this source."
                  }
                },
                "required": [
                  "pot_file",
                  "po_file"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "findings": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Missing, obsolete and malformed entries."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/translation-validate.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "translation_validate"
          },
          "inProcess": {
            "module": "src/tools/translation.ts"
          }
        },
        "x-mcp-tools": [
          "translation_validate"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "translation-manager"
        ]
      }
    },
    "/tools/uml-object-model": {
      "post": {
        "operationId": "uml-object-model",
        "summary": "Harness object model as PlantUML",
        "description": "Draw the harness object model (Actor, Role, Skill, Process, Task, Todo, Bean, tests, schemas) with every attribute read from the schema behind it. Each relationship names the field that carries it, and the generator refuses to write if that field is gone.",
        "tags": [
          "uml-overview"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/uml-object-model/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if the committed diagram is stale. Needs the beans CLI; without it the result is could-not-check (exit 2)."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "diagram": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The object-model diagram, in the layer's declared uml directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/uml-object-model.jsonld",
        "x-invoke": {
          "shell": "bun run cat uml:object-model"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "uml-overview"
        ]
      }
    },
    "/tools/uml-overview": {
      "post": {
        "operationId": "uml-overview",
        "summary": "UML overview per named sub-graph",
        "description": "Draw one UML class diagram per harness and one per named sub-graph it declares, as PlantUML, Mermaid and Graphviz DOT from one model, with every class read from the graph typology's node schema, and render the PlantUML to the SVG each page shows (needs Java; the check does not). The DOT is the page's Interactive view, laid out in the reader's browser by the site's vendored Graphviz WASM with draggable nodes. A kind with none is drawn as could-not-determine, never as an empty box.",
        "tags": [
          "uml-overview",
          "kg-subgraph-layout"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/uml-overview/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if any diagram, SVG or page is stale or orphaned, instead of writing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "diagrams": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "uml/overview/ (.puml and .mmd), their SVG renderings and Graphviz DOT beside them, and the docs/uml/overview/ pages that show them."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/uml-overview.jsonld",
        "x-invoke": {
          "shell": "bun run cat uml:overview"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "uml-overview",
          "kg-subgraph-layout"
        ]
      }
    },
    "/tools/upload-url": {
      "post": {
        "operationId": "upload-url",
        "summary": "Where to drop a file — the queue's upload URL",
        "description": "Compose the forge URL a person can drop a file at, from the layer's own declaration: the `uploads` graph's directory, resolved against the ROOT its scope names, expressed relative to the repository, and appended to the origin remote as GitHub's `/upload/<branch>/<path>`. Every failure is NAMED and no URL is guessed — no declaration, no declared `uploads` graph, a declared queue absent from disk, no `origin` remote, and a non-github.com remote each return a reason and a remedy instead. The declared path is relative to the LAYER and a forge URL needs it relative to the REPOSITORY, so pasting the declared path can mint a 404.",
        "tags": [
          "upload-routes",
          "content-acquisition"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/upload-url/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "branch": {
                    "$ref": "#/components/schemas/Branch",
                    "description": "The branch the upload form targets. Defaults to `main`; pass the working branch to send somebody to a pull request's head instead, so the upload lands on a commit CI judges."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The upload URL on stdout, exit 0 — or, on stderr and exit 1, the reason it could not be composed and the remedy for that reason. Never a guessed URL: a URL is believed, and somebody sent to a wrong one cannot tell it from an empty directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/upload-url.jsonld",
        "x-invoke": {
          "shell": "bun run cat upload:url"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "upload-routes",
          "content-acquisition"
        ],
        "x-selection": {
          "when": "You are about to tell somebody where to put a file, in any channel. Reach for it every time, not only when unsure: a hand-written path breaks silently when a directory moves. It also answers \"which queue\" when a checkout declares more than one (one per layer): the answer is whichever layer root you pass, never a literal.",
          "limits": "It answers WHERE, and nothing else. It does not upload, does not check whether the person has write access, and cannot tell you which of several declared queues should own a given file — that is undecided and `upload-routes` says so rather than picking. The `/upload/<branch>/<path>` form is GitHub's, so another forge gets a named refusal rather than a guess. And the URL it hands back opens the route with the FEWEST guarantees: the web form has no working tree, so no pre-commit hook and no generator run happen on it, and everything `upload-routes` lists has to be discharged afterwards from a checkout.",
          "cost": "One read of the declaration and one of the git remote; no network at run time and nothing installed."
        }
      }
    },
    "/tools/uploads-viewer": {
      "post": {
        "operationId": "uploads-viewer",
        "summary": "Uploads viewer",
        "description": "Render each declared uploads directory's intakes as a page per subject layer.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/uploads-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/uploads-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat uploads:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/user-auth": {
      "post": {
        "operationId": "user-auth",
        "summary": "Who is asking, and what may they do",
        "description": "User authentication and authorization. Asks GitHub for the caller's login and repository role, maps the role to a gateway actor, and answers from the ODRL policies — for an action, or for a BPMN step. Always states that GitHub's role covers the whole repository, not a sub-graph, node or query path.",
        "tags": [
          "task-authorization",
          "deployment-auth"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/user-auth/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "actor": {
                    "$ref": "#/components/schemas/Text",
                    "description": "A declared actor the caller is acting as."
                  },
                  "action": {
                    "$ref": "#/components/schemas/Text",
                    "description": "An ODRL action to ask about, e.g. content-authoring."
                  },
                  "process": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Process id, to scope the question or check a task."
                  },
                  "task": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Node id; with process, runs the task-authorization check."
                  },
                  "role": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The role the lane binds."
                  },
                  "target": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The content acted on."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "answer": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Identity, GitHub role, ODRL grants and decisions, and what GitHub's grain cannot express."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/user-auth.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "auth_whoami"
          },
          "inProcess": {
            "module": "src/tools/auth.ts"
          }
        },
        "x-mcp-tools": [
          "auth_whoami"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": true
        },
        "x-satisfies": [
          "task-authorization",
          "deployment-auth"
        ]
      }
    },
    "/tools/vocab-map": {
      "post": {
        "operationId": "vocab-map",
        "summary": "Apply a vocabulary mapping table",
        "description": "Carry one source record into a target vocabulary by a declared `folio-vocab-mapping/v1` table: each source field becomes the predicate its row names, in the table's order, with a DERIVED target (such as `dcterms:title` rendering `skos:prefLabel`) copied from its authoritative one so the two cannot drift. A table is shaped like a FHIR ConceptMap: an existing ConceptMap, R4 or R5, is representable as one without loss (`fromConceptMap`), and a table can be produced as a ConceptMap (`toConceptMap`), which returns every loss rather than dropping anything silently. First consumer: `glossary-export`.",
        "tags": [
          "vocabulary-authority"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/vocab-map/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "table": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "The table's id, resolved from this layer's declared `vocab-mapping` directories. An unknown id is an error naming the directories searched, never an empty result."
                  },
                  "record": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The source record, as a JSON object whose keys are the table's element codes. An absent, null, empty-string or empty-array value writes nothing."
                  }
                },
                "required": [
                  "table",
                  "record"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "properties": {
                      "$ref": "#/components/schemas/Text",
                      "description": "The mapped properties as a JSON object, keyed by each target's JSON term. Two rows writing one key is refused, not resolved."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/vocab-map.jsonld",
        "x-invoke": {
          "inProcess": {
            "module": "schemas/content/vocab-mapping.ts",
            "register": "applyVocabMapping"
          }
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "vocabulary-authority"
        ]
      }
    },
    "/tools/voices-viewer": {
      "post": {
        "operationId": "voices-viewer",
        "summary": "Voices viewer",
        "description": "Render each declared voices directory as a page per subject layer.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/voices-viewer/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Fail if a page is stale, instead of writing."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the pages at their declared route under it instead of under the harness's own site directory. A repository's own site build passes it (the tools layer's `visualiser-writers.ts`), since its harness docs are a pinned mount."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "The viewer pages, under the published site directory."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/voices-viewer.jsonld",
        "x-invoke": {
          "shell": "bun run cat voices:viz"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "graph-rendering"
        ]
      }
    },
    "/tools/web-app-build": {
      "post": {
        "operationId": "web-app-build",
        "summary": "Web app build",
        "description": "Build every declared `web-app` directory in the checkout and publish each at its own route, `<locale>/<harness>/apps/<id>/`, with no site chrome (every page marked `folio-navbar: none`), plus an `apps/` index in the site's chrome listing each app with its languages and size. Before building, each locale's translated UI strings are written from the layer's `translations/<locale>/apps/<id>.po` to the app's `i18n.out`, so building is the injection. `--extract` writes the translation templates; `--check` validates the declarations and translations and builds nothing.",
        "tags": [
          "graph-rendering"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/web-app-build/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Validate every declaration (manifest, build script, lockfile, route clashes) and translation (templates current, placeholders kept, no stale entries); build nothing."
                  },
                  "extract": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Write each app's translation templates, `translations/<locale>/apps/<id>.pot`, in the declaring layer: the app's \"refresh the templates\" step of the translation process."
                  },
                  "site": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "A site being built: write the apps and the index at their declared route under it instead of under the harness's own site directory."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pages": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "Each app's build under `<locale>/<harness>/apps/<id>/`, and the index page at `<locale>/<harness>/apps/`."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/web-app-build.jsonld",
        "x-invoke": {
          "shell": "bun run cat web-apps:build"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "node"
          ],
          "network": true
        },
        "x-satisfies": [
          "graph-rendering"
        ],
        "x-selection": {
          "when": "A site build of a checkout in which any layer declares a `web-app` directory; run with the other declared writers (`visualiser-writers.ts`). `--extract` whenever an app's catalog changes, as the translation watcher's template step; `--check` in the declaring layer's PR checks.",
          "limits": "Builds with npm or bun from the app's lockfile, so it needs the npm registry. An app's pages are its own: the Tool marks them chrome-less and does not otherwise change them. Untranslated strings fall back to the source text in the app.",
          "cost": "One install and one build per app; seconds to a minute each."
        }
      }
    },
    "/tools/wireframe-check": {
      "post": {
        "operationId": "wireframe-check",
        "summary": "Wireframe check at web and mobile viewports",
        "description": "Render each mid-fidelity wireframe candidate of one topic at a web viewport (1280x800) and a mobile viewport (390x844). For each viewport it records `script` entries for renders, no-overflow and no-placeholder, each pass or fail with a note. It writes a screenshot per viewport and a report.json carrying the use, topic and surface, and exits 1 on any fail and 2 when the candidate set is not one the use admits.",
        "tags": [
          "wireframe-viewport-check"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/wireframe-check/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "use": {
                    "$ref": "#/components/schemas/WireframeUse",
                    "description": "`design` or `as-is`. Design needs at least two candidates, compared blind; as-is candidates are drawings of what renders on main, each marked `as-is` in its file name. Anything else exits 2."
                  },
                  "topic": {
                    "$ref": "#/components/schemas/Slug",
                    "description": "Which wireframe is checked: its asset directory, docs/wireframes/<topic>/ for as-is use and docs/proposals/<topic>/wireframes/ for design use (docs/wireframes/<topic>/ is also accepted there). With no candidates, every .html in it is checked; a candidate outside it is refused."
                  },
                  "surface": {
                    "$ref": "#/components/schemas/SurfaceRef",
                    "description": "What is drawn: a visualiser route key or a chrome name. Recorded in report.json; for as-is use it must be the topic itself or a ref docs/wireframes/index.json says the topic covers."
                  },
                  "candidates": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Wireframe HTML files, all in the topic's directory. Absent: every .html there. Each must carry both a web and a mobile layout (responsive CSS or two layouts)."
                  },
                  "out": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Where screenshots and report.json go; default <the topic's directory>/checks."
                  }
                },
                "required": [
                  "use",
                  "topic",
                  "surface"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/RepoPath",
                      "description": "report.json: per candidate, per viewport, per criterion. The screenshots are beside it."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/wireframe-check.jsonld",
        "x-invoke": {
          "shell": "bun run cat wireframe:check"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun",
            "chromium"
          ],
          "network": false
        },
        "x-satisfies": [
          "wireframe-viewport-check"
        ],
        "x-skill-contracts": {
          "wireframe-viewport-check.input": {
            "$ref": "#/components/schemas/skill.wireframe-viewport-check.input"
          },
          "wireframe-viewport-check.output": {
            "$ref": "#/components/schemas/skill.wireframe-viewport-check.output"
          }
        }
      }
    },
    "/tools/witness-conformance": {
      "post": {
        "operationId": "witness-conformance",
        "summary": "Witness conformance report",
        "description": "Check every `*.witness.json` in the folio's declared `computation-witness` directories against the two schemas in `schemas/computation-witness.ts`: the envelope every witness should meet (a failure is a malformed file) and the producer contract (a failure is a finding against the producer, grouped by the fields at fault). Also lists files that are not strict JSON, which Python's reader accepts and every other consumer rejects. Report-only: it never edits a witness, which is generator output.",
        "tags": [
          "directory-conventions"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/witness-conformance/"
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dir": {
                    "$ref": "#/components/schemas/RepoPath",
                    "description": "Check this directory instead of the declared ones, e.g. before a folio declares the kind."
                  },
                  "json": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Machine-readable output, every finding group listed."
                  },
                  "strict": {
                    "$ref": "#/components/schemas/Flag",
                    "description": "Exit 1 when any witness is malformed or not strict JSON. Contract findings never fail the run."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/Text",
                      "description": "Counts of witnesses, malformed files, non-strict-JSON files and contract conformance, then the contract findings by field. Exit 2 when no directory declares the kind and no `--dir` was given: a clean report over nothing is not a pass."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/witness-conformance.jsonld",
        "x-invoke": {
          "shell": "bun run cat witness:conformance"
        },
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "directory-conventions"
        ]
      }
    },
    "/tools/work-plan-prime": {
      "post": {
        "operationId": "work-plan-prime",
        "summary": "Prime the work plan",
        "description": "Load the current work plan for this session — the same committed beans store the CLI reads, so a fresh container starts from the plan rather than from nothing.",
        "tags": [
          "todo-manager",
          "bean-coordination",
          "session-intent",
          "pending-show"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/work-plan-prime/"
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "priming": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Open items, the roadmap, and what each is waiting on."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/work-plan-prime.jsonld",
        "x-invoke": {
          "shell": "beans prime",
          "mcp": {
            "tool": "work_plan_prime"
          },
          "inProcess": {
            "module": "src/tools/beans-prime.ts"
          }
        },
        "x-mcp-tools": [
          "work_plan_prime"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "todo-manager",
          "bean-coordination",
          "session-intent",
          "pending-show"
        ]
      }
    },
    "/tools/workflow-complete": {
      "post": {
        "operationId": "workflow-complete",
        "summary": "Complete a step",
        "description": "Record an enabled step as done — or supply the facts a decision gateway is computed from — and advance the layer. Refuses a step that is not enabled.",
        "tags": [
          "process-state",
          "bean-coordination"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/workflow-complete/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/InstanceId"
                  },
                  "node": {
                    "$ref": "#/components/schemas/NodeId"
                  },
                  "outcome": {
                    "$ref": "#/components/schemas/NodeId",
                    "description": "Which branch a plain gateway takes. Refused at a gateway backed by a decision table — asserting the answer would defeat the table."
                  },
                  "facts": {
                    "$ref": "#/components/schemas/DecisionFacts",
                    "description": "Facts a DMN table is evaluated against. Structured, so it is never a command-line word."
                  },
                  "actor": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Who you say performed the step, written to the history. Authorization is decided on the principal GitHub vouches for, in strict mode (issue #1207)."
                  },
                  "target": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The content the step acted on, for the access check."
                  },
                  "note": {
                    "$ref": "#/components/schemas/Markdown",
                    "description": "Appended to the layer's bean."
                  },
                  "activities": {
                    "$ref": "#/components/schemas/ProvActivity",
                    "description": "PROV-O activities a Tool returned while doing this step, verbatim (e.g. skill_update's `activity`). Kept on the step's history entry; each must name this step as its plan."
                  }
                },
                "required": [
                  "instance",
                  "node"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "position": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "The layer's new position, and what is enabled next."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/workflow-complete.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "workflow_complete"
          },
          "inProcess": {
            "module": "src/tools/workflow.ts"
          }
        },
        "x-mcp-tools": [
          "workflow_complete"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "process-state",
          "bean-coordination"
        ]
      }
    },
    "/tools/workflow-gate": {
      "post": {
        "operationId": "workflow-gate",
        "summary": "May this step be performed?",
        "description": "Ask before doing work a strict process governs. The content-agnostic processes refuse a step that is not enabled; the per-content-type ones advise.",
        "tags": [
          "process-state"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/workflow-gate/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/InstanceId"
                  },
                  "activity": {
                    "$ref": "#/components/schemas/NodeId"
                  },
                  "actor": {
                    "$ref": "#/components/schemas/Text",
                    "description": "Who you say would perform it. Recorded only: strict mode authorizes the principal GitHub vouches for (issue #1207)."
                  },
                  "target": {
                    "$ref": "#/components/schemas/Text",
                    "description": "The content it would act on, for the access check."
                  }
                },
                "required": [
                  "instance",
                  "activity"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verdict": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Permitted, refused with the reason, or advisory — and the task-authorization verdict."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/workflow-gate.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "workflow_gate"
          },
          "inProcess": {
            "module": "src/tools/workflow.ts"
          }
        },
        "x-mcp-tools": [
          "workflow_gate"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "process-state"
        ]
      }
    },
    "/tools/workflow-list": {
      "post": {
        "operationId": "workflow-list",
        "summary": "List processes",
        "description": "The BPMN processes this layer defines, and the layers currently open against them.",
        "tags": [
          "process-state"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/workflow-list/"
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "processes": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Each process, its policy, and its open layers."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/workflow-list.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "workflow_list"
          },
          "inProcess": {
            "module": "src/tools/workflow.ts"
          }
        },
        "x-mcp-tools": [
          "workflow_list"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "process-state"
        ]
      }
    },
    "/tools/workflow-next": {
      "post": {
        "operationId": "workflow-next",
        "summary": "What is enabled now",
        "description": "The activities a layer may work right now, each with the lane that owns it and the skill that implements it.",
        "tags": [
          "process-state"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/workflow-next/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instance": {
                    "$ref": "#/components/schemas/InstanceId"
                  }
                },
                "required": [
                  "instance"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "$ref": "#/components/schemas/Markdown",
                      "description": "Activity, lane and skill for each enabled step."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/workflow-next.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "workflow_next"
          },
          "inProcess": {
            "module": "src/tools/workflow.ts"
          }
        },
        "x-mcp-tools": [
          "workflow_next"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "process-state"
        ]
      }
    },
    "/tools/workflow-start": {
      "post": {
        "operationId": "workflow-start",
        "summary": "Start a process instance",
        "description": "Open an instance of a process for a subject. Idempotent: an existing layer for the same subject is returned rather than duplicated.",
        "tags": [
          "process-state",
          "bean-coordination"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "cat-harness/workflow-start/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "process": {
                    "$ref": "#/components/schemas/ProcessId"
                  },
                  "subject": {
                    "$ref": "#/components/schemas/Text",
                    "description": "What the layer is about — a block label, a release, a bean."
                  },
                  "bean": {
                    "$ref": "#/components/schemas/BeanId",
                    "description": "The work-plan item this layer carries out."
                  },
                  "plan": {
                    "$ref": "#/components/schemas/BeanId",
                    "description": "The work plan this layer is part of: an epic or milestone whose `process:` tag names this process. Not every process needs one."
                  }
                },
                "required": [
                  "process",
                  "subject"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "instance": {
                      "$ref": "#/components/schemas/InstanceId",
                      "description": "The layer opened or found."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tools/workflow-start.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "workflow_start"
          },
          "inProcess": {
            "module": "src/tools/workflow.ts"
          }
        },
        "x-mcp-tools": [
          "workflow_start"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "network": false
        },
        "x-satisfies": [
          "process-state",
          "bean-coordination"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ArchimateMetamodelFormat": {
        "type": "string",
        "enum": [
          "text",
          "json",
          "dot",
          "mmd"
        ],
        "description": "A plain-text report, archimate-metamodel/v1 JSON, Graphviz DOT, or a Mermaid class diagram.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ArchimateMetamodelFormat"
      },
      "ArchimateModelId": {
        "type": "string",
        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
        "description": "An ArchiMate model's id in cat-archimate.config.json, e.g. 0.2.0",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ArchimateModelId"
      },
      "BeanClaimCheck": {
        "type": "object",
        "properties": {
          "bean": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "claimed",
              "would-claim",
              "skip-recent-commit",
              "skip-claim-note",
              "skip-open-pr",
              "skip-closed",
              "unknown"
            ]
          },
          "copies": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "repo": {
                  "type": "string"
                },
                "ref": {
                  "type": "string"
                },
                "recent": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "author": {
                        "type": "string"
                      },
                      "at": {
                        "type": "string"
                      },
                      "subject": {
                        "type": "string"
                      },
                      "session": {
                        "type": "string"
                      },
                      "agent": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "author",
                      "at",
                      "subject",
                      "agent"
                    ],
                    "additionalProperties": false
                  }
                },
                "status": {
                  "type": "string"
                },
                "claimCommit": {
                  "type": "string"
                },
                "pushAttempts": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                }
              },
              "required": [
                "repo",
                "ref",
                "recent"
              ],
              "additionalProperties": false
            }
          },
          "openWork": {
            "type": "object",
            "properties": {
              "query": {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "path",
                      "prefix",
                      "bean"
                    ]
                  },
                  "value": {
                    "type": "string"
                  }
                },
                "required": [
                  "kind",
                  "value"
                ],
                "additionalProperties": false
              },
              "checkedAt": {
                "type": "string"
              },
              "hits": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "repo": {
                      "type": "string"
                    },
                    "where": {
                      "type": "string",
                      "enum": [
                        "default-branch",
                        "open-pr"
                      ]
                    },
                    "pr": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "head": {
                      "type": "string"
                    },
                    "author": {
                      "type": "string"
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "match": {
                      "type": "string",
                      "enum": [
                        "file",
                        "title",
                        "body",
                        "branch"
                      ]
                    },
                    "paths": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "repo",
                    "where",
                    "match"
                  ],
                  "additionalProperties": false
                }
              },
              "unread": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "query",
              "checkedAt",
              "hits",
              "unread"
            ],
            "additionalProperties": false,
            "description": "Where a path, prefix or bean id exists on main or an open PR head; `unread` names what could not be read."
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "bean",
          "state",
          "copies",
          "openWork",
          "reason"
        ],
        "additionalProperties": false,
        "description": "Whether a bean was claimed, or why it was skipped, with what each copy of the work plan showed.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/BeanClaimCheck"
      },
      "BeanId": {
        "type": "string",
        "pattern": "^[a-z0-9-]+$",
        "description": "A bean identifier, e.g. folio-assistant-1dfh",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/BeanId"
      },
      "BeanQueryRows": {
        "type": "array",
        "items": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "string"
          }
        },
        "description": "The rows a bean SPARQL query returned, each variable to its value; bean IRIs are shortened to bean ids.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/BeanQueryRows"
      },
      "BeanStatus": {
        "type": "string",
        "enum": [
          "draft",
          "todo",
          "in-progress",
          "completed",
          "scrapped"
        ],
        "description": "A bean status. Exactly what `beans update --status` accepts.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/BeanStatus"
      },
      "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"
      },
      "ChangeProposalNumber": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991,
        "description": "A change-proposal number — a pull request on GitHub, a merge request on GitLab",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ChangeProposalNumber"
      },
      "ChangeSetAction": {
        "type": "string",
        "enum": [
          "seed",
          "propose",
          "add",
          "list",
          "body",
          "adopt",
          "check",
          "reconcile",
          "github",
          "install"
        ],
        "description": "A change-set verb: check or reconcile the records, or handle one GitHub issue event.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ChangeSetAction"
      },
      "CommitSha": {
        "type": "string",
        "pattern": "^[0-9a-f]{7,40}$",
        "description": "A git commit sha, full or abbreviated (7-40 hex digits).",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/CommitSha"
      },
      "ContentType": {
        "type": "string",
        "enum": [
          "paper",
          "document"
        ],
        "description": "A folio's content type. `paper` extends `document` — see AGENTS.md on content types.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ContentType"
      },
      "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"
      },
      "DecisionFacts": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": [
            "string",
            "number",
            "boolean"
          ]
        },
        "description": "Facts for a DMN decision table. Scalar values only. Not admissible as a command-line argument.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/DecisionFacts"
      },
      "DelimitedTextPath": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[A-Za-z0-9._][A-Za-z0-9._/-]*$",
        "description": "A repository path to a delimited text (CSV or TSV) file.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/DelimitedTextPath"
      },
      "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"
      },
      "DrainQueue": {
        "type": "object",
        "properties": {
          "refreshedAt": {
            "type": "string"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "repo": {
                  "type": "string"
                },
                "ref": {
                  "type": "string"
                },
                "sha": {
                  "type": "string"
                }
              },
              "required": [
                "repo",
                "ref",
                "sha"
              ],
              "additionalProperties": false
            }
          },
          "byOwner": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "owner": {
                  "type": "string"
                },
                "beans": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      },
                      "priority": {
                        "type": "string"
                      },
                      "lastTouch": {
                        "type": "object",
                        "properties": {
                          "author": {
                            "type": "string"
                          },
                          "at": {
                            "type": "string"
                          },
                          "agent": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "author",
                          "at",
                          "agent"
                        ],
                        "additionalProperties": false
                      },
                      "skip": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "title",
                      "status",
                      "type",
                      "priority"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "owner",
                "beans"
              ],
              "additionalProperties": false
            }
          },
          "spare": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "priority": {
                  "type": "string"
                },
                "lastTouch": {
                  "type": "object",
                  "properties": {
                    "author": {
                      "type": "string"
                    },
                    "at": {
                      "type": "string"
                    },
                    "agent": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "author",
                    "at",
                    "agent"
                  ],
                  "additionalProperties": false
                },
                "skip": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "title",
                "status",
                "type",
                "priority"
              ],
              "additionalProperties": false
            }
          },
          "excluded": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "reason": {
                  "type": "string",
                  "enum": [
                    "goal",
                    "epic",
                    "blocked",
                    "completed",
                    "scrapped",
                    "draft",
                    "owner-held"
                  ]
                },
                "detail": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "reason"
              ],
              "additionalProperties": false
            }
          },
          "disagreements": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "byCopy": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {
                    "type": "string"
                  }
                },
                "used": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "byCopy",
                "used"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "refreshedAt",
          "sources",
          "byOwner",
          "spare",
          "excluded",
          "disagreements"
        ],
        "additionalProperties": false,
        "description": "The beans that can be drained, by owner, with what was excluded and why.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/DrainQueue"
      },
      "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"
      },
      "HarnessStates": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "$schema": {
              "type": "string",
              "const": "folio-harness-state/v1"
            },
            "harness": {
              "type": "string",
              "minLength": 1
            },
            "initialization": {
              "type": "object",
              "properties": {
                "position": {
                  "type": "string",
                  "minLength": 1
                },
                "next": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "step": {
                          "type": "string",
                          "minLength": 1
                        },
                        "action": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "step",
                        "action"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "counts": {
                  "type": "object",
                  "properties": {
                    "done": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    "not-done": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    "could-not-determine": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    "stated": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    }
                  },
                  "required": [
                    "done",
                    "not-done",
                    "could-not-determine",
                    "stated"
                  ],
                  "additionalProperties": false
                },
                "steps": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "minLength": 1
                      },
                      "namedBy": {
                        "type": "string",
                        "minLength": 1
                      },
                      "what": {
                        "type": "string"
                      },
                      "state": {
                        "type": "string",
                        "enum": [
                          "done",
                          "not-done",
                          "could-not-determine",
                          "stated"
                        ]
                      },
                      "detail": {
                        "type": "string"
                      },
                      "action": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "namedBy",
                      "what",
                      "state",
                      "detail"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "position",
                "next",
                "counts",
                "steps"
              ],
              "additionalProperties": false
            },
            "health": {
              "type": "object",
              "properties": {
                "badges": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "enum": [
                          "initialization",
                          "repository"
                        ]
                      },
                      "state": {
                        "type": "string",
                        "enum": [
                          "ok",
                          "finding",
                          "unknown"
                        ]
                      },
                      "label": {
                        "type": "string",
                        "minLength": 1
                      }
                    },
                    "required": [
                      "id",
                      "state",
                      "label"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "badges"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "$schema",
            "harness",
            "initialization",
            "health"
          ],
          "additionalProperties": false
        },
        "description": "Every harness's initialization position, next step and health badges, in name order.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/HarnessStates"
      },
      "IdList": {
        "type": "string",
        "pattern": "^[A-Za-z0-9][A-Za-z0-9._/-]*(?:,[A-Za-z0-9][A-Za-z0-9._/-]*)*$",
        "description": "Comma-separated ids, e.g. skills,processes/sdlc or bean-query,agent-memory",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/IdList"
      },
      "InstanceId": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
        "description": "A workflow instance id — the stem of a file in the bean graph's workflow-state node",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/InstanceId"
      },
      "LinkMode": {
        "type": "string",
        "enum": [
          "submodule",
          "sibling",
          "remote"
        ],
        "description": "How a new folio links the platform: a git submodule, a sibling checkout, or pinned remote mounts in index.config.json.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/LinkMode"
      },
      "LinkStyle": {
        "type": "string",
        "enum": [
          "blob",
          "pages",
          "raw"
        ],
        "description": "How a README link addresses its target.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/LinkStyle"
      },
      "Locale": {
        "type": "string",
        "minLength": 2,
        "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$",
        "description": "A BCP-47 language tag, e.g. en or fr-CA",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Locale"
      },
      "Login": {
        "type": "string",
        "pattern": "^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$",
        "description": "A GitHub account name, e.g. litlfred",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Login"
      },
      "Markdown": {
        "type": "string",
        "description": "Markdown text. Not admissible as a command-line argument — see INJECTION_SAFE.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Markdown"
      },
      "MountChoice": {
        "type": "string",
        "pattern": "^[a-z0-9][a-z0-9-]*(?::[a-z0-9][a-z0-9-]*)?$",
        "description": "A mount entry and instance to write a choice to, e.g. cat-harness or cat-harness:cat-harness-tools",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/MountChoice"
      },
      "MountSeed": {
        "type": "string",
        "pattern": "^[a-z0-9][a-z0-9-]*=[A-Za-z0-9][A-Za-z0-9-]*\\/[A-Za-z0-9._-]+@[0-9a-f]{40}$",
        "description": "A remote instance to seed, e.g. <instance>=<owner>/<repo>@<40-hex sha>",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/MountSeed"
      },
      "NamespaceLayer": {
        "type": "string",
        "enum": [
          "bootstrap",
          "harness",
          "core"
        ],
        "description": "A namespace layer: bootstrap resolves before anything else, then harness, then core.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/NamespaceLayer"
      },
      "NodeId": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$",
        "description": "A node id within a BPMN process, e.g. A_Implement",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/NodeId"
      },
      "OpenWorkLookup": {
        "type": "object",
        "properties": {
          "query": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "path",
                  "prefix",
                  "bean"
                ]
              },
              "value": {
                "type": "string"
              }
            },
            "required": [
              "kind",
              "value"
            ],
            "additionalProperties": false
          },
          "checkedAt": {
            "type": "string"
          },
          "hits": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "repo": {
                  "type": "string"
                },
                "where": {
                  "type": "string",
                  "enum": [
                    "default-branch",
                    "open-pr"
                  ]
                },
                "pr": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                "head": {
                  "type": "string"
                },
                "author": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "match": {
                  "type": "string",
                  "enum": [
                    "file",
                    "title",
                    "body",
                    "branch"
                  ]
                },
                "paths": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "repo",
                "where",
                "match"
              ],
              "additionalProperties": false
            }
          },
          "unread": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "query",
          "checkedAt",
          "hits",
          "unread"
        ],
        "additionalProperties": false,
        "description": "Where a path, prefix or bean id exists on main or an open PR head; `unread` names what could not be read.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/OpenWorkLookup"
      },
      "PackageName": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[a-z][a-z0-9-]*$",
        "description": "A skill package, e.g. folio-core",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/PackageName"
      },
      "PinnedRepo": {
        "type": "string",
        "pattern": "^[A-Za-z0-9][A-Za-z0-9-]*\\/[A-Za-z0-9._-]+@[0-9a-f]{40}$",
        "description": "A repository at one commit, e.g. <owner>/<repo>@<40-hex sha>",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/PinnedRepo"
      },
      "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"
      },
      "ProcessId": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[a-z][a-z0-9-]*$",
        "description": "A BPMN process id, e.g. crdm-requirements",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ProcessId"
      },
      "ProvActivity": {
        "type": "object",
        "properties": {
          "@type": {
            "type": "string",
            "const": "prov:Activity"
          },
          "@id": {
            "type": "string",
            "minLength": 1
          },
          "prov:startedAtTime": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
          },
          "prov:endedAtTime": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
          },
          "prov:qualifiedAssociation": {
            "type": "object",
            "properties": {
              "prov:agent": {
                "type": "string",
                "minLength": 1
              },
              "prov:hadRole": {
                "type": "string",
                "minLength": 1
              },
              "prov:hadPlan": {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9-]*#[A-Za-z_][A-Za-z0-9_.-]*$"
              }
            },
            "required": [
              "prov:agent",
              "prov:hadRole",
              "prov:hadPlan"
            ],
            "additionalProperties": false
          },
          "prov:actedOnBehalfOf": {
            "type": "string",
            "minLength": 1
          },
          "prov:used": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1
                },
                {
                  "type": "object",
                  "properties": {
                    "@id": {
                      "type": "string",
                      "pattern": "^[a-z][a-z0-9+.-]*:\\S+$"
                    },
                    "@type": {
                      "type": "array",
                      "prefixItems": [
                        {
                          "type": "string",
                          "const": "prov:Entity"
                        },
                        {
                          "type": "string",
                          "const": "dcat:Distribution"
                        }
                      ],
                      "items": false,
                      "minItems": 2,
                      "maxItems": 2
                    },
                    "spdx:checksum": {
                      "type": "object",
                      "properties": {
                        "@type": {
                          "type": "string",
                          "const": "spdx:Checksum"
                        },
                        "spdx:algorithm": {
                          "type": "string",
                          "enum": [
                            "spdx:checksumAlgorithm_sha256",
                            "spdx:checksumAlgorithm_sha512"
                          ]
                        },
                        "spdx:checksumValue": {
                          "type": "string",
                          "pattern": "^[0-9a-f]+$"
                        }
                      },
                      "required": [
                        "spdx:algorithm",
                        "spdx:checksumValue"
                      ],
                      "additionalProperties": false
                    },
                    "dcat:downloadURL": {
                      "type": "string",
                      "pattern": "^[a-z][a-z0-9+.-]*:\\S+$"
                    }
                  },
                  "required": [
                    "@id",
                    "@type",
                    "spdx:checksum"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "@id": {
                      "type": "string",
                      "pattern": "^[a-z][a-z0-9+.-]*:\\S+$"
                    },
                    "@type": {
                      "type": "array",
                      "prefixItems": [
                        {
                          "type": "string",
                          "const": "prov:Entity"
                        },
                        {
                          "type": "string",
                          "const": "cred:VerifiableCredential"
                        }
                      ],
                      "items": false,
                      "minItems": 2,
                      "maxItems": 2
                    }
                  },
                  "required": [
                    "@id",
                    "@type"
                  ],
                  "additionalProperties": false
                }
              ]
            }
          },
          "prov:generated": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "prov:wasInformedBy": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                }
              }
            ]
          },
          "cat-harness:underPolicy": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                }
              }
            ]
          },
          "cat-harness:consent": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1
              },
              "versionId": {
                "type": "string",
                "minLength": 1
              }
            },
            "required": [
              "id",
              "versionId"
            ],
            "additionalProperties": false
          },
          "cat-harness:consentBased": {
            "type": "boolean"
          },
          "cat-harness:previousHash": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "cat-harness:recordHash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          }
        },
        "required": [
          "@type",
          "@id",
          "prov:startedAtTime",
          "prov:qualifiedAssociation",
          "cat-harness:underPolicy"
        ],
        "additionalProperties": false,
        "description": "A PROV-O activity (schemas/content/prov.ts). Structured. Not admissible as a command-line argument.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ProvActivity"
      },
      "ReadmeSection": {
        "type": "string",
        "enum": [
          "folio:toc",
          "folio:lean-coverage",
          "folio:lean-modules",
          "folio:simulators",
          "folio:workflows",
          "skills:index"
        ],
        "description": "A generated README section, named by its marker.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ReadmeSection"
      },
      "RenderEvent": {
        "type": "string",
        "enum": [
          "rendered",
          "removed",
          "restored",
          "retained"
        ],
        "description": "A render-log event: rendered, removed, restored or retained.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RenderEvent"
      },
      "RepoFullName": {
        "type": "string",
        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*\\/[A-Za-z0-9][A-Za-z0-9._-]*$",
        "description": "A forge repository's full name, owner/name",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoFullName"
      },
      "RepoPath": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[A-Za-z0-9._][A-Za-z0-9._/-]*$",
        "description": "A path relative to the repository root. No `..` segments.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath"
      },
      "ScriptName": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]*$",
        "description": "A package script name",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ScriptName"
      },
      "SessionSweep": {
        "type": "object",
        "properties": {
          "since": {
            "type": "string"
          },
          "commitsScanned": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "sessions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "session": {
                  "type": "string"
                },
                "commits": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                "first": {
                  "type": "string"
                },
                "last": {
                  "type": "string"
                },
                "branches": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "latestSubject": {
                  "type": "string"
                }
              },
              "required": [
                "session",
                "commits",
                "first",
                "last",
                "branches",
                "latestSubject"
              ],
              "additionalProperties": false
            }
          },
          "untrailered": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "since",
          "commitsScanned",
          "sessions",
          "untrailered"
        ],
        "additionalProperties": false,
        "description": "The sessions that committed in a window, read from Claude-Session trailers.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/SessionSweep"
      },
      "skill.content-test.input": {
        "title": "Content Test Input",
        "description": "Input schema for end-to-end content testing.",
        "type": "object",
        "required": [
          "targetPath"
        ],
        "properties": {
          "targetPath": {
            "type": "string"
          },
          "testPlan": {
            "type": "string",
            "description": "Path to test plan file."
          },
          "testData": {
            "type": "string",
            "description": "Path to test data directory."
          },
          "regressionBaseline": {
            "type": "string",
            "description": "Git ref for regression baseline."
          }
        }
      },
      "skill.content-test.output": {
        "title": "Content Test Output",
        "description": "Output schema for content testing results.",
        "type": "object",
        "required": [
          "overallStatus",
          "testResults"
        ],
        "properties": {
          "overallStatus": {
            "type": "string",
            "enum": [
              "pass",
              "fail"
            ]
          },
          "testResults": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "testId",
                "status"
              ],
              "properties": {
                "testId": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "pass",
                    "fail",
                    "skipped"
                  ]
                },
                "message": {
                  "type": "string"
                },
                "duration": {
                  "type": "number"
                }
              }
            }
          },
          "coverage": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "passed": {
                "type": "integer"
              },
              "failed": {
                "type": "integer"
              },
              "skipped": {
                "type": "integer"
              }
            }
          },
          "stagingLinks": {
            "$ref": "#/components/schemas/skill.content-test.output.stagingLinks",
            "description": "The staging preview of the work this output asks a person to look at: one deep link per changed page, with the same page on main. Required whenever a preview exists; when it does not, say so in `missing`. Rule: cat-harness skills/authoring/content-lifecycle/feedback-deep-links.md."
          }
        }
      },
      "skill.content-test.output.stagingLinks": {
        "title": "Staging links",
        "description": "The staging preview of the work a request for feedback is about: one deep link per changed page (the page and the anchor where the change sits) with the same page on main as `before`. Mirrors StagingComparison in schemas/sdlc/staging.ts. The rule is skills/authoring/content-lifecycle/feedback-deep-links.md. Copied inline as `definitions.stagingLinks` into every skill contract that carries it; schemas/staging.test.ts fails when a copy drifts.",
        "type": "object",
        "required": [
          "branch",
          "slug",
          "branchUrl",
          "mainBaseUrl",
          "stagingBaseUrl",
          "pages"
        ],
        "properties": {
          "branch": {
            "type": "string",
            "description": "Feature branch name."
          },
          "slug": {
            "type": "string",
            "description": "Branch slug used in the staging URL path."
          },
          "branchUrl": {
            "type": "string",
            "format": "uri"
          },
          "pr": {
            "type": "integer",
            "minimum": 1
          },
          "mainBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "stagingBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "pages": {
            "type": "array",
            "description": "One entry per changed page, deep-linked; from the change's rendered-impact list, never chosen by judgement.",
            "items": {
              "type": "object",
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "before": {
                  "type": "string",
                  "format": "uri",
                  "description": "Same page on main; absent for a new page."
                },
                "after": {
                  "type": "string",
                  "format": "uri",
                  "description": "The page on the staging preview, with the anchor where the change sits; absent for a deleted page."
                },
                "summary": {
                  "type": "string",
                  "description": "What to look at on this page."
                }
              }
            }
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What could not be linked, said rather than hidden: no preview yet (and when it will exist), no page list computed, or a changed page the publish ref does not hold."
          }
        },
        "$comment": "Copy of cat-harness schemas/staging-comparison.schema.json; cat-harness schemas/staging.test.ts fails when a copy drifts."
      },
      "skill.content-validate.input": {
        "title": "Content Validate Input",
        "description": "Input schema for content validation.",
        "type": "object",
        "required": [
          "targetPath"
        ],
        "properties": {
          "targetPath": {
            "type": "string",
            "description": "Path to content to validate."
          },
          "validationRules": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Specific validation rule IDs to run (empty = all applicable)."
          },
          "schemaRefs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Schema files to validate against."
          },
          "stagingLinks": {
            "$ref": "#/components/schemas/skill.content-validate.input.stagingLinks",
            "description": "The staging preview of the work under review, as the request for feedback carried it, so the reviewer opens the changed pages rather than rebuilding links. Rule: cat-harness skills/authoring/content-lifecycle/feedback-deep-links.md."
          }
        }
      },
      "skill.content-validate.input.stagingLinks": {
        "title": "Staging links",
        "description": "The staging preview of the work a request for feedback is about: one deep link per changed page (the page and the anchor where the change sits) with the same page on main as `before`. Mirrors StagingComparison in schemas/sdlc/staging.ts. The rule is skills/authoring/content-lifecycle/feedback-deep-links.md. Copied inline as `definitions.stagingLinks` into every skill contract that carries it; schemas/staging.test.ts fails when a copy drifts.",
        "type": "object",
        "required": [
          "branch",
          "slug",
          "branchUrl",
          "mainBaseUrl",
          "stagingBaseUrl",
          "pages"
        ],
        "properties": {
          "branch": {
            "type": "string",
            "description": "Feature branch name."
          },
          "slug": {
            "type": "string",
            "description": "Branch slug used in the staging URL path."
          },
          "branchUrl": {
            "type": "string",
            "format": "uri"
          },
          "pr": {
            "type": "integer",
            "minimum": 1
          },
          "mainBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "stagingBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "pages": {
            "type": "array",
            "description": "One entry per changed page, deep-linked; from the change's rendered-impact list, never chosen by judgement.",
            "items": {
              "type": "object",
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "before": {
                  "type": "string",
                  "format": "uri",
                  "description": "Same page on main; absent for a new page."
                },
                "after": {
                  "type": "string",
                  "format": "uri",
                  "description": "The page on the staging preview, with the anchor where the change sits; absent for a deleted page."
                },
                "summary": {
                  "type": "string",
                  "description": "What to look at on this page."
                }
              }
            }
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What could not be linked, said rather than hidden: no preview yet (and when it will exist), no page list computed, or a changed page the publish ref does not hold."
          }
        },
        "$comment": "Copy of cat-harness schemas/staging-comparison.schema.json; cat-harness schemas/staging.test.ts fails when a copy drifts."
      },
      "skill.content-validate.output": {
        "title": "Content Validate Output",
        "description": "Output schema for content validation results.",
        "type": "object",
        "required": [
          "overallStatus",
          "results"
        ],
        "properties": {
          "overallStatus": {
            "type": "string",
            "enum": [
              "pass",
              "warnings",
              "errors"
            ]
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "rule",
                "status"
              ],
              "properties": {
                "rule": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "pass",
                    "fail",
                    "warning",
                    "skipped"
                  ]
                },
                "message": {
                  "type": "string"
                },
                "location": {
                  "type": "string"
                }
              }
            }
          },
          "stagingLinks": {
            "$ref": "#/components/schemas/skill.content-validate.output.stagingLinks",
            "description": "The staging preview of the work this output asks a person to look at: one deep link per changed page, with the same page on main. Required whenever a preview exists; when it does not, say so in `missing`. Rule: cat-harness skills/authoring/content-lifecycle/feedback-deep-links.md."
          }
        }
      },
      "skill.content-validate.output.stagingLinks": {
        "title": "Staging links",
        "description": "The staging preview of the work a request for feedback is about: one deep link per changed page (the page and the anchor where the change sits) with the same page on main as `before`. Mirrors StagingComparison in schemas/sdlc/staging.ts. The rule is skills/authoring/content-lifecycle/feedback-deep-links.md. Copied inline as `definitions.stagingLinks` into every skill contract that carries it; schemas/staging.test.ts fails when a copy drifts.",
        "type": "object",
        "required": [
          "branch",
          "slug",
          "branchUrl",
          "mainBaseUrl",
          "stagingBaseUrl",
          "pages"
        ],
        "properties": {
          "branch": {
            "type": "string",
            "description": "Feature branch name."
          },
          "slug": {
            "type": "string",
            "description": "Branch slug used in the staging URL path."
          },
          "branchUrl": {
            "type": "string",
            "format": "uri"
          },
          "pr": {
            "type": "integer",
            "minimum": 1
          },
          "mainBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "stagingBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "pages": {
            "type": "array",
            "description": "One entry per changed page, deep-linked; from the change's rendered-impact list, never chosen by judgement.",
            "items": {
              "type": "object",
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "before": {
                  "type": "string",
                  "format": "uri",
                  "description": "Same page on main; absent for a new page."
                },
                "after": {
                  "type": "string",
                  "format": "uri",
                  "description": "The page on the staging preview, with the anchor where the change sits; absent for a deleted page."
                },
                "summary": {
                  "type": "string",
                  "description": "What to look at on this page."
                }
              }
            }
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What could not be linked, said rather than hidden: no preview yet (and when it will exist), no page list computed, or a changed page the publish ref does not hold."
          }
        },
        "$comment": "Copy of cat-harness schemas/staging-comparison.schema.json; cat-harness schemas/staging.test.ts fails when a copy drifts."
      },
      "skill.public-comment.input": {
        "title": "Public Comment Input",
        "description": "Input schema for the public-comment skill: one operation on the public-review comment store of a document folio.",
        "type": "object",
        "required": [
          "operation"
        ],
        "properties": {
          "operation": {
            "type": "string",
            "enum": [
              "import",
              "import-narrative",
              "list",
              "triage",
              "reassign",
              "assign",
              "recommend",
              "decide",
              "incorporate",
              "duplicate",
              "withdraw",
              "github",
              "summary"
            ],
            "description": "One task of public-comment.bpmn, or a read (list, summary)."
          },
          "file": {
            "type": "string",
            "description": "For import / import-narrative: the comment matrix (.xlsx), form export (.csv) or narrative text."
          },
          "ref": {
            "type": "string",
            "pattern": "^PC-\\d{4,}$",
            "description": "The comment the operation acts on."
          },
          "to": {
            "type": "string",
            "description": "reassign/triage: a block or section label. assign: GitHub login(s), comma-separated."
          },
          "code": {
            "type": "string",
            "enum": [
              "accepted",
              "accepted-modified",
              "not-accepted",
              "noted",
              "deferred"
            ],
            "description": "recommend / decide: the decision code."
          },
          "reason": {
            "type": "string",
            "description": "decide: required for every code but accepted."
          },
          "branch": {
            "type": "string",
            "description": "decide / incorporate: the change-set branch."
          },
          "pr": {
            "type": "integer",
            "description": "decide / incorporate: the change-set pull request."
          },
          "filter": {
            "type": "object",
            "description": "list: narrow by status (or 'open'), page, line, block, section, or unplaced.",
            "properties": {
              "status": {
                "type": "string"
              },
              "page": {
                "type": "integer"
              },
              "line": {
                "type": "integer"
              },
              "block": {
                "type": "string"
              },
              "section": {
                "type": "string"
              },
              "unplaced": {
                "type": "boolean"
              }
            }
          },
          "stagingLinks": {
            "$ref": "#/components/schemas/skill.public-comment.input.stagingLinks",
            "description": "The staging preview of the work under review, as the request for feedback carried it, so the reviewer opens the changed pages rather than rebuilding links. Rule: cat-harness sdlc/skills/sdlc-core/staging-review.md §\"The deep-link rule\"."
          }
        }
      },
      "skill.public-comment.input.stagingLinks": {
        "title": "Staging links",
        "description": "The staging preview of the work a request for feedback is about: one deep link per changed page (the page and the anchor where the change sits) with the same page on main as `before`. Mirrors StagingComparison in schemas/sdlc/staging.ts. The rule is skills/authoring/content-lifecycle/feedback-deep-links.md. Copied inline as `definitions.stagingLinks` into every skill contract that carries it; schemas/staging.test.ts fails when a copy drifts.",
        "type": "object",
        "required": [
          "branch",
          "slug",
          "branchUrl",
          "mainBaseUrl",
          "stagingBaseUrl",
          "pages"
        ],
        "properties": {
          "branch": {
            "type": "string",
            "description": "Feature branch name."
          },
          "slug": {
            "type": "string",
            "description": "Branch slug used in the staging URL path."
          },
          "branchUrl": {
            "type": "string",
            "format": "uri"
          },
          "pr": {
            "type": "integer",
            "minimum": 1
          },
          "mainBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "stagingBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "pages": {
            "type": "array",
            "description": "One entry per changed page, deep-linked; from the change's rendered-impact list, never chosen by judgement.",
            "items": {
              "type": "object",
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "before": {
                  "type": "string",
                  "format": "uri",
                  "description": "Same page on main; absent for a new page."
                },
                "after": {
                  "type": "string",
                  "format": "uri",
                  "description": "The page on the staging preview, with the anchor where the change sits; absent for a deleted page."
                },
                "summary": {
                  "type": "string",
                  "description": "What to look at on this page."
                }
              }
            }
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What could not be linked, said rather than hidden: no preview yet (and when it will exist), no page list computed, or a changed page the publish ref does not hold."
          }
        },
        "$comment": "Copy of cat-harness schemas/staging-comparison.schema.json; cat-harness schemas/staging.test.ts fails when a copy drifts."
      },
      "skill.public-comment.output": {
        "title": "Public Comment Output",
        "description": "Output schema for the public-comment skill.",
        "type": "object",
        "properties": {
          "changed": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Comment refs written by the operation."
          },
          "unplaced": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "import: refs whose citation resolved to no block, kept for triage."
          },
          "refused": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What was not done, and why: a tag from someone not in config.json, a transition the lifecycle does not allow."
          },
          "comments": {
            "type": "array",
            "description": "list: the matching public-comment/1.0.0 records."
          },
          "stagingLinks": {
            "$ref": "#/components/schemas/skill.public-comment.output.stagingLinks",
            "description": "The staging preview of the work this output asks a person to look at: one deep link per changed page, with the same page on main. Required whenever a preview exists; when it does not, say so in `missing`. Rule: cat-harness sdlc/skills/sdlc-core/staging-review.md §\"The deep-link rule\"."
          }
        }
      },
      "skill.public-comment.output.stagingLinks": {
        "title": "Staging links",
        "description": "The staging preview of the work a request for feedback is about: one deep link per changed page (the page and the anchor where the change sits) with the same page on main as `before`. Mirrors StagingComparison in schemas/sdlc/staging.ts. The rule is skills/authoring/content-lifecycle/feedback-deep-links.md. Copied inline as `definitions.stagingLinks` into every skill contract that carries it; schemas/staging.test.ts fails when a copy drifts.",
        "type": "object",
        "required": [
          "branch",
          "slug",
          "branchUrl",
          "mainBaseUrl",
          "stagingBaseUrl",
          "pages"
        ],
        "properties": {
          "branch": {
            "type": "string",
            "description": "Feature branch name."
          },
          "slug": {
            "type": "string",
            "description": "Branch slug used in the staging URL path."
          },
          "branchUrl": {
            "type": "string",
            "format": "uri"
          },
          "pr": {
            "type": "integer",
            "minimum": 1
          },
          "mainBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "stagingBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "pages": {
            "type": "array",
            "description": "One entry per changed page, deep-linked; from the change's rendered-impact list, never chosen by judgement.",
            "items": {
              "type": "object",
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "before": {
                  "type": "string",
                  "format": "uri",
                  "description": "Same page on main; absent for a new page."
                },
                "after": {
                  "type": "string",
                  "format": "uri",
                  "description": "The page on the staging preview, with the anchor where the change sits; absent for a deleted page."
                },
                "summary": {
                  "type": "string",
                  "description": "What to look at on this page."
                }
              }
            }
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What could not be linked, said rather than hidden: no preview yet (and when it will exist), no page list computed, or a changed page the publish ref does not hold."
          }
        },
        "$comment": "Copy of cat-harness schemas/staging-comparison.schema.json; cat-harness schemas/staging.test.ts fails when a copy drifts."
      },
      "skill.staging-review.input": {
        "title": "Staging Review Input",
        "description": "What the reader wants to look at, in their own words (kept verbatim; it narrows, never adds), and the branch or pull request whose preview to list.",
        "type": "object",
        "properties": {
          "ask": {
            "type": "string",
            "description": "What the reader wants to look at, verbatim. Absent: the whole preview, every page the branch changed."
          },
          "branch": {
            "type": "string"
          },
          "pr": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "skill.staging-review.output": {
        "title": "Staging Review Output",
        "description": "The reviewable list: a narrative of what changed, where to start, and the staging links, one deep link per changed page with its before. Every other skill that asks for feedback carries this same `stagingLinks` shape.",
        "type": "object",
        "required": [
          "narrative",
          "stagingLinks"
        ],
        "properties": {
          "narrative": {
            "type": "string",
            "description": "What a reader of the site will now see or do differently, and why, before any link."
          },
          "startHere": {
            "type": "string",
            "format": "uri",
            "description": "The one page to open first."
          },
          "stagingLinks": {
            "$ref": "#/components/schemas/skill.staging-review.output.stagingLinks"
          }
        }
      },
      "skill.staging-review.output.stagingLinks": {
        "title": "Staging links",
        "description": "The staging preview of the work a request for feedback is about: one deep link per changed page (the page and the anchor where the change sits) with the same page on main as `before`. Mirrors StagingComparison in schemas/sdlc/staging.ts. The rule is skills/authoring/content-lifecycle/feedback-deep-links.md. Copied inline as `definitions.stagingLinks` into every skill contract that carries it; schemas/staging.test.ts fails when a copy drifts.",
        "type": "object",
        "required": [
          "branch",
          "slug",
          "branchUrl",
          "mainBaseUrl",
          "stagingBaseUrl",
          "pages"
        ],
        "properties": {
          "branch": {
            "type": "string",
            "description": "Feature branch name."
          },
          "slug": {
            "type": "string",
            "description": "Branch slug used in the staging URL path."
          },
          "branchUrl": {
            "type": "string",
            "format": "uri"
          },
          "pr": {
            "type": "integer",
            "minimum": 1
          },
          "mainBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "stagingBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "pages": {
            "type": "array",
            "description": "One entry per changed page, deep-linked; from the change's rendered-impact list, never chosen by judgement.",
            "items": {
              "type": "object",
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "before": {
                  "type": "string",
                  "format": "uri",
                  "description": "Same page on main; absent for a new page."
                },
                "after": {
                  "type": "string",
                  "format": "uri",
                  "description": "The page on the staging preview, with the anchor where the change sits; absent for a deleted page."
                },
                "summary": {
                  "type": "string",
                  "description": "What to look at on this page."
                }
              }
            }
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What could not be linked, said rather than hidden: no preview yet (and when it will exist), no page list computed, or a changed page the publish ref does not hold."
          }
        },
        "$comment": "Copy of cat-harness schemas/staging-comparison.schema.json; cat-harness schemas/staging.test.ts fails when a copy drifts."
      },
      "skill.wireframe-viewport-check.input": {
        "title": "Wireframe Viewport Check Input",
        "description": "The wireframe candidates to render, and where the screenshots and report go. Called from wireframe-design-review step 3, once per round of candidates.",
        "type": "object",
        "required": [
          "candidates"
        ],
        "properties": {
          "candidates": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            },
            "description": "Wireframe HTML files. Each must carry both a web and a mobile layout (responsive CSS or two layouts)."
          },
          "out": {
            "type": "string",
            "description": "Where the screenshots and report.json go: the asset directory's checks/ (wireframe-design-review, 'Where wireframes live'). Absent: .build/wireframes."
          }
        },
        "additionalProperties": false
      },
      "skill.wireframe-viewport-check.output": {
        "title": "Wireframe Viewport Check Output",
        "description": "Per candidate, per viewport (web 1280x800, mobile 390x844), a pass or fail entry for each mechanical criterion (renders, no-overflow, no-placeholder) with a note, and a screenshot per viewport. Pass/fail entries only, never a score (the wiregen methodology).",
        "type": "object",
        "required": [
          "report",
          "candidates"
        ],
        "properties": {
          "report": {
            "type": "string",
            "description": "The report.json path; the screenshots are beside it."
          },
          "candidates": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "source",
                "screenshots",
                "entries"
              ],
              "properties": {
                "source": {
                  "type": "string",
                  "description": "The candidate's HTML path."
                },
                "screenshots": {
                  "type": "object",
                  "required": [
                    "web",
                    "mobile"
                  ],
                  "properties": {
                    "web": {
                      "type": "string"
                    },
                    "mobile": {
                      "type": "string"
                    }
                  }
                },
                "entries": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/skill.wireframe-viewport-check.output.criterionEntry"
                  }
                }
              }
            }
          },
          "stagingLinks": {
            "$ref": "#/components/schemas/skill.wireframe-viewport-check.output.stagingLinks"
          }
        }
      },
      "skill.wireframe-viewport-check.output.criterionEntry": {
        "type": "object",
        "required": [
          "criterion",
          "status"
        ],
        "properties": {
          "criterion": {
            "type": "string",
            "description": "renders, no-overflow, no-placeholder (script entries from wireframe-check); intent-fit, web-usability, mobile-usability, accessibility, alternatives (review entries)."
          },
          "status": {
            "type": "string",
            "enum": [
              "pass",
              "warn",
              "fail"
            ]
          },
          "by": {
            "type": "string",
            "description": "`script` for a wireframe-check entry; the reviewer otherwise."
          },
          "note": {
            "type": "string",
            "description": "The reason. Required in substance for every warn and fail."
          }
        }
      },
      "skill.wireframe-viewport-check.output.stagingLinks": {
        "title": "Staging links",
        "description": "The staging preview of the work a request for feedback is about: one deep link per changed page (the page and the anchor where the change sits) with the same page on main as `before`. Mirrors StagingComparison in schemas/sdlc/staging.ts. The rule is skills/authoring/content-lifecycle/feedback-deep-links.md. Copied inline as `definitions.stagingLinks` into every skill contract that carries it; schemas/staging.test.ts fails when a copy drifts.",
        "type": "object",
        "required": [
          "branch",
          "slug",
          "branchUrl",
          "mainBaseUrl",
          "stagingBaseUrl",
          "pages"
        ],
        "properties": {
          "branch": {
            "type": "string",
            "description": "Feature branch name."
          },
          "slug": {
            "type": "string",
            "description": "Branch slug used in the staging URL path."
          },
          "branchUrl": {
            "type": "string",
            "format": "uri"
          },
          "pr": {
            "type": "integer",
            "minimum": 1
          },
          "mainBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "stagingBaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "pages": {
            "type": "array",
            "description": "One entry per changed page, deep-linked; from the change's rendered-impact list, never chosen by judgement.",
            "items": {
              "type": "object",
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "before": {
                  "type": "string",
                  "format": "uri",
                  "description": "Same page on main; absent for a new page."
                },
                "after": {
                  "type": "string",
                  "format": "uri",
                  "description": "The page on the staging preview, with the anchor where the change sits; absent for a deleted page."
                },
                "summary": {
                  "type": "string",
                  "description": "What to look at on this page."
                }
              }
            }
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What could not be linked, said rather than hidden: no preview yet (and when it will exist), no page list computed, or a changed page the publish ref does not hold."
          }
        },
        "$comment": "Copy of cat-harness schemas/staging-comparison.schema.json; cat-harness schemas/staging.test.ts fails when a copy drifts."
      },
      "SkillName": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[a-z][a-z0-9-]*$",
        "description": "A skill name, e.g. todo-manager",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/SkillName"
      },
      "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"
      },
      "SurfaceRef": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[a-z0-9][a-z0-9-]*(\\/[a-z0-9][a-z0-9-]*)*$",
        "description": "A rendered surface: a visualiser route key such as cat-harness/beans, or a kebab-case name such as navbar.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/SurfaceRef"
      },
      "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"
      },
      "Timestamp": {
        "type": "string",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?Z$",
        "description": "An ISO-8601 UTC instant, e.g. 2026-09-20T14:03:11Z",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Timestamp"
      },
      "TimeWindow": {
        "type": "string",
        "pattern": "^(\\d{1,4}[hdw]|\\d{4}-\\d{2}-\\d{2})$",
        "description": "A history window: a count with a unit (4h, 2d, 1w) or an ISO date.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/TimeWindow"
      },
      "TranslationLevel": {
        "type": "string",
        "enum": [
          "block",
          "section",
          "chapter",
          "folio"
        ],
        "description": "What a translation sign-off covers.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/TranslationLevel"
      },
      "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"
      },
      "WireframeUse": {
        "type": "string",
        "enum": [
          "design",
          "as-is"
        ],
        "description": "Why a wireframe is drawn: `design` for a new or changed surface, `as-is` for an existing visualiser.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/WireframeUse"
      },
      "WorkbookPath": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[A-Za-z0-9._][A-Za-z0-9._/-]*$",
        "description": "A repository path to a spreadsheet workbook.",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/WorkbookPath"
      }
    }
  }
}
