Build a catalog

Validate authored guideline folders, write catalog bundles, and export catalog tables.

catalog build turns an authored guideline folder into a bundle that the site, CLI, Python, JavaScript, and MCP readers can load.

Folder scheme

An authored catalog folder contains a manifest and guideline entry folders:

catalog-source/
├── MANIFEST.md
└── entries/
    └── direct-labels/
        ├── guideline.md
        └── references.bib

The manifest defines section roles and label families. Each guideline entry keeps a stable id, title, description, labels, sections, and optional source references.

Create a minimal catalog

Create the manifest:

mkdir -p catalog-source/entries/direct-labels
cat > catalog-source/MANIFEST.md <<'EOF'
# Sample Catalog

## Section Roles

### advice

Actionable guidance for applying the guideline.

## Label Families

### chart

Chart-family labels such as `chart:line`.
EOF

Create one guideline:

cat > catalog-source/entries/direct-labels/guideline.md <<'EOF'
---
id: direct-labels
title: Use direct labels
description: Label marks directly when space permits.
labels:
  - chart:line
---

## Advice <!-- role: advice -->

Place the label close to the mark it names.
EOF

Validate

uvx chartcoach@latest catalog validate --source ./catalog-source --format table

uvx chartcoach@latest catalog manifest --source ./catalog-source --format markdown

Validation catches missing manifests, undefined section roles, undefined label families, duplicate ids, and invalid guideline entries.

Build a bundle

uvx chartcoach@latest catalog build \
  --source ./catalog-source \
  --out ./dist/catalog

The bundle contains metadata.json, MANIFEST.md, and entries.parquet. Pass the bundle directory to --source to read the built catalog with overview, query, and read.

uvx chartcoach@latest catalog overview --source ./dist/catalog

uvx chartcoach@latest catalog query --source ./dist/catalog --contains "legend"

uvx chartcoach@latest catalog read --source ./dist/catalog direct-labels

Export tables

Write a DuckDB file when another tool needs durable SQL tables:

uvx chartcoach@latest catalog export duckdb \
  --source ./dist/catalog \
  --out ./dist/catalog.duckdb

Authored Markdown, manifest and bundle shape, metadata, catalog sources, and artifact descriptors are defined in Cataloging scheme.

Folder scheme

Create a minimal catalog

Validate

Build a bundle

Export tables

On this page