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.

porttyperequireddescriptionconstraint
inpaperSlugThe 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
inchapterSlugRestrict the analysis to one chapter directory.string · pattern ^[a-z0-9][a-z0-9-]*$ · A folio slug, e.g. quantum-observable-universe
injsonFlagEmit the whole graph as JSON on stdout and exit.boolean · A boolean switch — projects to a bare flag, with no value word
inmdFlagWrite the report to /tmp/content-graph-report.md.boolean · A boolean switch — projects to a bare flag, with no value word
invisualiseFlagRender the Graphviz SVGs (needs graphviz).boolean · A boolean switch — projects to a bare flag, with no value word
inproposalsFlagWrite concrete reorganisation proposals to /tmp/content-graph-proposals.md.boolean · A boolean switch — projects to a bare flag, with no value word
outreportTextThe 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:

processsteplanevia skill
Make the content changeAssess downstream impactFolio-Assistant Agentcontent-graph

How it is deployed and reached

  • Command line. From the repository root: bun run cat content:graph-analysis. cat content:graph-analysis runs python3 cat-harness-tools/pipeline/content-graph-analysis.py (declared in cat-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.

installnone
runtimepython3
networkno

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/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
  }
}

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