Stage every IG whose instance records its source, one Jekyll site each
Clone each IG whose instance records a sushi-config source in fhir-artifact-index/menu.json, at the recorded commit, and stage it with build-ig-site (theme, artefact pages, post-processing fills, edit links to the IG’s default branch). Served at /<instance>/ when its docs declare igSite (its artefact pages copied in; a collision is refused), else /<instance>/ig/. Prints one <instance> <jekyll source> <at> line per IG for the caller’s jekyll build.
Skills it satisfies
A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.
ig-build-pipeline
The bare FHIR IG pipeline — FSH to SUSHI to the IG Publisher to a pages branch, with no pre-processing and no post-processing. What this layer runs, what it emits, and the list of things it deliberately refuses to know about. Owns the AST cache lifecycle: an IG site is built from the AST on its cache branch, the publish refuses a stale one, and the reusable ig-ast-refresh.yml is the one writer. Owns what an IG reader may read: contentTypes.ig.include in the repository’s index.config.json, and the legacy warning for a repository that declares none. Read before adding anything to fhir-harness, before onboarding, converting or changing the workflows of an IG repository, and before publishing an IG site.
Source: fhir-harness/skills/fhir-ig-base/ig-build-pipeline.md.
Also satisfied by: build-ig-site, fhir-core, ig-artifact-jsonld, ig-ast-refresh, ig-index-build, ig-page-render-qa, ig-pages, ig-publisher-i18n, ig-repo-site, ig-site-data, ingest-ig-menu, jsonld-vocabularies, logical-model-schemas, strip-library-binaries, strip-library-content, terminology-index, valueset-schemas.
The skill declares no I/O contract (schemas/skills/ig-build-pipeline/{input,output}.schema.json).
docs-generation
How a checkout of this harness generates and publishes its docs site: regenerating derived references, composing the docs layers and each layer’s site into one Jekyll source, building it with just-the-docs, the post-build passes, the TypeDoc API reference, the knowledge-graph export, and the full-replace publish to gh-pages and its branches/ previews.
Source: cat-harness/skills/ui/ui-core/docs-generation.md.
Also satisfied by: bpmn-checklist, bpmn-render, ci-post-merge-regen, pages-index, pages-publish, readme-audit, readme-sync, render-order, schema-docs, shared-assets, site-build-local, site-search-index, site-search-scopes, skill-docs, subgraph-readmes, upload-step-docs, proof-dependency-graph.
The skill declares no I/O contract (schemas/skills/docs-generation/{input,output}.schema.json).
Inputs and outputs
Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | work | RepoPath | yes | Scratch directory: each IG’s clone and its Jekyll source. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | baseurl | RepoPath | yes | The site’s base URL; each IG is served under it at /<instance>/ or /<instance>/ig/. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | plantuml-jar | RepoPath | Render input/images-source/*.plantuml as the Publisher does. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | remote-theme | Text | owner/repo@ref for Jekyll’s remote-theme plugin, instead of the just-the-docs gem. | string · A short single-line human string. Not admissible as a command-line argument. | |
| in | changed-files | RepoPath | Build only the IGs a changed file reaches (the staging cone). | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | compose-into | RepoPath | Move each staged IG into this host Jekyll source at <instance>/, so the host’s build renders it: in the thin layout with the host’s rail linked (the default), or with the host’s full chrome (sidebar, search, language selector) under --full-pages. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | compose-at-root | Flag | With --compose-into and --only: the IG IS the site — compose it at the host’s ROOT, based at --baseurl itself. An IG repository’s own site uses this with a compose-docs --shell host, so it wears the main site’s chrome. | boolean · A boolean switch — projects to a bare flag, with no value word | |
| in | only | Slug | Build one IG instance. | string · pattern ^[a-z0-9][a-z0-9-]*$ · A folio slug, e.g. quantum-observable-universe | |
| in | source | RepoPath | With --only: a local checkout of the IG’s source to build from instead of cloning the recorded commit — an IG repository building its own site in CI. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | full-pages | Flag | Default: artifacts.html and toc.html are thin pages over the artefact index node, and composed pages link the host’s chrome. With it: full pages; needs gen-ig-pages --full-pages too (a mismatch is refused). | boolean · A boolean switch — projects to a bare flag, with no value word | |
| out | sites | Count | IGs staged, one stdout line each; an instance with no recorded source is skipped and reported, never silently. | integer · A non-negative count — how many of something, or how many to show. Zero is a real answer. |
Processes and tasks
Its own procedure is drawn as:
- Each IG, composed into a host docs site and rendered with just-the-docs (
ig-docs-site-compose)
Steps this Tool can carry out, because each names a skill it satisfies:
| process | step | lane | via skill |
|---|---|---|---|
| Publishing the docs site, and keeping the previews alive | Compose each layer’s site [its Tool] | CI/CD Pipeline | docs-generation |
| An IG site, built from the AST on its cache branch | Restore and judge the cached AST | Site build (agent, stage-local) | ig-build-pipeline |
| An IG site, built from the AST on its cache branch | Build and publish the site from the AST | Site build (agent, stage-local) | ig-build-pipeline |
| An IG site, built from the AST on its cache branch | Dispatch AST refresh | Publication manager (owner, or the agent the owner delegates to) | ig-build-pipeline |
| Each IG, composed into a host docs site and rendered with just-the-docs | Build each IG’s artefact index | Host docs site build (CI runner) | ig-build-pipeline |
| Each IG, composed into a host docs site and rendered with just-the-docs | Generate each IG instance’s artefact pages | Host docs site build (CI runner) | ig-build-pipeline |
| Each IG, composed into a host docs site and rendered with just-the-docs | Clone each IG at its recorded commit and stage it | Host docs site build (CI runner) | ig-build-pipeline |
How it is deployed and reached
- Command line. From the repository root:
bun run fhir-harness/scripts/stage-ig-sites.ts. - GitHub Actions. 2 workflow line(s) run its command:
| workflow | line | |
|---|---|---|
.github/workflows/docs-site.yml | 559 | bun run fhir-harness/scripts/stage-ig-sites.ts --work ./_ig --baseurl "/${REPO_NAME}" \\ |
.github/workflows/feature-staging.yml | 1092 | bun run fhir-harness/scripts/stage-ig-sites.ts --work ./_ig --baseurl "$BASE" \\ |
As an API: its operation in the OpenAPI document and the MCP tool list of its layer.
| install | none |
| runtime | bun, git |
| network | yes |
When a host it reaches is refused:
| host / error | remedy |
|---|---|
github.com | none: It clones each IG’s source repository from GitHub; no declared Tool stages an IG without it. |
| when to choose it | |
|---|---|
| when | Building the docs site or a staging preview: every IG with a recorded source is staged, and with --compose-into composed into the host site. |
| limits | Needs network to clone each IG at its pinned commit, and to ask its default branch for edit links (absent, pages carry none and the run says so). |
| cost | Seconds per IG plus the clone; the Jekyll build is the caller’s. |
What it is made of
| role | file | |
|---|---|---|
| definition | fhir-harness/tools/stage-ig-sites/stage-ig-sites.ts | |
| script | fhir-harness/scripts/stage-ig-sites.ts | |
| subprocess diagram | fhir-harness/processes/tools/ig-docs-site-compose.bpmn |
Linked data
The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/fhir-harness/tools/stage-ig-sites.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.
{
"@context": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.context.jsonld",
"@id": "https://litlfred.github.io/folio-assistant/fhir-harness/tools/stage-ig-sites.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
"name": "stage-ig-sites",
"title": "Stage every IG whose instance records its source, one Jekyll site each",
"description": "Clone each IG whose instance records a sushi-config source in `fhir-artifact-index/menu.json`, at the recorded commit, and stage it with `build-ig-site` (theme, artefact pages, post-processing fills, edit links to the IG's default branch). Served at `/<instance>/` when its docs declare `igSite` (its artefact pages copied in; a collision is refused), else `/<instance>/ig/`. Prints one `<instance> <jekyll source> <at>` line per IG for the caller's `jekyll build`.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run fhir-harness/scripts/stage-ig-sites.ts"
},
"io": {
"inputs": [
{
"name": "work",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Scratch directory: each IG's clone and its Jekyll source.",
"required": true
},
{
"name": "baseurl",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The site's base URL; each IG is served under it at `/<instance>/` or `/<instance>/ig/`.",
"required": true
},
{
"name": "plantuml-jar",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Render `input/images-source/*.plantuml` as the Publisher does.",
"required": false
},
{
"name": "remote-theme",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
"description": "`owner/repo@ref` for Jekyll's remote-theme plugin, instead of the `just-the-docs` gem.",
"required": false
},
{
"name": "changed-files",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Build only the IGs a changed file reaches (the staging cone).",
"required": false
},
{
"name": "compose-into",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Move each staged IG into this host Jekyll source at `<instance>/`, so the host's build renders it: in the thin layout with the host's rail linked (the default), or with the host's full chrome (sidebar, search, language selector) under `--full-pages`.",
"required": false
},
{
"name": "compose-at-root",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
"description": "With `--compose-into` and `--only`: the IG IS the site — compose it at the host's ROOT, based at `--baseurl` itself. An IG repository's own site uses this with a `compose-docs --shell` host, so it wears the main site's chrome.",
"required": false,
"arg": {
"flag": "--compose-at-root"
}
},
{
"name": "only",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Slug",
"description": "Build one IG instance.",
"required": false
},
{
"name": "source",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "With `--only`: a local checkout of the IG's source to build from instead of cloning the recorded commit — an IG repository building its own site in CI.",
"required": false
},
{
"name": "full-pages",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
"description": "Default: `artifacts.html` and `toc.html` are thin pages over the artefact index node, and composed pages link the host's chrome. With it: full pages; needs `gen-ig-pages --full-pages` too (a mismatch is refused).",
"required": false,
"arg": {
"flag": "--full-pages"
}
}
],
"outputs": [
{
"name": "sites",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
"description": "IGs staged, one stdout line each; an instance with no recorded source is skipped and reported, never silently."
}
]
},
"satisfies": [
"ig-build-pipeline",
"docs-generation"
],
"requirements": {
"runtime": [
"bun",
"git"
],
"network": true
},
"remedies": [
{
"host": "github.com",
"none": "It clones each IG's source repository from GitHub; no declared Tool stages an IG without it."
}
],
"subprocesses": [
"ig-docs-site-compose"
],
"selection": {
"when": "Building the docs site or a staging preview: every IG with a recorded source is staged, and with `--compose-into` composed into the host site.",
"limits": "Needs network to clone each IG at its pinned commit, and to ask its default branch for edit links (absent, pages carry none and the run says so).",
"cost": "Seconds per IG plus the clone; the Jekyll build is the caller's."
}
}