Generated from cat-harness/skills/ui/ui-core/docs-generation.md — do not edit here.

✎ Edit this page’s source

Documentation Generation Skill

Role

Coordinate all documentation generation pipelines. This covers the full set of rendered artifacts published to the docs site, from the content-object schemas through to per-paper PDF/HTML viewers.

Documentation artifacts

Artifact	Generator	Output path (docs site)	Trigger
Paper PDF	pipeline/build.ts + PDF engine	papers/<dir>/<dir>.pdf	publish workflow
Paper HTML	generate-html.py (Pandoc + enhance)	papers/<dir>/paper.html	publish workflow
Paper Markdown	Pandoc (gfm)	papers/<dir>/<dir>.md	publish workflow
Paper viewer	generate-index.py	papers/<dir>/index.html	publish workflow
Folio landing	generate-folio-index.py	index.html	publish workflow
Schema docs	TypeDoc (npm run build:docs)	schema-docs/	publish workflow
Schema manifest	cat-harness-tools/scripts/generate-schema-manifest.ts	/api/schema-manifest	MCP server
Formal API docs	doc generator	docs/	formal-layer workflow
Dependency graph	generate_dependency_graph.py	dependency-graph.svg	publish / formal workflow
Proof/object report	extract_proof_objects.py	proof-objects.json	all workflows

Paper document generation

Pipeline: content objects → PDF

content/<paper>/<paper>.ts          paper manifest (metadata, sections)
     ↓
pipeline/build.ts           validates + renders sections → output
     ↓
preamble template + manifest        generate-main.ts → main document
     ↓
PDF engine                          main → PDF
     ↓
pandoc                              → .md → paper-raw.html
     ↓
generate-html.py                    → paper.html (enhanced)
     ↓
generate-index.py                   → per-paper index.html (viewer)

Running locally

# Build sections + generate the main document from the manifest
cd content && bun run pipeline/build.ts \
  <paper>/<paper>.ts \
  --out-dir ../sections/ \
  --generate-main \
  --main-out ../main.tex \
  --preamble ../latex/preamble.tex

# Compile PDF (requires the PDF engine). No engine in the sandbox? Run
# scripts/install-tex.sh first, or fall back to the Docker image.
cd .. && <pdf-engine> main.tex

Key files

File	Purpose
latex/preamble.tex	Shared rendering preamble template (paper-agnostic)
pipeline/build.ts	Content → output section build
pipeline/generate-main.ts	Manifest + preamble → main document
pipeline/render.ts	Block-level markdown → output conversion
.github/scripts/generate-html.py	Pandoc HTML → enhanced paper.html
.github/scripts/generate-index.py	Per-paper viewer (paper/visualizer toggle)
.github/scripts/generate-folio-index.py	Root folio landing page

Schema documentation (TypeDoc)

Pretty-printed HTML reference for the content-object type system.

Configuration

File	Purpose
typedoc.json	TypeDoc config (entry points, output dir, theme)
schemas/types.ts	Core types: Block, Section, Paper
schemas/constraints.ts	Zod runtime validation schemas
schemas/builders.ts	Constructor functions (definition(), theorem(), etc.)
schemas/output-types.ts	CI/output types (objects, glossary, coverage)
schemas/README.md	TypeDoc landing page content
package.json	build:docs script

Running locally

# Install TypeDoc (if not already)
npm install

# Generate schema docs
npm run build:docs
# Output: build/schema-docs/

Schema manifest (lightweight JSON)

For programmatic access (viewer, MCP server):

bun run cat-harness-tools/scripts/generate-schema-manifest.ts
# Output: build/schema-manifest.json

Formal-layer documentation

When a paper carries a formal layer (e.g. a proof assistant), its API documentation is generated by the formal-layer CI workflow after the formal build succeeds. If the primary doc generator fails, the workflow falls back to a static HTML source browser.

A gap/axiom report lists unproved-gap declarations and dependency transparency; it is produced by the same workflow.

Folio landing page

The root index.html on the docs site is a folio page listing all papers with viewer links. Generated from content/folio.ts.

This is the paper pipeline’s own page. In a checkout that instantiates several harnesses, which instance owns <base>/index.html is site.landing in the root index.config.json — an instance name, or "hub". That is index-config’s rule. For where every other page is published, canonical and alias, see schema-management §”Where a viewer publishes”.

Adding a new paper to the folio

1. Create content/<paper-dir>/<paper-dir>.ts (paper manifest with title, authors, abstract, macros, sections)
2. Create section directories with content objects
3. Add paperRef({ dir: "<paper-dir>", title: "...", ... }) to content/folio.ts
4. The pipeline discovers it automatically via extract-folio.py

Key scripts

Script	Purpose
.github/scripts/extract-folio.py	Parse folio.ts → JSON paper list
.github/scripts/generate-folio-index.py	Generate root index.html

Dependency graph

Visual SVG showing dependencies between content blocks.

python3 .github/scripts/generate_dependency_graph.py \
  --manifest proof-objects.json \
  --output dependency-graph.svg

Unified Docker image

All CI/CD workflows use the same paper-assistant Docker image (adapters/mcp-server/Dockerfile), which is also the folio MCP server. This eliminates per-workflow tool installation and ensures consistent build environments. The image bundles the PDF engine, the content pipeline runtime (Bun), pandoc, graph tooling, and CI scripts.

Using locally (Docker fallback)

When the PDF engine isn’t installed locally, the render hooks automatically fall back to the Docker image. The scripts/lib/docker-tex.sh helper automates this fallback for the render hooks.

CI workflows

Workflow	Container	Docs generated
publish.yml	paper-assistant	Paper PDF/HTML/MD, folio index, schema docs, dep graph
formal-layer workflow	paper-assistant	Formal API docs, gap report, manifests

When to use this skill

• “generate docs” / “build docs” / “rebuild documentation”
• “schema docs” / “type docs” / “TypeDoc”
• “build paper” / “compile PDF” / “render HTML”
• “update folio page” / “add paper to landing page”
• “dependency graph” / “gap report”