Cataloging scheme

The Guideline Catalog lets agents and applications find chart guidance, inspect the exact recommendation, and cite the sources behind it. Its record shape keeps discovery, table joins, public links, and citation output aligned across the CLI, Python, JavaScript, and MCP.

Core concepts

Inspect the manifest before hard-coding a role or label family. Role and label names come from the catalog's manifest vocabulary.

catalog-release/
├── metadata.json
├── MANIFEST.md
└── entries.parquet

uvx chartcoach@latest catalog read compare-percentages-with-bars-not-pies \
  --source-detail minimal \
  --format markdown

Use exact ids from catalog list, catalog query, catalog sql, or catalog find. Guideline ids are catalog data copied from command output.

Default Catalog and pinning

The Default Catalog is the package-pinned release used when a caller omits --source or chartcoach.open() receives no source. JavaScript callers use DEFAULT_CATALOG for the same package-pinned artifact URLs and pass the loaded artifact bytes to loadCatalog(). The package constants select a release URL and digest, so repeated reads resolve the same bundle until the installed package changes or the caller passes a custom catalog source.

Inspect the installed Default Catalog for current guideline entry counts, source references, version, and digest:

uvx chartcoach@latest catalog overview --format json

The Default Catalog follows the cataloging scheme described in Structured Visualization Design Knowledge for Grounding Generative Reasoning and Situated Feedback.

Pin chartcoach@<version> when CLI results must stay tied to the Default Catalog shipped by that package version.

Use a custom catalog source for another catalog instance:

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

CHARTCOACH_SOURCE=./dist/catalog uvx chartcoach@latest catalog overview

Query and search engines

chartcoach delegates SQL and indexed search to two engines:

chartcoach defines catalog shape, catalog sources, command behavior, and cache layout. DuckDB and LanceDB define SQL syntax, database-file behavior, table configuration, embedding functions, and search modes.

Serialized row

entries.parquet stores one row per guideline. The top-level row id must match guideline.id.

type CatalogRow = {
  id: string;
  guideline: {
    id: string;
    title: string;
    bibliography?: string | null;
    description: string;
    labels: string[];
    body: string;
    sections: Array<{
      role: string;
      title: string;
      content: string;
    }>;
  };
  references: string[];
};

Loaders reject duplicate ids, mismatched row ids, invalid labels, empty section roles, and manifest coverage gaps.

Authored Markdown

An authored catalog folder stores each entry at entries/<id>/guideline.md. The guideline Markdown carries front matter, sections, and section role comments. Build and read commands serialize source references into the row-level references array.

Manifest

Every catalog instance needs a MANIFEST.md with these headings:

• Section Roles
• Label Families

Each role or label family is a level-three heading with prose underneath. The manifest defines what the current catalog means by a role or family. Validation checks that every used section role and label family is defined there.

## Section Roles

### advice

Guidance that states what to do, avoid, prefer, or choose.

## Label Families

### chart

Labels for chart families and visual forms, such as `chart:bar`.

Label examples inside a family definition must belong to that family.

Release metadata and catalog sources

metadata.json names a catalog release and its artifacts. Base readers require manifest and entries. Indexed commands read lancedb-index when search should run from a published index.

type CatalogReleaseMetadata = {
  version: string;
  digest: string;
  artifacts: Array<{
    kind: "manifest" | "entries" | "lancedb-index";
    path: string;
    digest: string;
    bytes: number;
    rows?: number;
    format?: string;
    table?: string;
    documents?: number;
  }>;
};

Artifact descriptors include kind, path, digest, bytes, and kind-specific fields such as rows, format, table, and documents. path must be relative and cannot contain ... Catalog clients resolve paths relative to the metadata URL.

A release root URL includes the catalog version, digest, and trailing slash:

https://artifacts.chartcoach.dev/catalog/releases/<version>/<digest>/

Select releases through package constants or explicit metadata URLs. Store the concrete metadata URL when a workflow needs to reproduce the same release.

CLI and Python readers accept these catalog sources:

The JavaScript package loads caller-provided artifact bytes. Use DEFAULT_CATALOG for the package-pinned artifact URLs. Use parseCatalogReleaseMetadata(), catalogArtifact(), and catalogArtifactUrl() when code starts from a metadata.json URL.

Cache

The Python CLI and package store downloaded release artifacts under artifacts/ inside the user's platform cache directory.

uvx chartcoach@latest catalog cache path

Base reads download MANIFEST.md and entries.parquet. Indexed commands download LanceDB archives when chartcoach[index] is installed and a default index is resolved. A caller-owned --index path stays outside the chartcoach artifact cache.

Set CHARTCOACH_CACHE_DIR for tests or isolated runs that need a separate platform cache root.

Queryable tables

Inspect the live schema before writing SQL:

uvx chartcoach@latest catalog schema --tables --row-counts

uvx chartcoach@latest catalog schema --format jsonl

catalog sql and MCP sql accept one read-only SELECT statement. Use catalog schema TABLE for columns before writing a join. Use catalog export duckdb when another tool needs a database file.

Inspect vocabulary before writing filters:

uvx chartcoach@latest catalog values labels --contains chart: --format jsonl

uvx chartcoach@latest catalog values roles --format jsonl

uvx chartcoach@latest catalog values label.family --format jsonl

uvx chartcoach@latest catalog values sections.role --format jsonl

Aliases such as labels, roles, label.family, label.category, and label.modifier map to table columns.

Loader boundary

Load catalog data through the Python or JavaScript package APIs. Use generated docs output and public HTML pages for reading, linking, and search workflows.