Pack authoring

A pack is an installed Python distribution that plugs archetypes, recipe ops, checks and joints into the engine’s fail-fast registries. Most packs need almost no Python: archetypes, examples and presets are YAML.

1. Copy a template

Two templates ship in community/templates/:

• yaml-pack/ — archetypes + examples, zero Python beyond the two-line register(). Start here.
• python-pack/ — adds self-registering form checks with their declarations and tests.

Rename the package dir (af_pack_example_* → your id), update pack.yaml and pyproject.toml — the entry-point name must be unique.

2. The registration contract

The engine discovers your pack via one entry point:

[project.entry-points."artifact_forge_ng.packs"]
my_pack = "my_pack:register"

register(ctx) runs once, at catalog load, fail-fast:

• ctx.add_data_dir(path) — a dir mirroring the core catalog layout: optional features.yaml, archetypes/ (subdirs allowed), optional modifiers/;
• importing your checks/ / ops/ modules self-registers them into the shared registries — the same conventions core uses;
• collisions are errors: replacing an existing op / joint / check registration raises unless you explicitly ctx.declare_override(name);
• new check names are declared first (idempotent declare() at import), implementations attach after.

3. The honesty rules (non-negotiable)

• Every archetype ships at least one example that forge validate passes in strict mode. Geometry the validators don’t measure is a hallucination — don’t ship it.
• Every new check has PASS, FAIL and n/a branch tests, built on real op-built forms — never hand-typed frames.
• Claims are explicit. Default non-claims stay non-claims: no medical, safety-critical, mains-voltage, pressure-rated, IP-rated, food-safe or animal-safe claims unless externally certified — put the wording in your docs/CLAIMS.md. Non-claims render right on your pack’s page, next to the claims.
• A screenshot or render per archetype is strongly encouraged.

4. Test locally

uv pip install -e path/to/your-pack
uv run forge validate path/to/your-pack/examples/your_example.yaml
uv run pytest path/to/your-pack/tests
ARTIFACT_FORGE_DISABLE_PACKS=1 uv run python -c "import artifact_forge_ng"  # core stays clean

The last line matters: the core must import clean with packs disabled — that’s the core-only release gate, and your pack must not break it.

What a pack may contain

Piece	Format	Notes
archetypes	YAML	bind against core + your own ops/checks
examples	YAML	at least one per archetype, strict-mode green
recipe ops	Python	self-register into RECIPE_OPS
checks	Python	declare names first, attach implementations
joints	Python	self-register into JOINT_TYPES
report hooks	Python	extra sections in part/assembly reports
docs	Markdown	PACK.md, CLAIMS.md