Folio ChangeSet
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.
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.
diff
Show per-block content changes with viewer links, changelog, and undo impact analysis
Source: folio-assistant-core/skills/content/content-lifecycle-ext/diff.md.
The skill declares no I/O contract (schemas/skills/diff/{input,output}.schema.json).
staging-review
Staging preview and before/after comparison for content review. Takes one optional string — what the reader wants to look at, in their own words — and returns a list of URLs, each looked up in the publish ref, with what is published at it and what to review there. Provides before (MAIN) and after (branches/) pairs so reviewers can compare rather than guess. Used by the CRDM feature development workflow, content authoring review sessions, and whenever a staging preview deploys or someone asks to see it.
Source: cat-harness/skills/ui/ui-core/staging-review.md.
Also satisfied by: paper-preview.
input — cat-harness/schemas/skills/staging-review/input.schema.json, https://litlfred.github.io/folio-assistant/cat-harness/skills/staging-review/input.schema.json
| field | type | required | description |
|---|---|---|---|
ask | string | What the reader wants to look at, verbatim. Absent: the whole preview, every page the branch changed. | |
branch | string | ||
pr | integer |
output — cat-harness/schemas/skills/staging-review/output.schema.json, https://litlfred.github.io/folio-assistant/cat-harness/skills/staging-review/output.schema.json
| field | type | required | description |
|---|---|---|---|
narrative | string | yes | What a reader of the site will now see or do differently, and why, before any link. |
startHere | string | The one page to open first. | |
stagingLinks | stagingLinks | yes |
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 | folio | RepoPath | yes | The folio’s folio graph directory, relative to the repository — what <slug>.json declares for it, usually folio/. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | base | Branch | The ref compared against. Default origin/main. An unresolvable base is an ERROR, never an empty ChangeSet. | string · pattern ^[A-Za-z0-9][A-Za-z0-9._/-]*$ · A git branch name | |
| in | head | Branch | The ref under review, or worktree (the default) for the files on disk, uncommitted edits included. | string · pattern ^[A-Za-z0-9][A-Za-z0-9._/-]*$ · A git branch name | |
| in | out | RepoPath | Where to write the JSON. Absent: stdout. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | text-out | RepoPath | 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. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| out | changeset | RepoPath | A folio-changeset/v1 document. Its one-line summary goes to stderr. | 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:
| process | step | lane | via skill |
|---|---|---|---|
| Review task | Classify what changed | Reviewer / SME | staging-review |
| CRDM Phase 6 — implement, MVP, acceptance | Post summary to issue | Agent | staging-review |
| CRDM Phase 6 — implement, MVP, acceptance | Share MVP with stakeholders | BA / Feature Requestor | staging-review |
| Code change and review | Commit, push, open the PR | Authoring agent | staging-review |
| Code change and review | Review the change | Code reviewer | staging-review |
| Staging a feature branch preview, and taking it down | Comment the preview URL on the PR | CI/CD Pipeline | staging-review |
| Staging a feature branch preview, and taking it down | Post the retention notice on the PR | CI/CD Pipeline | staging-review |
| Adopting an upstream version bump | Review the MVP against what we bind to | Reviewer / SME | staging-review |
| Questionnaire wireframe review | Ask for review with deep links | FHIR modeller | staging-review |
| Committee review of a content change | Compare main vs staging | Review Committee | staging-review |
| Committee review of a content change | Slice the change and assign reviewers | Review Coordinator | staging-review |
| Content Change and Review | Review staged rendering | Content Author | staging-review |
| Content Change and Review | Request further revisions | Content Author | staging-review |
| Content Change and Review | Submit to review committee | Content Author | staging-review |
| Draft, review and publish | Circulate the draft | Publication manager | staging-review |
| Draft, review and publish | Review the draft publication | Review team (content · QC · technical officer) | staging-review |
| Draft, review and publish | Clinical or scientific sign-off | Clinical / scientific SMEs | staging-review |
| Make a decided public comment change | Review the change set on its staging preview | Change set — feature branch and staging | staging-review |
| Review and publish a folio | Review and record feedback | Reviewer | staging-review |
| SMART Guideline end to end | Review each L2 asset (before / after if adapted) | Human adjudicators | staging-review |
| SMART Guideline end to end | Review each L3 asset (before / after if adapted) | Human adjudicators | staging-review |
| SMART Guideline end to end | Adjudicate the L4 wireframes and application | Human adjudicators | staging-review |
| Classify and code content | Stage codings, warnings and exclusions for review | Authoring agent | staging-review |
| L2 component edit and review | Ask for review with staging deep links | Authoring agent | staging-review |
How it is deployed and reached
- Command line. From the repository root:
bun run folio-assistant-core/schemas/changeset.ts. - GitHub Actions. 2 workflow line(s) run its command:
| workflow | line | |
|---|---|---|
.github/workflows/folio-staging.yml | 197 | if [ -f "$PLATFORM_DIR/folio-assistant-core/schemas/changeset.ts" ]; then |
.github/workflows/folio-staging.yml | 398 | bun run "$PLATFORM_DIR/folio-assistant-core/schemas/changeset.ts" \\ |
As an API: its operation in the OpenAPI document and the MCP tool list of its layer.
| install | none |
| runtime | bun, git, tar |
| network | no |
| when to choose it | |
|---|---|
| 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. |
What it is made of
| role | file | |
|---|---|---|
| definition | folio-assistant-core/tools/folio-changeset/folio-changeset.ts | |
| script | folio-assistant-core/schemas/changeset.ts |
Linked data
The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-changeset.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-core/folio-assistant-core.context.jsonld",
"@id": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-changeset.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.jsonld",
"name": "folio-changeset",
"title": "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.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run folio-assistant-core/schemas/changeset.ts"
},
"io": {
"inputs": [
{
"name": "folio",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The folio's `folio` graph directory, relative to the repository — what `<slug>.json` declares for it, usually `folio/`.",
"required": true,
"arg": {
"flag": "--folio"
}
},
{
"name": "base",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Branch",
"description": "The ref compared against. Default `origin/main`. An unresolvable base is an ERROR, never an empty ChangeSet.",
"required": false,
"arg": {
"flag": "--base"
}
},
{
"name": "head",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Branch",
"description": "The ref under review, or `worktree` (the default) for the files on disk, uncommitted edits included.",
"required": false,
"arg": {
"flag": "--head"
}
},
{
"name": "out",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Where to write the JSON. Absent: stdout.",
"required": false,
"arg": {
"flag": "--out"
}
},
{
"name": "text-out",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/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": false,
"arg": {
"flag": "--text-out"
}
}
],
"outputs": [
{
"name": "changeset",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "A `folio-changeset/v1` document. Its one-line summary goes to stderr."
}
]
},
"satisfies": [
"diff",
"staging-review"
],
"requirements": {
"runtime": [
"bun",
"git",
"tar"
],
"network": false
},
"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."
}
}