Editorial content-graph analysis
Build the block- and section-level editorial dependency graph of one paper from its .ts manifests and report forward references, cross-chapter coupling, sparse or dense sections and isolated blocks, ranked. Reads uses[]/interprets only — the editorial relation, never the formal one.
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.
content-graph
Editorial graph analysis skill — builds a content graph from uses[], interprets, proofs, and examples relationships; builds a chapter/section topology graph; and applies heuristics to identify forward references, cross-section/cross-chapter coupling, and sections that are too sparse or too dense. Produces actionable reorganisation suggestions and can implement approved moves.
Source: cat-harness/skills/authoring/authoring-core/content-graph.md.
Also satisfied by: content-graph-uml.
The skill declares no I/O contract (schemas/skills/content-graph/{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 | paper | Slug | The paper: a directory name under the folio directory, or a path to it. When omitted, the folio’s only paper; required when the folio holds several. | string · pattern ^[a-z0-9][a-z0-9-]*$ · A folio slug, e.g. quantum-observable-universe | |
| in | chapter | Slug | Restrict the analysis to one chapter directory. | string · pattern ^[a-z0-9][a-z0-9-]*$ · A folio slug, e.g. quantum-observable-universe | |
| in | json | Flag | Emit the whole graph as JSON on stdout and exit. | boolean · A boolean switch — projects to a bare flag, with no value word | |
| in | md | Flag | Write the report to /tmp/content-graph-report.md. | boolean · A boolean switch — projects to a bare flag, with no value word | |
| in | visualise | Flag | Render the Graphviz SVGs (needs graphviz). | boolean · A boolean switch — projects to a bare flag, with no value word | |
| in | proposals | Flag | Write concrete reorganisation proposals to /tmp/content-graph-proposals.md. | boolean · A boolean switch — projects to a bare flag, with no value word | |
| out | report | Text | The ranked findings, or the graph as JSON with --json. | string · A short single-line human string. Not admissible as a command-line argument. |
Processes and tasks
Steps this Tool can carry out, because each names a skill it satisfies:
| process | step | lane | via skill |
|---|---|---|---|
| Make the content change | Assess downstream impact | Folio-Assistant Agent | content-graph |
How it is deployed and reached
- Command line. From the repository root:
bun run cat content:graph-analysis.cat content:graph-analysisrunspython3 cat-harness-tools/pipeline/content-graph-analysis.py(declared incat-harness-tools/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 | python3 |
| network | no |
What it is made of
| role | file | |
|---|---|---|
| definition | cat-harness/tools/content-graph-analysis/content-graph-analysis.json | |
| script | cat-harness-tools/pipeline/content-graph-analysis.py |
Linked data
The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/cat-harness/tools/content-graph-analysis.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/cat-harness/cat-harness.context.jsonld",
"@id": "https://litlfred.github.io/folio-assistant/cat-harness/tools/content-graph-analysis.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/cat-harness/cat-harness.jsonld",
"name": "content-graph-analysis",
"title": "Editorial content-graph analysis",
"description": "Build the block- and section-level editorial dependency graph of one paper from its `.ts` manifests and report forward references, cross-chapter coupling, sparse or dense sections and isolated blocks, ranked. Reads `uses[]`/`interprets` only — the editorial relation, never the formal one.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run cat content:graph-analysis"
},
"io": {
"inputs": [
{
"name": "paper",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Slug",
"description": "The paper: a directory name under the folio directory, or a path to it. When omitted, the folio's only paper; required when the folio holds several.",
"required": false,
"arg": {
"flag": "--paper"
}
},
{
"name": "chapter",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Slug",
"description": "Restrict the analysis to one chapter directory.",
"required": false,
"arg": {
"flag": "--chapter"
}
},
{
"name": "json",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
"description": "Emit the whole graph as JSON on stdout and exit.",
"required": false,
"arg": {
"flag": "--json"
}
},
{
"name": "md",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
"description": "Write the report to /tmp/content-graph-report.md.",
"required": false,
"arg": {
"flag": "--md"
}
},
{
"name": "visualise",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
"description": "Render the Graphviz SVGs (needs graphviz).",
"required": false,
"arg": {
"flag": "--visualise"
}
},
{
"name": "proposals",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
"description": "Write concrete reorganisation proposals to /tmp/content-graph-proposals.md.",
"required": false,
"arg": {
"flag": "--proposals"
}
}
],
"outputs": [
{
"name": "report",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
"description": "The ranked findings, or the graph as JSON with `--json`."
}
]
},
"satisfies": [
"content-graph"
],
"requirements": {
"runtime": [
"python3"
],
"network": false
}
}