unaltraweb 0.4.0 → 0.5.1

data/docs/agents/owner-followup-76.md

@@ -0,0 +1,144 @@
+# Owner follow-up 76: populated Bundler transitions and 0.5.1 preparation
+
+This follows the immutable historical intake in
+[owner-preparation-2026-09-29.md](owner-preparation-2026-09-29.md) and the hub's
+`owner-followups/05-unaltraweb.txt`. Tracking and final execution results:
+[issue 76](https://github.com/dosquartsdedocs/unaltraweb/issues/76).
+
+## Correction and source identity
+
+Implementation commit: `c23e12b0e1567d18a7f9dd225dc062ddc77dad8b`, on the existing
+`feat/76-distributed-mcp-launcher` primary checkout. Local commits were explicitly
+authorized. The following integration commit pins `consumer_integration.core_sha`
+to this real 0.5.1 core, so the generated Gemfile/lock/workflow tuple no longer
+combines a 0.5.1 gem version with a 0.5.0 source revision.
+
+The correction lives in `src/unaltraweb_mcp/bundler_runtime.py` and is included in
+both wheel and gem. It keys generated state by the actual Ruby/platform, Bundler,
+installed gem inventory, core dependency inputs and hashed Bundler configuration.
+No mutable Docker alias or project build default acts as the cache identity.
+
+- Offline `bundle lock --local` and `bundle check` prepare a new identity cache
+  under `tmp/unaltraweb-bundle/<hash>/` and record exact Gemfile/lock hashes.
+- Reuse verifies that receipt. Edited, unsafe or incomplete caches are retained
+  and rejected rather than silently reset. No old generated tree is removed.
+- Each build/preview gets private invocation copies. This also accommodates
+  Bundler 4's local default-gem checksum completion without disabling checksums
+  or changing a cached or authored lock. An initially attempted frozen generated
+  lock exposed empty `rake` CHECKSUMS entries in the owner runtime; private copies
+  fixed that additional regression. Explicit author Gemfiles require an existing
+  lock and run with `BUNDLE_FROZEN=true`.
+- Updated package scaffolds use the helper in native build/test/serve targets.
+- MCP build and same-image preview adapt unchanged historical Makefiles only
+  when their bytes match the recorded package scaffold baseline. They pass
+  `LOCAL_GEMFILE` pointing to an invocation copy. The original
+  `tmp/Gemfile.local.lock`, project Gemfile/lock, Makefile and scaffold manifest
+  remain byte-identical. Custom Makefiles retain their own dependency policy;
+  adopting the new native targets remains an explicit scaffold update.
+
+The already-published 0.5.0 image is still unpatched. The roundtrip fixture retains
+its exact Ruby/gem layers and adds the new owner controls as a separately named
+test image; this proves the correction against the problematic 0.5.0 inventory,
+not a new empty cache or an unrelated fresh Ruby installation.
+
+## Component decision
+
+| Component | 0.5.1 preparation |
+| --- | --- |
+| Core gem | New 0.5.1: ships the runtime helper and updated controls/docs. |
+| Python wheel | New 0.5.1: installed Docker launcher, cache orchestration, scaffolds and integration tuple. |
+| Full MCP image | New 0.5.1: required to run the correction without a local core. |
+| Base Ruby/Jekyll image | Coordinated 0.5.1 candidate under the existing image workflow. The Dockerfile/toolchain recipe itself is unchanged. |
+| Manual PDF | Reuse published 0.5.0 digest `sha256:9e0b3a45753c170b795e9a9d6df61580085c113436beac5bf6c8de69b6562097`. |
+| Python/R computation, web capture | Retain their published 0.4.0 versions/digests. |
+| Diavisuals/Vegavisuals | Retain published hashed 0.4.0 wheels and current receipt contract. |
+
+The native validator now permits a released, digest-pinned PDF to retain its
+actual version across a coordinated core patch. Pending/ready PDF candidates,
+mutable aliases and other repositories do not receive that exception. The
+existing source image workflow may build a PDF verification candidate; it does
+not thereby replace the selected released worker or put it in the new receipt.
+The new receipt must contain exactly `gem`, `wheel`, `runtime`, `mcp` when those
+four components remain `ready`.
+
+The 0.5.0 receipt is unchanged, SHA-256
+`e57a9dbb041c1e7fcd781cd1524f4de0317382e0f7303bb36bfa59c0b6d1cb9b`.
+Historical tags and published packages are untouched. The launcher retains the
+last published MCP digest until a separately reviewed post-release selection.
+Local 0.5.1 artifacts have new names and are not registry-published candidates.
+
+## Regressions and pre-integration owner gates
+
+Executed on Linux/amd64:
+
+- All four historical profiles: successful 0.4.0 host build first, containing
+  `google-protobuf (4.36.1-x86_64-linux-gnu)` in the retained generated lock.
+- Unpatched 0.5.0 fails with the known missing `google-protobuf (4.36.1)` on a
+  disposable copy of each populated consumer; this negative control is required.
+- Corrected controls on 0.5.0 Ruby layers: two builds, preview and HTTP pass.
+- Return to unchanged published 0.4.0: two builds, preview and HTTP pass.
+- Hash comparisons verify preservation of both authored and retained generated
+  Gemfile/lock pairs, Makefile and scaffold baseline across the roundtrip.
+- The manual additionally builds/stages real PDFs and performs receipt-bound
+  preview cleanup. No source mount or real manual is used.
+- Unit regressions cover populated A→B→A cache reuse, modified generated locks,
+  symlink ancestors, author Makefile overrides, frozen author locks, credential
+  hashing, and private checksum-completion copies.
+
+Initial evidence is retained under
+`/tmp/opencode/unaltraweb-followup-76/all-profiles-first/` (three completed
+profiles) and `manual-first-roundtrip/` (completed manual). The first combined
+run reached its 20-minute terminal limit during the final historical preview;
+the manual was rerun to completion. No test container remained from that timeout.
+
+Before integration: **562 unit tests, 30 optional skips**; distribution, workflow,
+wheel, gem, MCP CLI, MCP stdio/manual-preview, prose and docs-build gates passed.
+The final native smoke passed using `unaltraweb-followup-76-mcp:precommit3`; the
+earlier frozen-generated-lock attempts remain failed intermediate evidence.
+The old report's 0.5.0-labelled local wheel is not a release artifact.
+
+## Final-version artifact gate protocol
+
+After pinning the corrected core, build the final 0.5.1 wheel and gem from that
+clean integration commit, retain their hashes, install the wheel non-editably,
+and repeat the gates against those bytes. Retain final outcomes and immutable
+local image IDs in issue 76 rather than inserting a self-referential artifact
+digest into its own source. Evidence belongs under
+`/tmp/opencode/unaltraweb-followup-76/final-artifacts/` and
+`/tmp/opencode/unaltraweb-followup-76/final-roundtrip/`.
+
+The reproducible populated-cache command is:
+
+```bash
+python3 test/bundler_transition_smoke.py \
+  --launcher /tmp/opencode/unaltraweb-followup-76/final-venv/bin/unaltraweb-mcp-docker \
+  --legacy-image ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:389bc585cdb4fc89d3372f4896a55fe26e15df38b46bc114ce44fdb3f1c8deb9 \
+  --broken-image ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98 \
+  --fixed-image unaltraweb-followup-76:051-on-050-final \
+  --output /tmp/opencode/unaltraweb-followup-76/final-roundtrip
+```
+
+Use a fresh output directory and a sufficiently long outer deadline; the driver
+never clears a populated fixture to obtain a pass. The test overlay is built
+with `test/bundler_transition.Dockerfile`, the exact published 0.5.0 base digest,
+and a named `wheel` build context containing the final wheel. Installation uses
+`--no-index --no-deps`, and the build uses `--network none`. Ordinary owner
+`mcp-check`/`mcp-smoke` also run against separate test tags and fresh fixtures.
+
+## Publication status and next gate
+
+Issue 76 stays open until integration and release. No PR, push, tag, workflow
+dispatch, registry upload or consumer activation is authorized by the local
+commit approval. The native schema remains unchanged; H1 range/catalogue fields
+are not invented here. Tested points are the explicit tuples above, not a
+continuous semver compatibility interval.
+
+The strict `distribution-release-check` is mandatory and must remain blocking
+until there is a new 0.5.1 receipt-only child commit with the correct default-branch
+candidate ancestry, signed image digests and verified package checksums. The
+retained 0.5.0 receipt cannot satisfy that gate and is not rewritten to do so.
+Next: reviewed branch integration (preserving or deliberately refreshing the
+core pin), approved signed candidate/package preparation on the resulting source,
+new receipt-only commit, strict gate, then separately approved promotion and
+post-release launcher selection. TIG, TIGIT, Geodisseny, their active registrations
+and their image/worker selections are outside this test and adoption scope.

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

@@ -0,0 +1,79 @@
+# 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.
+
+## Selected artifacts
+
+| Provider | Integrated published source | Wheel SHA-256 |
+| --- | --- | --- |
+| Diavisuals v0.4.0 | `1e842967eabbad4cdb7dcb081493c1c25772dc5f` | `bfedcc9e2554f25ce4a1c33e556f352210848fccb8da800d1c3900dd86c48c93` |
+| Vegavisuals v0.4.0 | `68c0b231402ae9485cc34ce530dc5239cb0ec194` | `b52ffa743643dd6b5e0320e7a9aa0cd500ea06262b7d5098c0c3f94a379bc0ea` |
+
+Canonical URLs are in `components.<provider>.reference`; dependency `uv_spec`
+values derive from them. Validation binds a wheel's repository, release path,
+package/version filename and nonzero SHA-256. Existing exact Git references
+remain accepted. No additional component-contract field or wire version is needed.
+The published Vega wheel/renderer archive targets Linux/amd64.
+
+Native lifecycle flags, tools/resources and the complete dependency closure are
+preserved. Vega consumer scaffold revision now comes from its published commit.
+The current native receipts retain their original provider-owned semantics.
+This unit does not add a v1 artifact importer or claim domain bundle compatibility.
+
+## Executed acceptance — 2026-09-26
+
+- `make distribution-check`: passed.
+- `PYTHONPATH=src python3 -m unittest discover -s test -p 'test_*.py'`:
+  544 discovered, 515 passed, 29 optional cases skipped.
+- `make wheel-check`: passed against a clean factory-free installed wheel.
+- `make mcp-check mcp-smoke`: passed through the owner Docker development images,
+  including real stdio and preview/manual-PDF paths.
+- `make docs-build`: passed in the published core runtime.
+- `test/published_companion_smoke.py`: passed with separate installed published
+  wheel CLIs, their tested renderer images and a new temporary consumer with spaces.
+  It renders Mermaid, PlantUML, Vega-Lite with retained CSV data, and raw Vega;
+  checks actual provider receipts through `site_check`; rejects modified data and
+  diagram bytes; then accepts the relocated consumer. No receipt is fabricated.
+- `git diff --check`: passed.
+
+Reproduce the provider acceptance after installing the exact BOM wheel URLs and
+loading/verifying the renderer archives from their releases:
+
+```bash
+PYTHONPATH=src python3 test/published_companion_smoke.py \
+  --diavisuals /absolute/published-diavisuals/bin/diavisuals \
+  --vegavisuals /absolute/published-vegavisuals/bin/vegavisuals
+```
+
+Tested renderer IDs:
+`sha256:5a6887b372a0e1c386a7b54981d11ae1910215baeb6a12dfd0706b3e85ef0846`
+(Diavisuals) and
+`sha256:695125943d0fbc3aa7c877babb9a11a6501bbc7ac265b0975bb5657c60439d98`
+(Vega). These identify the release archives' images, not OCI registry RepoDigests.
+
+## Activation and publication order
+
+1. Review/integrate this owner PR and choose the next coordinated core release
+   version. Do not rebuild or republish the existing 0.4.0 artifacts under this
+   changed BOM. Keep other already integrated editorial/scaffold changes in scope
+   when preparing that coherent release.
+2. Run the normal candidate/receipt/signing/package release procedure in
+   `docs/_documentation/en/40-distribution.md`. Verify installed runtime and
+   native receipts against the exact candidate digests; unchanged workers can
+   retain their existing reviewed identities.
+3. Advance `MCP_RELEASE_IMAGE` only in the normal post-release change, using its
+   new receipt. It currently remains
+   `ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:389bc585cdb4fc89d3372f4896a55fe26e15df38b46bc114ce44fdb3f1c8deb9`.
+   A green development manifest does not mean that this older running image has
+   acquired the new companion contract.
+4. Reconcile hub dependency state and repair the existing unaltraweb client drift
+   through normal dependency-aware installation. Reconnect clients and inspect the
+   selected runtime's own manifest before updating real consumer scaffolds.

data/docs/assets/img/caption-credits-demo.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="640" height="180" viewBox="0 0 640 180" role="img" aria-labelledby="title desc">
+  <title id="title">Three linked stages</title>
+  <desc id="desc">Three labelled boxes, A, B and C, connected from left to right.</desc>
+  <rect width="640" height="180" fill="#fff"/>
+  <g fill="#eaf1f7" stroke="#315a75" stroke-width="2">
+    <rect x="35" y="45" width="150" height="90" rx="8"/>
+    <rect x="245" y="45" width="150" height="90" rx="8"/>
+    <rect x="455" y="45" width="150" height="90" rx="8"/>
+  </g>
+  <g fill="none" stroke="#315a75" stroke-width="3">
+    <path d="M185 90h50m-10-8 10 8-10 8"/>
+    <path d="M395 90h50m-10-8 10 8-10 8"/>
+  </g>
+  <g fill="#213f56" font-family="sans-serif" font-size="18" text-anchor="middle">
+    <text x="110" y="97">A</text>
+    <text x="320" y="97">B</text>
+    <text x="530" y="97">C</text>
+  </g>
+</svg>

data/scripts/editorial_check.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Run the gem's offline editorial publication check without an MCP checkout."""
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from unaltraweb_mcp.editorial import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

data/scripts/image_background_check.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Run the packaged image background advisory without an MCP factory runtime."""
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from unaltraweb_mcp.image_backgrounds import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())