containers/bin convention — ecosystem adoption audit + migration plan

[ywatanabe1989]

Ecosystem-wide audit of the ~/.scitex/<pkg>/{containers,bin} convention. Persisted from an a2a delivery to lead on 2026-06-04. Read-only — no migration started. Issue exists to hold the analysis until operator priorities the actual cross-package migration.

TL;DR

• 2 pkgs already on convention (scitex-writer, scitex-agent-container).
• 3 pkgs are real adoption candidates (scitex-ml, scitex-scholar, scitex umbrella) — all currently misfiled under scitex-python/containers/.
• 4 pkgs have container artifacts but DON'T fit the convention (scitex-orochi, newb, crossref-local, figrecipe — all Docker-deployment / GHCR, not personal SIFs).
• 1 template provider (scitex-template), 1 library (scitex-container), 1 HPC helper (scitex-hpc) — convention-aware, no on-disk move.
• ~54 remaining pure-Python pkgs — no containers, no bin/, no migration.
• bin/: ZERO packages in the ecosystem currently have a bin/ at repo root. The slot is greenfield — needs a layout spec before adoption begins.

Verdict legend

ADOPTED / REAL / TRIVIAL / NONE (skip — wrong shape) / N/A

---

TIER A — already on ~/.scitex/<pkg>/containers/

pkg	(a) container artifact	(b) drop path	(c) bin/	(d) verdict & delta
scitex-writer	YES — scripts/containers/{scitex-writer,texlive,mermaid}.def	~/.scitex/writer/containers/<tool>.sif via scitex-writer install	no	ADOPTED. Δ=none. Note: scitex-python/containers/scitex-writer.def is a stale duplicate — cleanup candidate.
scitex-agent-container (sac)	YES — src/scitex_agent_container/containers/apptainer-{base,scitex,proxy}.def	~/.scitex/agent-container/containers/sac-{base,scitex,proxy}.sif	no	ADOPTED. Δ=none. Owns the generic discovery (~/.scitex/*/containers/*.sif, exactly 2 levels).

TIER B — real container, needs adoption (REAL delta)

pkg	(a) container artifact	(b) drop path	(c) bin/	(d) verdict & delta
scitex-ml	YES — .def lives in scitex-python/containers/scitex-ml.def (PyTorch+CUDA base)	hardcoded to umbrella repo path, no install command	no	REAL. Δ: move .def to scitex-ml/scripts/containers/, add scitex-ml install mirroring writer → ~/.scitex/ml/containers/scitex-ml.sif.
scitex-scholar	YES — .def in scitex-python/containers/scitex-scholar.def + scripts/containers/Dockerfile.scholar-gui (also in scitex-python)	hardcoded to umbrella repo	no	REAL. Δ: same shape as ml — relocate + scitex-scholar install → ~/.scitex/scholar/containers/scitex-scholar.sif.
scitex (umbrella / scitex-python repo)	YES — containers/scitex-core.def + scitex-cloud-shared-v0.1.0.def + duplicates (ml/scholar/writer)	hardcoded to umbrella repo	no	REAL. Δ: own only scitex-core.def → ~/.scitex/scitex/containers/scitex-core.sif (if anyone still uses it; verify); duplicates of ml/scholar/writer move to their packages; scitex-cloud-shared is for scitex-cloud which is OUT of ecosystem list (likely retire).

TIER C — has container but NOT a personal-SIF fit (skip cleanly)

pkg	(a) artifact	(b) drop path	(c) bin/	(d) verdict & delta
scitex-orochi	Docker — deployment/docker/Dockerfile + compose (Django web stack)	deployment-side (registry push)	no	NONE — production web image, not a per-user SIF. Skip.
newb	Docker — containers/Dockerfile (newb-runner image, claude-agent-sdk staging)	GHCR (ghcr.io/ywatanabe1989/newb-runner:VERSION), pulled per-run	no	NONE — published image, dockerd runtime, not local SIF. Skip.
crossref-local	Docker — scripts/deployment/mcp/Dockerfile.mcp (MCP server)	deployment-side	no	NONE — deployment image, not personal SIF. Skip.
figrecipe	Docker — scripts/containers/{Dockerfile,Dockerfile.gui} (browser-based figure editor)	local build (docker build ...)	no	OPTIONAL. Δ=could ship apptainer alt + figrecipe install → ~/.scitex/figrecipe/containers/figrecipe-gui.sif if SIF parity is wanted; otherwise NONE.

TIER D / E / F — convention-aware, no on-disk move

pkg	role	(d) verdict & delta
scitex-template	ships singularity .def TEMPLATES (templates/singularity/{template,dev,version-2,_dev,definition_files/dev}.def) for downstream packages to copy	NONE on disk. Δ=trivial: template body should reference ~/.scitex/<pkg>/containers/<name>.sif as the canonical drop path so adopters inherit the convention.
scitex-container	pure-Python wrapper over Apptainer/Docker (no own SIF)	NONE on disk. Δ=trivial: Python API + skills should know about / produce paths in ~/.scitex/<pkg>/{containers,bin} shape (consumer-side awareness).
scitex-hpc	load_apptainer() resolves apptainer via module load on HPC (Spartan/Gadi)	NONE. Δ=none. It's the on-HPC binary resolver that runs SIFs discovered under the convention; no on-disk change needed.

TIER G — no containers, no bin/, no convention impact (verdict NONE for all)

scitex-io, scitex-stats, scitex-clew, scitex-hub, openalex-local, scitex-dataset, socialia, scitex-ssh, scitex-ui, scitex-app, scitex-audio, scitex-parallel, scitex-types, scitex-path, scitex-repro, scitex-compat, scitex-etc, scitex-gists, scitex-db, scitex-seizure-metrics, scitex-dev, scitex-str, scitex-logging, scitex-dict, scitex-browser, scitex-config, scitex-events, scitex-decorators, scitex-pd, scitex-plt, scitex-nn, scitex-genai, scitex-gen, scitex-dsp, scitex-benchmark, scitex-bridge, scitex-capture, scitex-context, scitex-cv, scitex-datetime, scitex-git, scitex-introspect, scitex-linalg, scitex-msword, scitex-notebook, scitex-notification, scitex-os, scitex-resource, scitex-security, scitex-session, scitex-sh, scitex-tex, scitex-todo, scitex-web

(54 pkgs.) Pure-Python libraries. No .def, no Dockerfile, no bin/, no ~/.scitex/<pkg>/ refs. Verdict: NONE / none.

---

Blockers / options to surface before migration is dispatched

1. scitex-python/containers/ is the single biggest cleanup blob — holds .def for scitex-core, ml, scholar, writer (DUP), cloud-shared. Decision needed:
   • (1a) leave umbrella owning scitex-core.sif only, push ml/scholar .def into their own packages.
   • (1b) retire scitex-core if nothing actually consumes it (audit reveals zero in-repo scitex-core.sif refs outside the .def itself).
   • (1c) scitex-cloud-shared-v0.1.0.def is for scitex-cloud which is OUTSIDE the ecosystem roster — propose deleting from scitex-python and letting scitex-cloud own it if/when revived.
2. scitex-writer-texlive .tmp-audit/ directory under scitex-agent-container — looks like a prior audit scratch; not load-bearing but it's polluting grep results.
3. bin/ slot is empty across all 66 pkgs — no current adopter, no precedent to lock the layout. sac uses CLI verbs not standalone exes; writer ships only SIFs. Decision needed before any pkg starts populating it: (a) what goes in bin/ (helper shell scripts? generated launcher symlinks?), OR (b) leave it future-state and let the first adopter set the precedent.
4. scitex-template singularity templates — should be updated to reference ~/.scitex/<pkg>/containers/<name>.sif as canonical drop path so new pkgs that scaffold from template inherit the convention by default. Cheap fix in scitex-template, big leverage downstream.
5. figrecipe Docker-vs-Apptainer decision — figrecipe's GUI dev container currently has no apptainer .def. If brand convention is "SIF first, Docker for deployment", figrecipe may want an apptainer .def alongside the Dockerfile.

---

Bottom line

The convention is already in production in 2 packages (writer + sac) with sac as the discoverer. 3 real moves (ml, scholar, scitex umbrella) clear the legacy scitex-python/containers/ blob. Everything else is either deployment-Docker (skip cleanly) or pure-Python (no impact). Greenfield bin/ slot — needs a layout spec before adoption begins.

Provenance

• Convention DOC: PR docs(skill/local-state): §4d worked example for dotfiles-tracked ~/.scitex + §4b containers/bin rows #112 (already merged) — ~/.scitex/<pkg>/{containers,bin} documented in skill 06 §4b.
• This audit: read-only enumeration of all 66 pkgs from scitex-dev ecosystem list, performed 2026-06-04 by proj-scitex-dev. No .def files moved, no other packages touched.
• Status: HELD pending operator prioritization. This issue persists the analysis; migration work has not started.