Publish a Lean render under a folio site, with the harness rail

Stage a doc-gen4 render under a folio’s built site (<site>/<route>/, default lean/) and give every page the harness navbar and rail by running cat-harness/scripts/rail-standalone-pages.ts --foreign-site over the site — the same rail stage-folio-local.ts applies to the folio’s own pages. Leaves out Lake’s .hash/.trace bookkeeping, marks doc-gen4’s iframe navbar and find/ redirect folio-navbar: none so no rail is drawn inside the sidebar, adds a layout shim so the rail does not cover doc-gen4’s fixed sidebar, and with --modules prunes to the folio’s own modules, repointing links into dropped ones to the community docs. Then asserts every staged page is railed or declined.

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.

lean-html-docs

Build and publish the visualiser of a folio’s declared lean directory: the package’s doc-gen4 HTML render, staged under the folio’s site and wrapped in the harness navbar and rail. Use when a folio’s Lean docs are missing, stale, or published without the harness chrome, or when declaring a lean directory and its coverage.visualiser.

Source: folio-assistant-sci/skills/lean/lean-html-docs.md.

Also satisfied by: lean-html-docs, lean-kg-publish.

The skill declares no I/O contract (schemas/skills/lean-html-docs/{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
indocsRepoPathyesThe doc-gen4 render, lean-html-docs’s output.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
insiteRepoPathyesThe folio’s built site (_site from build-folio-site.ts).string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inrouteSlugWhere under the site. Default lean.string · pattern ^[a-z0-9][a-z0-9-]*$ · A folio slug, e.g. quantum-observable-universe
inmodulePackageNameA Lake package whose module root to keep (qou keeps QOU/, matched case-insensitively). Repeat for several. Default: keep everything.string · pattern ^[a-z][a-z0-9-]*$ · A skill package, e.g. folio-core
inexternalBaseUrlWhere links into pruned modules go. Default the community mathlib4 docs.string · format uri · An absolute http(s) URL
inhomeLabelInstanceIdThe rail’s home row: the folio’s instance name, e.g. qou.string · pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$ · A workflow instance id — the stem of a file in the bean graph’s workflow-state node
ininstanceInstanceIdRail as this instance’s own site (its name, mark and graphs), as rail-standalone-pages.ts –instance.string · pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$ · A workflow instance id — the stem of a file in the bean graph’s workflow-state node
inplatformRepoPathThe index checkout holding the rail pass. Default $FOLIO_ASSISTANT_ROOT, then the nearest ancestor that has it.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
innoRailFlagStage only; the caller rails the site itself.boolean · A boolean switch — projects to a bare flag, with no value word
outpagesRepoPath<site>/<route>/, railed, plus the rail’s shared data under <site>/assets/navbar/.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.

Processes and tasks

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

processsteplanevia skill
Publish a folio’s Lean render with the harness chromeBuild the doc-gen4 render over the warm cacheLean toolchainlean-html-docs
Publish a folio’s Lean render with the harness chromeStage the render under the site and rail every pageCI/CD Pipelinelean-html-docs

How it is deployed and reached

  • Command line. From the repository root: bun run folio-assistant-sci/adapters/paper/lean/lean-render.ts.
  • GitHub Actions. No workflow in this checkout runs its command.

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun
networkno
when to choose it
whenAfter the folio’s site is built and before it is checked and published (stage-folio-local.ts step 2 runs the same rail): put the Lean render into it as the lean directory’s visualiser.
limitsPruned links point at the community docs, built from THEIR Mathlib rather than the folio’s pin; doc-gen4’s search index still lists pruned declarations, whose hits 404. The rail’s assets load from the platform’s published site, as on every foreign-site page.
costMeasured on qou’s July render: pruned to QOU,UGB,Fred2005 34 pages / 29 MB / about 5 s; unpruned 4,193 pages / 533 MB / 347 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/folio-assistant-sci/tools/lean-render-publish.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/folio-assistant-sci/folio-assistant-sci.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/folio-assistant-sci/tools/lean-render-publish.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/folio-assistant-sci/folio-assistant-sci.jsonld",
  "name": "lean-render-publish",
  "title": "Publish a Lean render under a folio site, with the harness rail",
  "description": "Stage a doc-gen4 render under a folio's built site (`<site>/<route>/`, default `lean/`) and give every page the harness navbar and rail by running `cat-harness/scripts/rail-standalone-pages.ts --foreign-site` over the site — the same rail `stage-folio-local.ts` applies to the folio's own pages. Leaves out Lake's `.hash`/`.trace` bookkeeping, marks doc-gen4's iframe navbar and `find/` redirect `folio-navbar: none` so no rail is drawn inside the sidebar, adds a layout shim so the rail does not cover doc-gen4's fixed sidebar, and with `--modules` prunes to the folio's own modules, repointing links into dropped ones to the community docs. Then asserts every staged page is railed or declined.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run folio-assistant-sci/adapters/paper/lean/lean-render.ts"
  },
  "io": {
    "inputs": [
      {
        "name": "docs",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The doc-gen4 render, `lean-html-docs`'s output.",
        "required": true,
        "arg": {
          "flag": "--docs"
        }
      },
      {
        "name": "site",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The folio's built site (`_site` from build-folio-site.ts).",
        "required": true,
        "arg": {
          "flag": "--site"
        }
      },
      {
        "name": "route",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Slug",
        "description": "Where under the site. Default `lean`.",
        "required": false,
        "arg": {
          "flag": "--route"
        }
      },
      {
        "name": "module",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/PackageName",
        "description": "A Lake package whose module root to keep (`qou` keeps `QOU/`, matched case-insensitively). Repeat for several. Default: keep everything.",
        "required": false,
        "arg": {
          "flag": "--module"
        }
      },
      {
        "name": "externalBase",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Url",
        "description": "Where links into pruned modules go. Default the community mathlib4 docs.",
        "required": false,
        "arg": {
          "flag": "--external-base"
        }
      },
      {
        "name": "homeLabel",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/InstanceId",
        "description": "The rail's home row: the folio's instance name, e.g. `qou`.",
        "required": false,
        "arg": {
          "flag": "--home-label"
        }
      },
      {
        "name": "instance",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/InstanceId",
        "description": "Rail as this instance's own site (its name, mark and graphs), as rail-standalone-pages.ts --instance.",
        "required": false,
        "arg": {
          "flag": "--instance"
        }
      },
      {
        "name": "platform",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The index checkout holding the rail pass. Default `$FOLIO_ASSISTANT_ROOT`, then the nearest ancestor that has it.",
        "required": false,
        "arg": {
          "flag": "--platform"
        }
      },
      {
        "name": "noRail",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Stage only; the caller rails the site itself.",
        "required": false,
        "arg": {
          "flag": "--no-rail"
        }
      }
    ],
    "outputs": [
      {
        "name": "pages",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "`<site>/<route>/`, railed, plus the rail's shared data under `<site>/assets/navbar/`."
      }
    ]
  },
  "satisfies": [
    "lean-html-docs"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "After the folio's site is built and before it is checked and published (`stage-folio-local.ts` step 2 runs the same rail): put the Lean render into it as the `lean` directory's visualiser.",
    "limits": "Pruned links point at the community docs, built from THEIR Mathlib rather than the folio's pin; doc-gen4's search index still lists pruned declarations, whose hits 404. The rail's assets load from the platform's published site, as on every foreign-site page.",
    "cost": "Measured on qou's July render: pruned to QOU,UGB,Fred2005 34 pages / 29 MB / about 5 s; unpruned 4,193 pages / 533 MB / 347 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