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.

porttyperequireddescriptionconstraint
inworkRepoPathyesScratch 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.
inbaseurlRepoPathyesThe 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.
inplantuml-jarRepoPathRender 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.
inremote-themeTextowner/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.
inchanged-filesRepoPathBuild 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.
incompose-intoRepoPathMove 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.
incompose-at-rootFlagWith --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
inonlySlugBuild one IG instance.string · pattern ^[a-z0-9][a-z0-9-]*$ · A folio slug, e.g. quantum-observable-universe
insourceRepoPathWith --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.
infull-pagesFlagDefault: 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
outsitesCountIGs 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:

Steps this Tool can carry out, because each names a skill it satisfies:

processsteplanevia skill
Publishing the docs site, and keeping the previews aliveCompose each layer’s site [its Tool]CI/CD Pipelinedocs-generation
An IG site, built from the AST on its cache branchRestore and judge the cached ASTSite build (agent, stage-local)ig-build-pipeline
An IG site, built from the AST on its cache branchBuild and publish the site from the ASTSite build (agent, stage-local)ig-build-pipeline
An IG site, built from the AST on its cache branchDispatch AST refreshPublication 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-docsBuild each IG’s artefact indexHost docs site build (CI runner)ig-build-pipeline
Each IG, composed into a host docs site and rendered with just-the-docsGenerate each IG instance’s artefact pagesHost docs site build (CI runner)ig-build-pipeline
Each IG, composed into a host docs site and rendered with just-the-docsClone each IG at its recorded commit and stage itHost 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:
workflowline
.github/workflows/docs-site.yml559bun run fhir-harness/scripts/stage-ig-sites.ts --work ./_ig --baseurl "/${REPO_NAME}" \\
.github/workflows/feature-staging.yml1092bun 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.

installnone
runtimebun, git
networkyes

When a host it reaches is refused:

host / errorremedy
github.comnone: It clones each IG’s source repository from GitHub; no declared Tool stages an IG without it.
when to choose it
whenBuilding the docs site or a staging preview: every IG with a recorded source is staged, and with --compose-into composed into the host site.
limitsNeeds 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).
costSeconds per IG plus the clone; the Jekyll build is the caller’s.

What it is made of

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."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev