Pack Maturity Guide

The question for promotion is never “is the code interesting?” It is “can another project load, run, and understand the boundary without inheriting the whole example tree?” This guide names the levels and the proof each one needs.

Promotion Levels

Level	User-facing promise	Required proof
Source reference	Read the code after the promoted path works.	README/docs note explaining the pattern to copy.
Promoted demo	Run one command and recognize success.	Named Pixi task, documented output, smoke check.
Pack candidate	Load the boundary without source-path knowledge.	Manifest export plus Hub loader smoke.
Hub-loadable pack	Reuse the interface from another project.	Versioned release, docs, compatibility notes.

A payload reaches Hub-loadable only once its manifest export, this section’s docs, and demo-golden-hub-pack agree. The applied types on the export catalog are at that level; heavier examples stay at demo level behind a Pixi task.

Maintainer promotion check

The release gate is scripted, not manual. public-surface-check verifies that required paths exist, promoted Pixi tasks are declared, and every documented command and output marker is still present in the docs.

pixi run demo-golden-hub-pack
pixi run public-surface-check

Real output — each required surface reports its own status line:

[PASS] path:examples/advanced/core_composition/golden_hub_pack_smoke.py                exists
[PASS] task:demo-golden-hub-pack                                                        declared
[PASS] task:demo-robotics-lerobot-bridge                                               declared
[PASS] doc:docs-site/src/content/docs/hub/export-catalog.mdx:convert_to_arrow          present

The checked tasks include demo-golden-hub-pack, demo-robotics-data-eventstream, demo-robotics-data-join, demo-robotics-lerobot-bridge, and demo-pipeline-html-viz; the marker set pins the exact export names and command strings this documentation promises. Break one and the check fails loudly.

Do not promote yet if

• Imports leak — loading the pack pulls in simulator, model, robot, camera, GUI, network, or credential-dependent code.
• Only source paths are documented — a user sees where files live but not which command to run or what output proves success.
• Success is ambiguous — no terminal markers, artifact names, or generated files to recognize.
• The example is lab-specific — private paths, credentials, capture procedures, or local hardware are still required.

Minimum Promotion Checklist

1. Name the public command (a Pixi task).
2. Show expected output or generated artifacts.
3. Keep imports lightweight — no optional robot/sim/model/network deps.
4. Add or update the smoke check.
5. Add or update the release-surface marker in scripts/release/check_public_surface.py.
6. Keep /llms.txt aligned so agents start from the same route as humans.

Default decision: keep a useful example as a promoted demo before turning it into a Hub pack. Promote the stable boundary, not the whole experiment.

Source: scripts/release/check_public_surface.py; manifest in pyproject.toml [tool.retriever.module].