unaltraweb 0.5.0 → 0.5.1

data/docs/agents/owner-preparation-2026-09-29.md

@@ -0,0 +1,254 @@
+# Checkout-free MCP launcher: owner preparation report
+
+Date: 2026-09-29. Hub handoff: **unaltraweb owner preparation**, following
+`gacontext/src/bash/mcp_factories/handoffs/owner-preparation-prompts.md` and its
+existing-manual baseline. Tracking: [issue 76](https://github.com/dosquartsdedocs/unaltraweb/issues/76).
+
+## Source and delivery status
+
+- Primary checkout: `unaltraweb`; branch `feat/76-distributed-mcp-launcher`.
+- Base/source checkpoint: `260271e41b17be0f95dcb8047014c35cb97142ee`.
+- Implementation is an **uncommitted owner working-tree change**, not a release,
+  tag, pushed branch or PR. The hub can ingest this report without changing its
+  catalogue or activating a client registration.
+- The full published 0.5.0 GHCR runtime already contains the factory and supports
+  checkout-free site work. No replacement image release is needed to run it.
+- The published 0.5.0 wheel lacks the standalone host launcher. The new wheel
+  contents require a future reviewed package release under a new version. The
+  local test wheel still reports source version 0.5.0 and must never replace the
+  published wheel of that name.
+
+Changed paths:
+
+```text
+Makefile
+pyproject.toml
+packaging/launcher/Makefile
+src/unaltraweb_mcp/docker_launcher.py
+scripts/unaltraweb-mcp-bootstrap.sh
+scripts/test_wheel_install.py
+scripts/validate_distribution.py
+test/test_distributed_launcher.py
+test/distributed_launcher_smoke.py
+docs/_documentation/en/40-distribution.md
+docs/agents/mcp-contract.md
+docs/agents/owner-preparation-2026-09-29.md
+```
+
+The source `mcp-factory.yml`, component BOM/schema, published receipt, managed
+consumer scaffolds and their version selections are unchanged. Preserved hashes:
+
+| File | SHA-256 |
+| --- | --- |
+| `src/unaltraweb_mcp/component-contract.json` | `f3de4b289fc6ae66ddc86bf6a701b3a2cfaed66ab6303f64252c92639a7aab98` |
+| `release-candidates.json` | `e57a9dbb041c1e7fcd781cd1524f4de0317382e0f7303bb36bfa59c0b6d1cb9b` |
+
+## Native installed profile and capability boundary
+
+The wheel installs `share/unaltraweb-launcher/Makefile`, the **byte-identical native
+schema-v1 `mcp-factory.yml`**, and the existing bootstrap, project-ID, CSV mount and
+cleanup scripts under `scripts/`. It uses the current `runtime.kind: container`,
+`runtime.package_manager: docker`, consumer binding, `transport.command` with
+`make -C ${factoryRoot} mcp-stdio`, and inherited `MCP_CONSUMER_WORKSPACE`.
+Here `${factoryRoot}` names the installed launcher directory. No new H1 fields or
+alternative central schema were introduced. Companion lifecycle flags and exact
+tool/resource inventories remain those in the native manifest.
+
+`unaltraweb-mcp-docker path` resolves that directory from installed wheel metadata.
+`manifest` prints the descriptor. `prepare`, `check`, `smoke`, `serve` and `down`
+delegate to packaged shell scripts. Preparation may pull; check/smoke require a
+local image, use its immutable local ID and mount neither source nor consumer.
+Serve requires an explicit consumer and preserves both canonical host-path mounts
+and the original factory/project labels. Cleanup retains its exact project scope.
+
+The profile directory is independently relocatable with Make, POSIX shell, Linux
+core utilities and Docker. The console adapter requires Python. The native
+`unaltraweb-mcp` CLI retains the BOM's exact package-only and factory-required
+inventories: shipping a Docker adapter does not put Ruby/core/TeX/Chromium or
+worker/companion implementations into the wheel. `new-web`, doctor and inspection
+remain usable natively; full MCP serving and build/PDF orchestration execute in
+the selected GHCR image.
+
+## Published identities and dependency closure
+
+Native identities use existing BOM `kind`, `version`, `release`, `reference` and
+`image_repository`, and manifest `mcp_dependencies[].uv_spec`. Container references
+below are in `ghcr.io/dosquartsdedocs/`; each hash is an OCI repository digest,
+not a Docker image configuration ID.
+
+| Component / repository | Version | Exact selected digest |
+| --- | --- | --- |
+| Full MCP `unaltraweb-mcp` | 0.5.0 | `sha256:36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98` |
+| Base Ruby/Jekyll `unaltraweb` (receipt) | 0.5.0 | `sha256:4c7bfa51b8f936993ca5a1350d8b63ac3af77f88e97065a9b4a223583528fa8e` |
+| PDF `unaltraweb-manual-pdf` | 0.5.0 | `sha256:9e0b3a45753c170b795e9a9d6df61580085c113436beac5bf6c8de69b6562097` |
+| Python `unaltraweb-compute-python` | 0.4.0 | `sha256:18cb269811bd4005800382da25a480ec2bca7eac8d0501ad1ef36bad1c0f8cd9` |
+| R `unaltraweb-compute-r` | 0.4.0 | `sha256:928ffb93f221e09e8b929157dee473b838e061915a2eb67224e4124b85f81837` |
+| Chromium `unaltraweb-web-capture` | 0.4.0 | `sha256:0bf1bc67fe63e1440bffe708a168beefa11c54441650a871ab99380d362f7c1e` |
+| Historical full MCP `unaltraweb-mcp` | 0.4.0 | `sha256:389bc585cdb4fc89d3372f4896a55fe26e15df38b46bc114ce44fdb3f1c8deb9` |
+| Historical PDF `unaltraweb-manual-pdf` | 0.4.0 tuple | `sha256:bb3e373f8a512495eeed684c23ad904d298c2e20a6dc3ade0d0a60c7ec9a9f11` |
+
+The runtime layer is embedded in the full MCP image. The four workers remain
+separate feature-selected containers; compute/capture were inventoried, not
+rendered again in this preparation. Companions remain separate MCP servers:
+
+| Companion | Native selected wheel and SHA-256 |
+| --- | --- |
+| Diavisuals 0.4.0 | `diavisuals[mcp] @ https://github.com/dosquartsdedocs/diavisuals/releases/download/v0.4.0/diavisuals-0.4.0-py3-none-any.whl#sha256=bfedcc9e2554f25ce4a1c33e556f352210848fccb8da800d1c3900dd86c48c93` |
+| Vegavisuals 0.4.0 | `vegavisuals[mcp] @ https://github.com/dosquartsdedocs/vegavisuals/releases/download/v0.4.0/vegavisuals-0.4.0-py3-none-linux_x86_64.whl#sha256=b52ffa743643dd6b5e0320e7a9aa0cd500ea06262b7d5098c0c3f94a379bc0ea` |
+
+Both dependencies retain `required/install/build/check/smoke: true` and
+`init/update: false`. Their renderer archive identities and earlier real receipt
+acceptance are in [visual-companions-0.4.0.md](visual-companions-0.4.0.md); that
+2026-09-26 evidence is not presented as a new rendering run here. Historical core
+0.4.0 selects companions 0.3.1; the 0.5.0 receipt verifier does not promise to accept
+those older provider identities.
+
+## Synthetic acceptance and isolation
+
+Platform: Linux/amd64, host Python 3.12, Docker 27.2.0. A non-editable wheel was
+installed with `--no-deps --no-index` into
+`/tmp/opencode/unaltraweb-owner-20260929/venv`. Its launcher metadata resolved
+outside the source checkout. The retained test wheel SHA-256 is
+`a8b2136ffb23970980b86b70e64d509e2e24500f1e032b023f857cde22a7988f`.
+
+All acceptance consumers, Git indexes, caches, generated PDFs and Jekyll outputs
+are synthetic under `/tmp/opencode/unaltraweb-owner-20260929/`. No host core was
+mounted. Preview inspection verified only the synthetic consumer bind and no
+Docker socket. Ports were allocated on loopback; preview stop and digest-bound
+PDF preview cleanup passed. Full stdio sessions used the installed launcher.
+
+| Scaffold / host build | Active MCP / PDF | Profile coverage | Result |
+| --- | --- | --- | --- |
+| 0.5.0 / MCP build | 0.5.0 / 0.5.0 | All four profiles | Empty detection, creation, site check, build, preview, HTTP and HTML audit pass; manual PDF/cover pass. Ports 32770–32773. |
+| 0.4.0 / 0.4.0 host build | 0.4.0 / historical pinned PDF | `unaltremanual` | Host build/PDF, MCP build, preview, HTTP and HTML audit pass. Port 32776. New image-background and update-advisory tools are absent as expected. |
+| 0.4.0 / no earlier host build cache | 0.5.0 / 0.5.0 | `unaltremanual` | Pass with fresh synthetic runtime cache, port 32774. Update advisory reports `update_available`; no sync is applied. |
+| 0.4.0 / successful 0.4.0 host build first | 0.5.0 / 0.5.0 | `unaltremanual` | Site check and PDF pass; MCP build fails because retained `tmp/Gemfile.local.lock` selects `google-protobuf (4.36.1)`, unavailable in the 0.5.0 image. No automatic cache deletion or pin migration. |
+
+Evidence directories are `released-050-full`, `released-040-manual-full`,
+`mixed-fresh-040-050`, and `mixed-retained-lock-final`. Runs retain `evidence.json`,
+server stderr and actual outputs, including the reproduced mixed-cache failure's
+MCP response, host-build log and generated lock. The initial
+four-profile run hit the terminal's 120-second limit after one profile; its owned
+test session was cleaned by exact consumer identity and the complete run passed
+with a 600-second outer limit. An initial historical runner call to the newer
+`image_background_check` was corrected to inspect actual capabilities; it was a
+test-driver mismatch, not a claimed 0.4.0 feature.
+
+Retained PDF hashes:
+
+- 0.5.0 and fresh 0.4.0-scaffold/0.5.0 runtime:
+  `4e6e405ed690caf075ec33ea04090d2a5c4bfbf0fb0a49a35cdab819c6f40939`.
+- Historical host/runtime 0.4.0:
+  `68f067addf5e009364edb42042de2410af5ce8c38543556852d4498bd9663a75`.
+
+Both covers were visually inspected. The 0.5.0 PDF has nine pages including the
+synthetic Coordinates chapter, contents and expected draft marker. This is
+technical acceptance, not human publication approval.
+
+## Owner gates and exact reproduction
+
+Passed:
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s test -p 'test_*.py'
+make distribution-check
+make workflow-check
+make wheel-check
+make mcp-check mcp-smoke \
+  MCP_RUNTIME_IMAGE=unaltraweb-owner-76-runtime:20260929 \
+  MCP_IMAGE=unaltraweb-owner-76-mcp:20260929-final \
+  MANUAL_PDF_DEV_IMAGE=unaltraweb-owner-76-pdf:20260929 \
+  MCP_SMOKE_MANUAL_PDF_IMAGE=unaltraweb-owner-76-pdf:20260929 \
+  MCP_SMOKE_PROJECT=/tmp/opencode/unaltraweb-owner-20260929/owner-preview-final
+docker run --rm --network none --user "$(id -u):$(id -g)" -e HOME=/tmp \
+  --entrypoint make unaltraweb-owner-76-mcp:20260929 -C /opt/unaltraweb gem-check
+make --silent --no-print-directory \
+  -C /tmp/opencode/unaltraweb-owner-20260929/venv/share/unaltraweb-launcher \
+  mcp-check mcp-smoke
+PYTHONPATH=src python3 -m unaltraweb_mcp.cli --project docs mcp prose-check \
+  --target _documentation/en/40-distribution.md
+make docs-build DOCKER_IMAGE=unaltraweb-owner-76-runtime:20260929
+git diff --check
+```
+
+Unit suite: **553 tests, 30 optional skips**. `wheel-check` verifies all four
+factory-free native scaffolds and every byte of the launcher/helper closure.
+The installed-profile smoke uses the published image, no socket/source mount and
+`--network none`. Owner source smoke additionally runs a real stale PDF worker and
+a socket-free persistent preview. Docker's content-addressed build cache reused
+existing layers; test image tags and consumer/Python/Jekyll caches were separate.
+The owner smoke now creates a fresh unique fixture by default and refuses any
+existing explicit `MCP_SMOKE_PROJECT`, preventing its fixture reset from touching
+prior work. Prose check reports only one pre-existing informational long-sentence
+finding in the publication-workflow paragraph; docs build and diff check pass.
+Existing `:dev`, manual build and TIGIT local worker image IDs were rechecked and
+preserved. Test image configuration IDs:
+
+- `unaltraweb-owner-76-runtime:20260929`: `sha256:df6a55511b5e40c3fde8a10326263cc7a87723b8c090e8333d64bf848c3a853f`.
+- `unaltraweb-owner-76-mcp:20260929`: `sha256:dd795ad90dc30547ae09c9175e06f296af1072f4277a2b02d8122000c7378e07`.
+- Final source gate `unaltraweb-owner-76-mcp:20260929-final`: `sha256:1ef3d4e7ac5fbb60b66103415c87c30bb432802016ccc30b46b896de3bf35a1b`.
+- `unaltraweb-owner-76-pdf:20260929`: `sha256:6c7c5411b4f570fcdcfb1f984a9d9a0e36cc54d606bf459ca67929af0bc0d145`.
+
+The host `make gem-check` initially refused the absent semver-tagged base image;
+the exact gate then passed inside the isolated owner image using its local Ruby.
+`make distribution-release-check` correctly **fails** at this post-release source
+checkpoint: it is not the receipt-only child of the recorded candidate source.
+The published receipt is preserved rather than rewritten to make a source
+preparation look publication-ready.
+
+Acceptance driver (fresh output directories are required):
+
+```bash
+L=/tmp/opencode/unaltraweb-owner-20260929/venv/bin/unaltraweb-mcp-docker
+MCP05=ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98
+MCP04=ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:389bc585cdb4fc89d3372f4896a55fe26e15df38b46bc114ce44fdb3f1c8deb9
+python3 test/distributed_launcher_smoke.py --launcher "$L" --image "$MCP05" \
+  --output /tmp/opencode/unaltraweb-owner-20260929/released-050-full
+python3 test/distributed_launcher_smoke.py --launcher "$L" --image "$MCP04" \
+  --profiles unaltremanual --host-build \
+  --output /tmp/opencode/unaltraweb-owner-20260929/released-040-manual-full
+python3 test/distributed_launcher_smoke.py --launcher "$L" --image "$MCP05" \
+  --scaffold-image "$MCP04" --profiles unaltremanual \
+  --output /tmp/opencode/unaltraweb-owner-20260929/mixed-fresh-040-050
+python3 test/distributed_launcher_smoke.py --launcher "$L" --image "$MCP05" \
+  --scaffold-image "$MCP04" --profiles unaltremanual --host-build \
+  --output /tmp/opencode/unaltraweb-owner-20260929/mixed-retained-lock-final
+```
+
+The final command intentionally reproduces the retained-lock failure in a new
+output directory. The original `mixed-040-050` run used the driver's then-default
+host-build step before that option was made explicit.
+
+## Range adoption points, gaps and next action for the hub
+
+1. **Install/discovery:** map the installed `path` and existing descriptor into the
+   accepted hub contract. Do not treat a source checkout's `make mcp-check` (which
+   builds) as equivalent to the installed profile's prepared-image check.
+2. **Compatibility versus exact selection:** `mcp_dependencies` and
+   `distribution.py:companion_dependency_requirements` currently select exact
+   provider versions/wheels; `site_tools.py` receipt validation also requires exact
+   provider version/release. A future accepted range must be tested there without
+   weakening request/input/artifact hashes or equating wheel hashes with images.
+3. **Consumer tuple:** `consumer_integration`, scaffold rendering/update planning,
+   the Make image selection and native Gemfile pins remain atomic reviewed
+   selections. Preserve their concrete revision and hashes after any future range
+   resolution. Fix/test runtime-specific generated Bundler-cache handling before
+   promising transparent switching across the mixed 0.4.0/0.5.0 tuple.
+4. **Coverage:** tested endpoints are 0.4.0 and 0.5.0, not a promised `[0.4,0.6)`
+   interval. The other three 0.4.0 profiles, non-Linux/amd64 platforms, independent
+   new compute/capture/companion rendering and stable publication channels were
+   not covered by this preparation.
+5. **Delivery:** review the owner diff, assign a new package version through the
+   normal release procedure, bind final artifacts to new receipt evidence, then
+   adopt the installed profile in a separate synthetic hub pilot. The full 0.5.0
+   image can remain selected. Client activation and each real-manual upgrade need
+   their own later owner session.
+
+TIG/TIGIT retain 0.4.0 build defaults; Geodisseny retains 0.5.0. Their sources,
+generated artifacts, registrations and worker identities were not migrated.
+During this session the author separately approved storage cleanup: five stopped
+old test containers were removed, and exact unused/unshared unaltraweb cache IDs
+were submitted to BuildKit pruning (131.1 kB actually reclaimed). Active stdio
+containers, manual previews, images and volumes were not removed by that cleanup.
+Other concurrent Docker activity changed disk availability; its reclaimed space
+is not attributed to this preparation.

data/docs/agents/visual-companions-0.4.0.md

@@ -1,6 +1,11 @@
 # Published visual companions: native acceptance and release handoff
 
 Tracking: [issue 67](https://github.com/dosquartsdedocs/unaltraweb/issues/67).
+Publication update: the acceptance is included in
+[unaltraweb v0.5.0](https://github.com/dosquartsdedocs/unaltraweb/releases/tag/v0.5.0),
+receipt `3fa855378dcc61dc7b84b8b03812698042e02fed`, and the post-release launcher
+selects MCP digest `36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98`.
+The preparation notes and original 0.4.0 image below retain their historical context.
 Owner branch: `fix/67-published-visual-companions`, based on
 `bfabaa2738ddd24725f5e386d60b58a9a8294316` after an eligible primary-checkout
 preflight. This is next-release source, not a replacement for published core 0.4.0.

data/scripts/test_gem_build.py

@@ -62,7 +62,7 @@ def build(output: Path, *, source: Path = ROOT) -> str:
 
 def inspect_gem(path: Path) -> None:
     editorial_files = ["scripts/editorial_check.py", "src/unaltraweb_mcp/editorial.py", "src/unaltraweb_mcp/editorial_sources.py"]
-    inspection_files = editorial_files + ["scripts/image_background_check.py", "src/unaltraweb_mcp/image_backgrounds.py",
+    inspection_files = editorial_files + ["src/unaltraweb_mcp/bundler_runtime.py", "scripts/image_background_check.py", "src/unaltraweb_mcp/image_backgrounds.py",
                                           "src/unaltraweb_mcp/image_probe.py", "src/unaltraweb_mcp/processes.py"]
     with tarfile.open(path, mode="r") as package:
         data_member = package.extractfile("data.tar.gz")

data/scripts/test_wheel_install.py

@@ -35,6 +35,9 @@ def main() -> int:
             source,
             ignore=shutil.ignore_patterns(
                 ".git",
+                ".venv",
+                ".cache",
+                ".jekyll-cache",
                 "build",
                 "dist",
                 "*.egg-info",
@@ -58,6 +61,21 @@ def main() -> int:
             raise RuntimeError(f"Expected one wheel, found: {wheels}")
         with zipfile.ZipFile(wheels[0]) as archive:
             names = archive.namelist()
+            launcher_prefix = f"{wheels[0].name.split('-')[0]}-{wheels[0].name.split('-')[1]}.data/data/share/unaltraweb-launcher/"
+            launcher_files = {
+                "Makefile": "packaging/launcher/Makefile",
+                "mcp-factory.yml": "mcp-factory.yml",
+                **{f"scripts/{name}.sh": f"scripts/{name}.sh" for name in (
+                    "unaltraweb-mcp-bootstrap", "unaltraweb-mcp-project-id",
+                    "unaltraweb-mcp-cleanup", "unaltraweb-docker-mount",
+                )},
+            }
+            actual_launcher = {name.removeprefix(launcher_prefix) for name in names if name.startswith(launcher_prefix)}
+            if actual_launcher != set(launcher_files):
+                raise RuntimeError(f"Wheel launcher closure mismatch: {actual_launcher}")
+            for installed_path, source_path in launcher_files.items():
+                if archive.read(launcher_prefix + installed_path) != (ROOT / source_path).read_bytes():
+                    raise RuntimeError(f"Wheel launcher asset differs from source: {installed_path}")
         forbidden_roots = {"docs", "scripts", "_layouts", "_includes", "_sass"}
         leaked = []
         for name in names:
@@ -71,6 +89,7 @@ def main() -> int:
             raise RuntimeError(f"Factory assets leaked into wheel: {leaked}")
         required = [
             "unaltraweb_mcp/calibre_import.py",
+            "unaltraweb_mcp/bundler_runtime.py",
             "unaltraweb_mcp/component-contract.json",
             "unaltraweb_mcp/component-contract.schema.json",
             "unaltraweb_mcp/manual_pdf_preview.py",
@@ -105,6 +124,33 @@ def main() -> int:
         python = environment / "bin/python"
         cli = environment / "bin/unaltraweb-mcp"
         run([str(python), "-m", "pip", "install", "--no-deps", str(wheels[0])], cwd=temp, env=env)
+        docker_cli = environment / "bin/unaltraweb-mcp-docker"
+        launcher = Path(run([str(docker_cli), "path"], cwd=temp).stdout.strip())
+        if launcher != environment / "share/unaltraweb-launcher":
+            raise RuntimeError(f"Launcher did not resolve its installed wheel data: {launcher}")
+        if run([str(docker_cli), "manifest"], cwd=temp).stdout != (ROOT / "mcp-factory.yml").read_text(encoding="utf-8"):
+            raise RuntimeError("Installed native manifest drifted from discovery contract")
+        no_consumer_env = {key: value for key, value in env.items() if key not in {"MCP_CONSUMER_WORKSPACE", "UNALTRAWEB_PROJECT"}}
+        refused = run([str(docker_cli), "serve"], cwd=temp, env=no_consumer_env, expected=2)
+        if "requires --project" not in refused.stderr:
+            raise RuntimeError("Installed launcher accepted an implicit consumer")
+        fake_bin = temp / "fake-bin"
+        fake_bin.mkdir()
+        fake_docker = fake_bin / "docker"
+        fake_docker.write_text("#!/bin/sh\n[ \"$1 $2\" = 'image inspect' ] || exit 99\n[ \"$5\" = \"$EXPECTED_IMAGE\" ] || exit 98\nprintf 'sha256:fixture\\n'\n", encoding="utf-8")
+        fake_docker.chmod(0o755)
+        expected_image = json.loads((ROOT / "src/unaltraweb_mcp/component-contract.json").read_text())["components"]["mcp"]["reference"]
+        launcher_env = {**no_consumer_env, "PATH": f"{fake_bin}:{env['PATH']}", "EXPECTED_IMAGE": expected_image}
+        launcher_env.pop("UNALTRAWEB_MCP_IMAGE", None)
+        launcher_env.pop("MCP_RELEASE_IMAGE", None)
+        prepared_image = run([str(docker_cli), "prepare"], cwd=temp, env=launcher_env).stdout.strip()
+        if prepared_image != "sha256:fixture":
+            raise RuntimeError("Installed preparation did not use the packaged bootstrap")
+        run(["make", "--silent", "--no-print-directory", "-C", str(launcher), "mcp-build"], cwd=temp, env=launcher_env)
+        run([str(docker_cli), "prepare", "--image", "explicit:override"], cwd=temp,
+            env={**launcher_env, "EXPECTED_IMAGE": "explicit:override", "UNALTRAWEB_MCP_IMAGE": "environment:override"})
+        run([str(docker_cli), "prepare"], cwd=temp,
+            env={**launcher_env, "EXPECTED_IMAGE": "environment:override", "UNALTRAWEB_MCP_IMAGE": "environment:override"})
         version = run([str(cli), "version"], cwd=temp).stdout.strip()
         doctor = json.loads(run([str(cli), "doctor"], cwd=temp).stdout)
         if not doctor["ok"] or doctor["mode"] != "wheel" or not doctor["limited"]:

data/scripts/unaltraweb-mcp-bootstrap.sh

@@ -3,15 +3,18 @@ set -eu
 
 usage() {
   cat <<'USAGE'
-Usage: unaltraweb-mcp-bootstrap [--project PATH] [--image IMAGE]
+Usage: unaltraweb-mcp-bootstrap [--project PATH] [--image IMAGE] [--prepare|--check|--smoke]
 
 Start one Dockerized unaltraweb MCP stdio server for the selected workspace.
 If --project is omitted, MCP_CONSUMER_WORKSPACE is used, then the current directory.
+--prepare inspects or pulls the selected image without mounting a consumer.
+--check and --smoke require that image locally; neither builds nor pulls.
 USAGE
 }
 
-image="${UNALTRAWEB_MCP_IMAGE:-ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.0}"
+image="${UNALTRAWEB_MCP_IMAGE:-ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98}"
 project="${MCP_CONSUMER_WORKSPACE:-${UNALTRAWEB_PROJECT:-}}"
+operation=serve
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -25,6 +28,11 @@ while [ "$#" -gt 0 ]; do
       image="$2"
       shift 2
       ;;
+    --prepare|--check|--smoke)
+      [ "$operation" = serve ] || { printf '%s\n' 'Select only one operation.' >&2; exit 2; }
+      operation="${1#--}"
+      shift
+      ;;
     -h|--help)
       usage
       exit 0
@@ -37,6 +45,28 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
+resolve_image() {
+  if ! resolved_image="$(docker image inspect --format '{{.Id}}' "$image" 2>/dev/null)"; then
+    case "$operation" in
+      check|smoke)
+        printf 'Image is not prepared: %s. Run --prepare first.\n' "$image" >&2
+        exit 1
+        ;;
+    esac
+    docker pull "$image" >&2
+    resolved_image="$(docker image inspect --format '{{.Id}}' "$image")"
+  fi
+}
+
+if [ "$operation" != serve ]; then
+  resolve_image
+  case "$operation" in
+    prepare) printf '%s\n' "$resolved_image"; exit 0 ;;
+    check) exec docker run --rm --network none --user "$(id -u):$(id -g)" -e HOME=/tmp --entrypoint unaltraweb-mcp "$resolved_image" version ;;
+    smoke) exec docker run --rm --network none --user "$(id -u):$(id -g)" -e HOME=/tmp --entrypoint python3 "$resolved_image" /opt/unaltraweb/test/mcp_smoke.py ;;
+  esac
+fi
+
 if [ -z "$project" ]; then
   project="$PWD"
 fi
@@ -80,10 +110,7 @@ if [ -S "$docker_socket" ]; then
   esac
 fi
 
-if ! resolved_image="$(docker image inspect --format '{{.Id}}' "$image" 2>/dev/null)"; then
-  docker pull "$image" >/dev/null
-  resolved_image="$(docker image inspect --format '{{.Id}}' "$image")"
-fi
+resolve_image
 image_reference="$image"
 case "$image_reference" in
   ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:*) ;;

data/scripts/validate_distribution.py

@@ -75,7 +75,7 @@ def component_version_errors(contract: dict[str, Any]) -> list[str]:
     """Retain the real version of already-published, digest-pinned workers."""
     version = str(contract["release"]["version"])
     errors = []
-    reusable_workers = {"compute_python", "compute_r", "web_capture"}
+    reusable_workers = {"compute_python", "compute_r", "web_capture", "manual_pdf"}
     for component_id in ["gem", "wheel", "runtime", "mcp", "compute_python", "compute_r", "web_capture", "manual_pdf"]:
         selected = contract["components"][component_id]
         if (component_id in reusable_workers and selected["kind"] == "container"
@@ -168,6 +168,20 @@ def validate(root: Path = ROOT) -> list[str]:
         errors.append("component contract schema does not select version 1")
 
     pyproject = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8"))
+    launcher_files = {
+        "share/unaltraweb-launcher": ["packaging/launcher/Makefile", "mcp-factory.yml"],
+        "share/unaltraweb-launcher/scripts": [
+            "scripts/unaltraweb-mcp-bootstrap.sh", "scripts/unaltraweb-mcp-project-id.sh",
+            "scripts/unaltraweb-mcp-cleanup.sh", "scripts/unaltraweb-docker-mount.sh",
+        ],
+    }
+    if pyproject.get("tool", {}).get("setuptools", {}).get("data-files") != launcher_files:
+        errors.append("wheel must distribute exactly the native Docker launcher and its helper closure")
+    launcher_image = make_value(root / "Makefile", "MCP_RELEASE_IMAGE")
+    if not re.fullmatch(r"ghcr\.io/dosquartsdedocs/unaltraweb-mcp@sha256:[0-9a-f]{64}", launcher_image):
+        errors.append("MCP_RELEASE_IMAGE must select a full GHCR MCP digest")
+    if make_value(root / "packaging/launcher/Makefile", "MCP_RELEASE_IMAGE") != component_reference("mcp"):
+        errors.append("installed launcher must select its own package release image")
     project = pyproject.get("project", {})
     if "version" in project or project.get("dynamic") != ["version"]:
         errors.append("pyproject version must be derived from the package component contract")
@@ -242,7 +256,7 @@ def validate(root: Path = ROOT) -> list[str]:
     pinned_text = {
         "scripts/computations/render.py": [component_reference("compute_python"), component_reference("compute_r")],
         "scripts/web_captures/render.py": [component_reference("web_capture")],
-        "scripts/unaltraweb-mcp-bootstrap.sh": [component_reference("mcp")],
+        "scripts/unaltraweb-mcp-bootstrap.sh": [launcher_image],
         "Dockerfile.mcp": [component_reference("runtime")],
     }
     for relative, references in pinned_text.items():
@@ -485,6 +499,11 @@ def publish_ref_errors(
         if not isinstance(component, dict):
             errors.append(f"unknown publish component: {component_id}")
             continue
+        if (component_id == "manual_pdf" and component.get("release_status") == "released"
+                and re.fullmatch(r"ghcr\.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:[0-9a-f]{64}", str(component.get("reference", "")))):
+            # Already-published, unchanged worker. It is not a new candidate for
+            # this coordinated core release and receives no new semver identity.
+            continue
         if str(component.get("version") or "") != version:
             errors.append(f"{component_id} publish version does not match distribution release {version}")
         if str(component.get("release") or "") != release_tag: