Audit Container Documentation

Separate repository intent from registry state. An image can have a Dockerfile, be eligible for redistribution, or exist in a private registry without being in the public release inventory. State only the layer that the evidence proves.

Required Onboarding Hook

Load this skill before finishing any change that introduces or changes a workbench image or an image-backed solution. This includes work performed through contribute-workbench-image, add-workbench-tool, and oss-solution-registry-onboard.

Reconcile docs/workbench/container-image-catalog.md after the image name, pin, packaging classification, and publication intent are stable:

• Add or update a table row only when the image is selected by publicly_publishable_tools() (which excludes publication quarantine) and its exact resolved tag is anonymously pullable. Do not list a build, private-registry artifact, or merely redistribution-eligible image as published.
• For a new solution that remains BYOF-only, restricted, internal, deferred, or otherwise outside the public plan, do not force it into the public table. Confirm the exclusion against repository sources and document it in the appropriate solution or container documentation when the distinction would otherwise be misleading.
• Treat the catalog audit and its guardrail as part of the originating image or solution change, not as optional follow-up work.

Read The Authoritative Sources

Read AGENTS.md, skills/index.yaml, and the applicable image/tool skills first. Use these sources for distinct facts:

• npa/docker/workbench/packaging-contract.yaml: built-image inventory, packaging tier, ports, security exceptions, and redistribution eligibility.
• npa/src/npa/deploy/images.py: canonical tool-to-image names, restricted tools, public-release membership, and tag-resolution exceptions.
• npa/pyproject.toml [tool.npa.supported-tools]: default immutable image pins.
• npa/src/npa/deploy/*_image_manifest.json: variant-specific pins and evidence for SONIC, Wan, LeRobot, and any future manifest-backed tool.
• npa/src/npa/deploy/public_release_manifest.json: accepted release tags and exact anonymously verified published_digest values.
• npa/docker/workbench/<image>/Dockerfile*, build scripts, lock files, and redistribution records: what an image actually contains and does.
• npa/src/npa/deploy/publish_public.py: exact public source-to-target plan.
• Golden evaluations, CLI/SDK code, and workflow specs: capability and runtime integration. Do not infer capabilities from an image name alone.
• Anonymous registry manifest/config inspection: what is publicly pullable now. Treat this as volatile observed state, not a replacement for repository intent.

Do not treat every Dockerfile or every redistribution: public entry as a public catalog row. public means eligible to redistribute; public-release membership is the intersection selected by publicly_publishable_tools() and its resolved pin.

Run The Audit

1. Preserve unrelated dirty-tree changes and inspect the diff from the relevant base. Search recent changes to Dockerfiles, packaging contracts, image maps, manifests, supported-tool pins, workflows, solution metadata, and container docs. If this audit was loaded by an onboarding skill, identify the new or changed image/solution explicitly before reconciling the catalog.

2. Print the repository's current public plan from the installed checkout:

   npa/.venv/bin/python - <<'PY'
   from npa.deploy.images import CONTAINER_IMAGE_NAMES, public_release_tag_for_tool, publicly_publishable_tools
   
   for tool in publicly_publishable_tools():
       print(tool, CONTAINER_IMAGE_NAMES[tool], public_release_tag_for_tool(tool), sep="\t")
   PY
   

3. Compare that output with the public catalog. Require one row per public-plan image and require each row to include its current resolved pin. Keep additional aliases or historical tags only when the registry still resolves them and the text explains why they remain useful.

4. Compare the packaging-contract keys with Dockerfile directories and the public plan. Classify differences: internal/derived variants, restricted build-your-own images, unregistered artifacts, or actual drift. Never silently force the sets to match.

5. Verify every documented public reference anonymously. Prefer the complete publisher check for current pins, then inspect any extra documented tags:

   npa/.venv/bin/python -m npa.deploy.publish_public \
     --target ghcr.io/nebius/nebius-physical-ai --verify-accepted-releases
   docker buildx imagetools inspect \
     ghcr.io/nebius/nebius-physical-ai/<image>:<tag>
   

   Record the UTC verification date only after all retained rows resolve. A 401 or 403 is not proof that a tag is absent; it proves anonymous pull was not verified. Describe that limitation precisely.

6. Inspect OCI config and labels before changing build dates, users, entrypoints, ports, digests, or architecture claims. Use an immutable tag timestamp or npa.build_ts only when the reproducible image intentionally clears created.

7. Update affected documentation together: the public catalog, container packaging/security docs, tool skills, workflow docs, and release records only where the changed source or observed registry state supplies evidence. Preserve the distinction among built, supported, publishable, published, and validated.

Validate The Result

Run the skill validator, catalog/index guardrails, and documentation drift check:

npa/.venv/bin/python \
  ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
  skills/atomic/audit-container-docs
npa/.venv/bin/python -m pytest \
  npa/tests/guardrails/test_audit_container_docs_skill.py \
  npa/tests/guardrails/test_skills_index.py -q
PATH="$PWD/npa/.venv/bin:$PATH" scripts/build_docs.sh --check

When container sources or resolver code changed, also run the affected Docker, deploy, golden-eval, and workflow tests plus the full non-E2E suite required by skills/atomic/testing-conventions/SKILL.md. Documentation must report registry checks numerically and must not claim live capability validation from unit tests.