---
name: catalog
description: 'Build, check, publish, and depend on a catalog of fraglet tools -- compile packs into skills, validate the result, render its website, and vendor pinned tools into another repository. Tools: compile, site, validate, vendor. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: engineering, internet
  tools: compile.py, site.py, validate.py, vendor.py
---

# Catalog

Build, check, publish, and depend on a catalog of fraglet tools -- compile packs into skills, validate the result, render its website, and vendor pinned tools into another repository.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/compile.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `compile.py`

Compile a catalog of level-0 tools -- a tarball of pack directories, each an index.md plus fraglet files -- into its projections: one Agent Skill per pack (SKILL.md beside byte-identical copies of the tools), a Claude Code plugin per pack with a marketplace.json, llms.txt and llms-full.txt for agents arriving over HTTP, manifest.json with every tool's contract and procedure_hash, and an Open Knowledge Format bundle. Everything is derived from the tools' own headers and the pack index files; nothing is authored twice.

Use when the user asks to build, rebuild, or regenerate the tools catalog, or wants the skills, llms.txt, marketplace, or OKF views of a set of fraglet tools.

```sh
<skill-dir>/compile.py -p archive="<archive>" [-p host=tools.ofthemachine.com] --output tools.tar.gz
```

Parameters:
- `archive` (file, required) — tar/tar.gz of the catalog source: index.md at the top level (optionally CONTRIBUTING.md beside it, copied through verbatim) plus one directory per pack (<pack>/index.md and the pack's tool files)
- `host` (string, optional, default `tools.ofthemachine.com`) — Canonical host (served over https) where the catalog is published; OKF concepts locate computations by URL there, paired with procedure_hash

Outputs:
- `tools.tar.gz` — copy out with `--output tools.tar.gz[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `site.py`

Render a compiled tools catalog (archived) into a static website: the catalog itself served verbatim -- llms.txt, manifest.json, every pack's SKILL.md and every tool file at the same paths -- plus an HTML layer over it: an explorer of every tool with search, tag and pack filters, grid and table views and a dark/light theme; one page per pack; one page per tool with its contract, provenance, a curl one-liner and its full source. Relative links throughout, so the result works from a file:// URL as well as a web root.

Use when the user wants the browsable website for a tools catalog, or CI publishes tools.ofthemachine.com from a freshly built catalog.

```sh
<skill-dir>/site.py -p archive="<archive>" [-p host=tools.ofthemachine.com] --output site.tar.gz
```

Parameters:
- `archive` (file, required) — tools.tar.gz as catalog/compile.py emits it (the site root is the catalog root)
- `host` (string, optional, default `tools.ofthemachine.com`) — Canonical host (served over https), used in curl one-liners, canonical links, and the CNAME file

Outputs:
- `site.tar.gz` — copy out with `--output site.tar.gz[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `validate.py`

Validate a compiled tools catalog (archived): every pack's SKILL.md against the agentskills.io specification using skills-ref, the spec's own reference validator; every tool file present, executable, and hashing to the procedure_hash manifest.json records for it; every llms.txt link resolving; marketplace.json plugins matching the pack directories; and, if an okf/ bundle is present, every concept typed and every relative link resolving. Prints one line per finding and a summary; exit 0 only when clean.

Use when the user asks whether a compiled catalog of packs is valid, as the catalog build's validation step, or before publishing a catalog.

```sh
<skill-dir>/validate.py -p archive="<archive>" [-p strict=true]
```

Parameters:
- `archive` (file, required) — tar/tar.gz/zip of a compiled catalog: <pack>/SKILL.md and tools, manifest.json, llms.txt, marketplace.json, optional okf/
- `strict` (string, optional, default `true`) — Treat warnings (body over 500 lines) as failures when true

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `vendor.py`

Fetch the catalog tools a project depends on, verify each against its pinned procedure_hash, and pack them into vendor.tar.gz (executable, at their catalog paths, reproducible bytes). The lock file names where the tools are published ("source https://tools.ofthemachine.com") and lists one "<pack>/<stem>.<ext> sha256:<hex>" per line (# comments allowed); the hashes are what manifest.json and every receipt call procedure_hash. A file whose hash does not match is refused and nothing is written, so base_url may fetch from anywhere -- a mirror, or a local `make serve` -- without weakening the pin or changing the recorded source.

Use when bootstrapping a repository that runs catalog tools from its own Makefile or CI: turn its tools.lock into a verified vendor/ directory before running anything.

```sh
<skill-dir>/vendor.py -p lock="<lock>" [-p base_url="<base_url>"] --output vendor.tar.gz
```

Parameters:
- `lock` (file, required) — tools.lock: a "source <url>" line, then "<pack>/<stem>.<ext> sha256:<hex>" per line
- `base_url` (string, optional) — Fetch from here instead of the lock's source (a mirror, or http://host.docker.internal:8080); integrity comes from the hashes, not the host

Outputs:
- `vendor.tar.gz` — copy out with `--output vendor.tar.gz[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.
