Reference lists to reference nodes
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.
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.
l1-document-ingestion
The detailed method for turning a DOCUMENT in uploads/ into a complete L1 entry in library/<bib-slug>/ — which rung reads it and why, what a complete L1 entry holds, why an inferred structure is refused rather than guessed, and the archive, dataset, narrative, image and vector-label arms. Refines the harness’s basic library-ingestion flow; one entry point: bun run cat ingest.
Source: folio-assistant-core/skills/library/ingestion/l1-document-ingestion.md.
The skill declares no I/O contract (schemas/skills/l1-document-ingestion/{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 | instance | RepoPath | yes | The instance root whose library sections are read and whose references directory is written. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | entry | RepoPath | One library entry’s slug, to extract only its lists. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | check | Flag | Fail if a node is stale, instead of writing. | boolean · A boolean switch — projects to a bare flag, with no value word | |
| out | references | RepoPath | The extracted reference nodes: <references dir>/<doc-id>.<section>.<n>.json. | 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 |
|---|---|---|---|
| L1 document ingestion — a document to the L1 source knowledge graph | L1 completeness gate | Ingestion Engine (agent, runs unattended) | l1-document-ingestion |
| L1 document ingestion — a document to the L1 source knowledge graph | Summarise prose blocks, in every language | Ingestion Engine (agent, runs unattended) | l1-document-ingestion |
| L1 document ingestion — a document to the L1 source knowledge graph | Record errata in the source’s own text | Ingestion Engine (agent, runs unattended) | l1-document-ingestion |
| Ingestion subprocess — build the L1 knowledge graph | Extract reference lists | Ingestion Engine (agent, runs unattended) | l1-document-ingestion |
| Ingestion subprocess — derive content from the assets | Footnotes and the marks that call them | Ingestion Engine (agent, runs unattended) | l1-document-ingestion |
| Ingestion subprocess — extract structure | Check each page; OCR pages that fail | Ingestion Engine (agent, runs unattended) | l1-document-ingestion |
| DTH authoring | Extract L1 from WHO publications | Librarian | l1-document-ingestion |
How it is deployed and reached
- Command line. From the repository root:
bun run cat references:extract.cat references:extractrunsbun run folio-assistant-core/scripts/references-extract.ts(declared infolio-assistant-core/package.json). - 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.
| install | none |
| runtime | bun |
| network | no |
| when to choose it | |
|---|---|
| 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. |
What it is made of
| role | file | |
|---|---|---|
| definition | folio-assistant-core/tools/references-extract/references-extract.ts | |
| script | folio-assistant-core/scripts/references-extract.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/references-extract.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/references-extract.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": "references-extract",
"title": "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.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run cat references:extract"
},
"io": {
"inputs": [
{
"name": "instance",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The instance root whose library sections are read and whose references directory is written.",
"required": true,
"arg": {
"flag": "--instance"
}
},
{
"name": "entry",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "One library entry's slug, to extract only its lists.",
"required": false,
"arg": {
"flag": "--entry"
}
},
{
"name": "check",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
"description": "Fail if a node is stale, instead of writing.",
"required": false,
"arg": {
"flag": "--check"
}
}
],
"outputs": [
{
"name": "references",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The extracted reference nodes: `<references dir>/<doc-id>.<section>.<n>.json`."
}
]
},
"satisfies": [
"l1-document-ingestion"
],
"requirements": {
"runtime": [
"bun"
],
"network": false
},
"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."
}
}