How-to guides on Katalyst Documentation

Profile an existing wiki by hand

Mon, 01 Jan 0001 00:00:00 +0000

Profile an existing wiki by hand#

You have a directory of markdown: a vault, a docs tree, a knowledge base, and you want a Katalyst schema for it. Rather than guess the conventions, inspect measures them. This guide turns an existing corpus into a draft schema by reading the evidence yourself. To hand that judgment to an agent instead, see Profile an existing wiki with an agent.

inspect reports evidence, counts and distributions, never recommendations. Reading the evidence and deciding the schema is your call. It runs in two layers: point it at a directory to profile a raw store (no project needed), or at a configured collection to profile its items. The onboarding loop uses both.

Profile an existing wiki with an agent

Mon, 01 Jan 0001 00:00:00 +0000

Profile an existing wiki with an agent#

The by-hand guide has you read inspector evidence and decide the schema. This guide hands that judgment to an agent: inspect supplies the measurements, the agent supplies the thresholds, collection-boundary decisions, and the draft. Katalyst is the instrument; the agent is the profiler.

The split is deliberate. Inspectors are deterministic and never recommend; deciding that a field present in 94% of files should be required, or that a directory should be a collection, is the agent’s call. Keep that division and the loop stays debuggable.

Configure checks for a collection

Mon, 01 Jan 0001 00:00:00 +0000

Configure checks for a collection#

You have a directory of markdown files and want Katalyst to enforce checks on them. This guide adds a collection and attaches checks to it.

1. Point a collection at the directory#

Collections are declared inside a storage instance. In a fresh project that is .katalyst/storage/local.yaml (the default filesystem instance). Add the collection under collections:, keyed by its name; path is the directory relative to the instance root:

Add a schema

Mon, 01 Jan 0001 00:00:00 +0000

Add a schema#

JSON Schema is how Katalyst validates the shape of an item’s frontmatter: required keys, types, ranges. This guide registers a schema and binds it to a collection.

1. Write the schema file#

Put a JSON Schema (draft 2020-12) under .katalyst/schemas/. Its name is the filename stem: book.yaml registers a schema named book, with no separate registration step. Schemas are written in YAML by default, the same draft 2020-12 vocabulary as JSON:

Validate in CI

Mon, 01 Jan 0001 00:00:00 +0000

Validate in CI#

Run Katalyst in continuous integration so malformed frontmatter and non-canonical formatting fail the build instead of reaching main.

Exit codes#

Both gating commands use the same convention:

Code	Meaning
`0`	Everything passed
`1`	One or more items failed (validation or formatting)
`2`	Usage error (e.g. no `.katalyst/` directory found)

Gate on validation#

katalyst check over the whole project exits non-zero if any item has a violation:

katalyst check

An item with a violation, here one missing its H1, prints the diagnostic and the run exits 1, the non-zero status that fails the CI step: