Pack Maturity Guide

Pack promotion

Use this page when a Golden example feels useful outside its source folder. The question is not “is the code interesting?” It is “can another project load, run, and understand the boundary without inheriting the whole example tree?”

Maintainer promotion check

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

Expected result: the pack boundary loads through Retriever Hub, promoted commands run, and docs still name the commands plus expected outputs users should see.

Promotion Levels

SourceUseful pattern

The code is helpful as an implementation reference, but users should not depend on it as a stable public surface yet.

DemoNamed command

The example has a Pixi task, docs page, expected output, and smoke coverage. This is the first public launch point.

CandidateManifest boundary

The reusable part has lightweight imports and can be loaded by manifest without optional robot, camera, simulator, model, or network dependencies.

PackReusable interface

The exported names, docs, smoke tests, and compatibility notes are stable enough for downstream projects.

Decision Table

Level	User-facing promise	Required proof
Source reference	Read the code after the promoted path works.	README or docs note explains what pattern to copy.
Promoted demo	Run one command and recognize success.	Named Pixi task, expected output, smoke check.
Pack candidate	Load the reusable 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, and maintainer guardrail.

Do Not Promote Yet If

ImportsOptional dependencies leak in

Loading the pack imports simulator, model, robot, camera, GUI, network, or credential-dependent code.

DocsOnly source paths are documented

A user sees where files live, but not which command to run or what output proves success.

OutputSuccess is ambiguous

The page lacks terminal markers, artifact names, generated files, or screenshots that make success recognizable.

ScopeThe example is lab-specific

Private paths, private credentials, capture procedures, or local hardware assumptions are still required.

Minimum Promotion Checklist

1. Name the public command.
2. Show expected output or generated artifacts.
3. Keep imports lightweight.
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 only the stable boundary, not the whole experiment.