unaltraweb 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9b1d06c849d3893c28fa69a879e93f56acef7a742aa8e2d8ae7df78fa53d4a2
-  data.tar.gz: '0995fe545e4466b531edc89ed8c8a37ca707e847cc31a8a3acd3647d6b77ecdd'
+  metadata.gz: 33193d7900939e3cf2e4e9769e8fd9443e0a7242eaa73aef1d93b8ffcee6e79b
+  data.tar.gz: 3ef63e4f55c4b369e0926be413eb2da4d3702f49ac733d84dedc952bb1ec563c
 SHA512:
-  metadata.gz: 06dd87a7428129eb5ab81655c892abddf159d223aefec27cbdf5e7b5512a72fe7940061313cec5ccee5032ac1b0343cc6b8390617106c59b76d979b109d73cfc
-  data.tar.gz: e2a1cc1fe578e4df0968d1f9b9fbc1abbb0cfed254d38c192e7ec24a55e254adf14c9ed57128255f5a18cbaacf68b4fc64a8c519c99d5f87e1a98798db42a1ca
+  metadata.gz: eb799646f841a4444d315aa4a71d161ec83acacbef75f36fe00b8db7242699be40147c2829bedee18f249f3085b51328cd18a902f317196d518b4f2b8e11a9f2
+  data.tar.gz: cfe5a103146718d7bbae56c9821b2dabdc0fdf1bcde966779ee41ea96c468bd795446202844a56a0974919ce4bca33e2d90e5c6de98e8e95936b1335c44dca86

data/Makefile

@@ -1,9 +1,9 @@
 PYTHON ?= python3
 override PROJECT := $${MCP_CONSUMER_WORKSPACE:?MCP_CONSUMER_WORKSPACE is required}
 override PROJECT_ROOT := $(PROJECT)
-MCP_RUNTIME_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb:0.5.0
-MCP_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.0
-MCP_RELEASE_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:389bc585cdb4fc89d3372f4896a55fe26e15df38b46bc114ce44fdb3f1c8deb9
+MCP_RUNTIME_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb:0.6.0
+MCP_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.6.0
+MCP_RELEASE_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:908b4ce54c7bdf355e14ed55b31ed4b9baae319e211af90004a680d1d1cb8692
 MCP_DOCKER_BUILD_NETWORK ?= default
 INIT_SITE_PROFILE ?= unaltreselfie
 NEW_WEB_PROFILE ?= unaltreselfie
@@ -40,10 +40,13 @@ WEB_CAPTURE_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-web-capture@sha256:0bf1b
 WEB_CAPTURE_DEV_IMAGE ?= unaltraweb-web-capture:dev
 WEB_CAPTURE_DOCKER_BUILD_NETWORK ?= default
 VEGAVISUALS_CLI ?=
-DOCKER_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb:0.5.0
-MANUAL_PDF_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:9e0b3a45753c170b795e9a9d6df61580085c113436beac5bf6c8de69b6562097
+DOCKER_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb:0.6.0
+MANUAL_PDF_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:0ba267cb87f53ebaca4e31805fe00610cd61fdf97a8d2c3692f4655700dceaed
 MANUAL_PDF_DEV_IMAGE ?= unaltraweb-manual-pdf:dev
 MCP_SMOKE_MANUAL_PDF_IMAGE ?= $(MANUAL_PDF_IMAGE)
+MCP_SMOKE_PROJECT ?=
+override MCP_SMOKE_PROJECT := $(value MCP_SMOKE_PROJECT)
+export MCP_SMOKE_PROJECT
 MANUAL_PDF_LANG ?=
 MANUAL_PDF_PUBLISH_DRY_RUN ?= 1
 MANUAL_PDF_CONFIRM_PUBLISH ?= 0
@@ -142,14 +145,18 @@ mcp-smoke: mcp-image manual-pdf-image-dev ## Build and prove a real MCP stdio co
 
 mcp-smoke-prebuilt: ## Prove a real MCP stdio connection using the selected prebuilt MCP image
 	docker run --rm --user "$(LOCAL_UID):$(LOCAL_GID)" -e HOME=/tmp --entrypoint python3 "$(MCP_IMAGE)" /opt/unaltraweb/test/mcp_smoke.py
-	@mkdir -p "$(CURDIR)/tmp/mcp-preview-smoke"
-	@docker_socket="$${UNALTRAWEB_DOCKER_SOCKET:-/var/run/docker.sock}"; socket_group=$$(stat -c '%g' "$$docker_socket"); \
+	@mkdir -p "$(CURDIR)/tmp"
+	@project="$${MCP_SMOKE_PROJECT:-}"; \
+	if test -n "$$project"; then mkdir -- "$$project" || exit $$?; \
+	else project=$$(mktemp -d "$(CURDIR)/tmp/mcp-preview-smoke.XXXXXX") || exit $$?; fi; \
+	project=$$(realpath -e -- "$$project") || exit $$?; \
+	docker_socket="$${UNALTRAWEB_DOCKER_SOCKET:-/var/run/docker.sock}"; socket_group=$$(stat -c '%g' "$$docker_socket"); \
 	image_id=$$(docker image inspect --format '{{.Id}}' "$(MCP_IMAGE)"); \
 	socket_mount=$$(/bin/sh "$(DOCKER_MOUNT_SCRIPT)" "$$docker_socket" /var/run/docker.sock); \
-	project_mount=$$(/bin/sh "$(DOCKER_MOUNT_SCRIPT)" "$(CURDIR)/tmp/mcp-preview-smoke" /workspace); \
-	mirror_mount=$$(/bin/sh "$(DOCKER_MOUNT_SCRIPT)" "$(CURDIR)/tmp/mcp-preview-smoke" "$(CURDIR)/tmp/mcp-preview-smoke"); \
+	project_mount=$$(/bin/sh "$(DOCKER_MOUNT_SCRIPT)" "$$project" /workspace); \
+	mirror_mount=$$(/bin/sh "$(DOCKER_MOUNT_SCRIPT)" "$$project" "$$project"); \
 	docker run --rm --user "$(LOCAL_UID):$(LOCAL_GID)" --group-add "$$socket_group" \
-	  -e HOME=/tmp -e "UNALTRAWEB_DOCKER_ROOT=$(CURDIR)/tmp/mcp-preview-smoke" \
+	  -e HOME=/tmp -e "UNALTRAWEB_DOCKER_ROOT=$$project" \
 	  -e "UNALTRAWEB_PROJECT_USER=$(LOCAL_UID):$(LOCAL_GID)" -e "UNALTRAWEB_MCP_IMAGE=$$image_id" \
 	  -e "MANUAL_PDF_IMAGE=$(MCP_SMOKE_MANUAL_PDF_IMAGE)" \
 	  --mount "$$socket_mount" \
@@ -368,7 +375,7 @@ manual-pdf-image: ## Ensure the selected versioned Pandoc/XeLaTeX image is prese
 	@docker image inspect "$(MANUAL_PDF_IMAGE)" >/dev/null 2>&1 || docker pull "$(MANUAL_PDF_IMAGE)"
 
 manual-pdf-image-dev: ## Build the explicitly named maintainer PDF development image
-	docker build -f scripts/manual/Dockerfile -t "$(MANUAL_PDF_DEV_IMAGE)" scripts/manual
+	docker build -f scripts/manual/Dockerfile -t "$(MANUAL_PDF_DEV_IMAGE)" .
 
 define run_manual_pdf_worker
 	@set -e; set --; cidfile=""; \

data/README.md

@@ -34,7 +34,7 @@ The default distribution is Docker-first. Generated sites run their normal build
 
 ## Current Status
 
-- Public release `v0.4.0` provides the Docker images, Ruby gem and Python wheel as one receipt-bound distribution.
+- Public release [`v0.5.0`](https://github.com/dosquartsdedocs/unaltraweb/releases/tag/v0.5.0) provides the Docker images, Ruby gem and Python wheel as one receipt-bound distribution.
 - `ghcr.io/dosquartsdedocs/unaltraweb-mcp` is the canonical normal local runtime for generated sites; `ghcr.io/dosquartsdedocs/unaltraweb` is its lower-level Jekyll runtime base.
 - The Ruby gem supports native Bundler/Jekyll consumers. The modular MCP wheel supports native creation and inspection, and does not bundle the gem, factory checkout, worker images or companion renderers.
 - PDF, browser-capture and computation environments remain separate images so the normal site image does not carry every heavy toolchain.
@@ -74,11 +74,11 @@ Create a child site directly with the public Docker image:
 mkdir my-site && \
 docker run --rm --network none --user "$(id -u):$(id -g)" -e HOME=/tmp \
   --mount "type=bind,src=${PWD}/my-site,dst=/workspace" \
-  ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:389bc585cdb4fc89d3372f4896a55fe26e15df38b46bc114ce44fdb3f1c8deb9 \
+  ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98 \
   --project /workspace new-web --site-profile unaltreselfie --title "My site" --default-lang en
 ```
 
-The chained `mkdir` requires a new destination, the digest binds creation to the reviewed `v0.4.0` receipt, and `--network none` keeps scaffold generation offline.
+The chained `mkdir` requires a new destination, the digest binds creation to the reviewed `v0.5.0` receipt, and `--network none` keeps scaffold generation offline.
 
 If Python package tooling is already available, the PyPI adapter exposes the equivalent native command:
 
@@ -129,7 +129,7 @@ make docs-serve DOCKER_IMAGE=unaltraweb:dev
 make docs-build DOCKER_IMAGE=unaltraweb:dev
 ```
 
-The public distribution contract selects `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.4.0` for normal generated-site commands. `MCP_RELEASE_IMAGE` pins the reviewed MCP digest from the same `v0.4.0` receipt for gContExt (formerly ContExt), the GNOME Shell extension. The mutable `:main` channel is reserved for explicit maintainer testing; locally built core images use the `:dev` name.
+The public distribution contract selects `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.0` for normal generated-site commands. `MCP_RELEASE_IMAGE` pins the reviewed MCP digest from the same `v0.5.0` receipt for gContExt (formerly ContExt), the GNOME Shell extension. The mutable `:main` channel is reserved for explicit maintainer testing; locally built core images use the `:dev` name.
 
 The lower-level `unaltraweb` image supplies Ruby, Jekyll and runtime dependencies. The MCP image layers the full reviewed factory and installed Python package on top; generated Make targets load the theme as a path gem from `/opt/unaltraweb`. Native Bundler consumers can instead resolve the independently published gem, and native Python users can install the wheel.
 

data/_plugins/retained_documents.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+require "open3"
+require "timeout"
+
+module UnaltrawebRetainedDocuments
+  def self.verify(site, output = nil)
+    return { "imports" => [] } unless File.exist?(File.join(site.source, ".unaltraweb", "artifacts"))
+
+    source = File.expand_path("../src", __dir__)
+    command = ["python3", "-m", "unaltraweb_mcp.artifact_imports", "--project", File.expand_path(site.source)]
+    command += ["--output-folder", output] if output
+    stdout, stderr, status = Timeout.timeout(120) { Open3.capture3({ "PYTHONPATH" => source }, *command) }
+    result = JSON.parse(stdout)
+    raise Jekyll::Errors::FatalException, "Retained document check failed: #{result['error'] || stderr}" unless status.success? && result["ok"] == true
+
+    result
+  end
+
+  class Generator < Jekyll::Generator
+    safe true
+    priority :highest
+
+    def generate(site)
+      site.config["unaltraweb_retained_documents"] = UnaltrawebRetainedDocuments.verify(site)["imports"].to_h { |item| [item["id"], item] }
+    end
+  end
+
+  class DocumentTag < Liquid::Tag
+    def initialize(name, markup, tokens)
+      super
+      @id = markup.strip
+      raise ArgumentError, "retained_document requires one import ID" unless @id.match?(/\A[a-z][a-z0-9-]{0,63}\z/)
+    end
+
+    def render(context)
+      site = context.registers[:site]
+      item = (site.config["unaltraweb_retained_documents"] || {})[@id]
+      raise Jekyll::Errors::FatalException, "Unverified retained document #{@id}" unless item
+
+      path = site.config["baseurl"].to_s.sub(%r{/\z}, "") + "/" + item.fetch("pdf")
+      url = CGI.escapeHTML(path)
+      page = context["page"]
+      title = CGI.escapeHTML(((page && page["title"]) || @id).to_s)
+      %(<figure class="retained-document"><object data-retained-document="#{@id}" data="#{url}" type="application/pdf" aria-label="#{title}" style="width:100%;height:70vh"><a href="#{url}">#{title}</a></object><figcaption><a href="#{url}">#{title} (PDF)</a></figcaption></figure>)
+    end
+  end
+end
+
+Liquid::Template.register_tag("retained_document", UnaltrawebRetainedDocuments::DocumentTag)
+
+Jekyll::Hooks.register :site, :post_write do |site|
+  source = File.expand_path(site.source)
+  destination = File.expand_path(site.dest)
+  if destination.start_with?(source + "/")
+    UnaltrawebRetainedDocuments.verify(site, destination.delete_prefix(source + "/"))
+  elsif !(site.config["unaltraweb_retained_documents"] || {}).empty?
+    raise Jekyll::Errors::FatalException, "Retained documents require a project-confined site destination"
+  end
+end

data/docs/_documentation/en/02-tools.md

@@ -30,10 +30,10 @@ nav_title: Local Tools
 The current public core runtime image is:
 
 ```bash
-ghcr.io/dosquartsdedocs/unaltraweb:0.4.0
+ghcr.io/dosquartsdedocs/unaltraweb:0.5.0
 ```
 
-That image provides Ruby, Bundler, Jekyll system dependencies, ImageMagick, Node for ExecJS and Python tooling needed by local commands. Package-generated `v0.4.0` sites select the matching public MCP image for normal local commands. The external integration fixture can advance from its older release pin independently.
+That image provides Ruby, Bundler, Jekyll system dependencies, ImageMagick, Node for ExecJS and Python tooling needed by local commands. Package-generated `v0.5.0` sites select the matching public MCP image for normal local commands. The external integration fixture can advance from its older release pin independently.
 
 ## Generated Site Commands
 
@@ -143,4 +143,4 @@ When the core docs and all template profiles are running together, use this conv
 - Keep deploy workflows as thin `workflow_dispatch` wrappers pinned to a reviewed full commit SHA of `dosquartsdedocs/unaltraweb/.github/workflows/site-deploy.yml`.
 - The optional integration template may retain its local `gh-pages` publishing target for testing that separate workflow.
 - After the first Docker publish, make `ghcr.io/dosquartsdedocs/unaltraweb` public.
-- Confirm `docker pull ghcr.io/dosquartsdedocs/unaltraweb:0.4.0` works without `docker login`.
+- Confirm `docker pull ghcr.io/dosquartsdedocs/unaltraweb:0.5.0` works without `docker login`.

data/docs/_documentation/en/32-development.md

@@ -65,7 +65,7 @@ docker compose -f docker-compose.yml down --remove-orphans
 
 This can be resource-heavy because the inherited demo build minifies JavaScript and can generate many responsive WebP images.
 
-The currently public base Dockerfile image is `ghcr.io/dosquartsdedocs/unaltraweb:0.4.0`. Published generated consumers select the higher-level `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.4.0`, which adds the reviewed core and Python control plane. Their Make targets use `/opt/unaltraweb` as a path gem; the RubyGems package remains the optional native Bundler channel. gContExt prepares the full post-release `MCP_RELEASE_IMAGE` digest with `mcp-build`, while `mcp-image`, `mcp-check` and `mcp-smoke` reserve local `:dev` names for source testing. Mutable `:main` channels remain explicit maintainer paths.
+The currently public base Dockerfile image is `ghcr.io/dosquartsdedocs/unaltraweb:0.5.0`. Published generated consumers select the higher-level `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.0`, which adds the reviewed core and Python control plane. Their Make targets use `/opt/unaltraweb` as a path gem; the RubyGems package remains the optional native Bundler channel. gContExt prepares the full post-release `MCP_RELEASE_IMAGE` digest with `mcp-build`, while `mcp-image`, `mcp-check` and `mcp-smoke` reserve local `:dev` names for source testing. Mutable `:main` channels remain explicit maintainer paths.
 
 The root core build excludes `docs/`. The reference site is published from the `docs/` folder through a dedicated workflow so its root-relative permalinks do not collide with the inherited core demo build.
 

data/docs/_documentation/en/40-distribution.md

@@ -25,12 +25,52 @@ The template is the better place to validate gem consumption, centralized styles
 
 ## Component Contract
 
-### 0.5.0 release preparation
-
-The next coordinated core release is **0.5.0**. It groups the integrated editorial
+### Pending 0.6.0 retained-letter increment
+
+The source branch prepares a separate 0.6.0 identity for native
+[retained-letter import]({{ '/retained-documents/' | relative_url }}).
+Gem, wheel, base runtime and MCP are authorized as `ready` for final same-source
+candidates. The consumer core selects reviewed integration
+`5cf9817489c8dc47cee726bfe42fe3071cd32b85`; the PDF 0.6.0 worker is already
+published, signed and tested at immutable digest
+`sha256:0ba267cb87f53ebaca4e31805fe00610cd61fdf97a8d2c3692f4655700dceaed`.
+The PDF worker changes to include complete retained documents and the same
+integrity checkers used by its controller. Computation, capture and visual
+companions retain their tested 0.4.0 selections.
+
+The checkout's active launcher remains pinned to the published 0.5.1 MCP digest.
+Its receipt and package bytes remain unchanged. Local development images and an
+installed wheel exercise the new import without claiming a public 0.6.0 release
+or changing real consumer sites. The
+[owner acceptance record](https://github.com/dosquartsdedocs/unaltraweb/blob/main/docs/agents/retained-letter-import.md)
+records the authenticated Carta packet, receiver mapping and relocation proof.
+
+### Published 0.5.1 release
+
+[**0.5.1**](https://github.com/dosquartsdedocs/unaltraweb/releases/tag/v0.5.1)
+delivers the installed Docker launcher and runtime-specific generated Bundler
+state. Source `aab5a7b030cd711b40770a3f44ad3a356eab90da` produced the signed
+images and verified gem/wheel. Receipt/tag commit
+`e842c733c8a274279dd5efdc3618e20669f29037` changes only the receipt from that
+first parent. Strict release/publication gates passed before promotion, and
+anonymous registry downloads match the receipt. The checkout launcher now selects
+`ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:908b4ce54c7bdf355e14ed55b31ed4b9baae319e211af90004a680d1d1cb8692`.
+
+The four-profile populated-cache roundtrip also passed against the actual signed
+candidate. The selected PDF stays at its published 0.5.0 digest, and computation,
+capture and visual companions retain 0.4.0. See the
+[delivery report](https://github.com/dosquartsdedocs/unaltraweb/blob/main/docs/agents/owner-closeout-76.md)
+and [issue 76](https://github.com/dosquartsdedocs/unaltraweb/issues/76).
+Strict release validation applies to the receipt/tag revision; subsequent
+post-release launcher changes are ordinary source revisions, not new receipts.
+
+### Previous 0.5.0 release
+
+The previous coordinated core release is [**0.5.0**](https://github.com/dosquartsdedocs/unaltraweb/releases/tag/v0.5.0). It groups the integrated editorial
 review, guided scaffold updates, caption-credit/image behavior and published
-Diavisuals/Vegavisuals 0.4.0 acceptance. Package, core/MCP and manual PDF candidates
-are verified through the existing source-bound workflows before publication.
+Diavisuals/Vegavisuals 0.4.0 acceptance. Source-bound image/package workflows,
+tag promotion and both Trusted Publishing jobs passed. Anonymous package downloads
+match the receipt and clean native installations were checked.
 Unchanged already-published computation and web-capture workers retain their own
 0.4.0 versions and digests. New/pending worker candidates must still match the
 coordinated release; an old mutable alias cannot qualify for reuse. The selected
@@ -41,19 +81,35 @@ at source `d857f8c9f5fea90cf450c0b30b4e77a37b541275` and is selected by digest
 `sha256:9e0b3a45753c170b795e9a9d6df61580085c113436beac5bf6c8de69b6562097` in
 both the factory and the consumer tuple. It is already published and tested, so
 final candidate receipts cover the remaining ready package/core components.
-The factory launcher remains on its previous published image until the normal
-post-release pin update. Follow [issue 69](https://github.com/dosquartsdedocs/unaltraweb/issues/69)
-for the candidate, receipt, tag and package evidence.
+The 0.5.0 post-release factory launcher selected the MCP digest recorded in receipt
+`3fa855378dcc61dc7b84b8b03812698042e02fed`:
+`sha256:36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98`.
+See [issue 69](https://github.com/dosquartsdedocs/unaltraweb/issues/69) for the
+candidate, receipt, tag and package evidence.
 
 `src/unaltraweb_mcp/component-contract.json` is the canonical versioned bill of materials. Its `consumer_integration` object is the sole source for the reviewed core Git revision, reusable deploy workflow, manual PDF image digest, and Vega renderer revision. Scaffold templates render that tuple atomically into consumer `Gemfile`, `Gemfile.lock`, and deploy workflow files. `component-contract.schema.json` defines schema version 1. Runtime loading and `scripts/validate_distribution.py` validate the complete document against that schema, then enforce semantic parity between versions, release tags, repositories, references, wheel contents, CLI availability, and consumer integration pins.
 
-The BOM is an interoperability contract, not a bundle. The wheel contains only its Python control/inspection modules, schema/BOM, and clean package-owned scaffolds. In particular it does not contain Ruby theme assets, Docker image layers, factory Make/scripts/docs, TeX, Chromium, computation environments, `diavisuals`, or `vegavisuals`.
+The BOM is an interoperability contract, not a bundle. The wheel contains its Python control/inspection modules, schema/BOM, clean package-owned scaffolds and a small host Docker launcher, described below. It does not include Ruby theme assets, Docker image layers, the factory's build/worker implementations, TeX, Chromium, computation environments, `diavisuals`, or `vegavisuals`.
 
-The selected public core release is `0.4.0`; `v0.3.0` remains the immutable previous distribution. The next-release source BOM reuses immutable compute and web-capture worker digests and selects published `diavisuals v0.4.0` and `vegavisuals v0.4.0` through SHA-256-pinned wheel URLs. Companion references can describe either a provider/release-matching Git reference or a provider/release/version-matching wheel with its content hash. The wheel boundary remains external. The scaffold's Vega revision is the published `68c0b231402ae9485cc34ce530dc5239cb0ec194` commit. These source changes require a new coordinated core release; they do not alter the already published `0.4.0` artifacts or the factory's `MCP_RELEASE_IMAGE` digest. `distribution-check` validates structural integrity for normal CI. `distribution-release-check` blocks coordinated publication while any component is `pending` or `unavailable`; reviewed source authorized to produce the final same-commit candidates is `ready`, while an already-published component is `released`.
+The selected public core release is `0.5.1`; earlier distributions remain immutable. Its BOM reuses immutable PDF, compute and web-capture worker digests and selects published `diavisuals v0.4.0` and `vegavisuals v0.4.0` through SHA-256-pinned wheel URLs. Companion references can describe either a provider/release-matching Git reference or a provider/release/version-matching wheel with its content hash. The wheel boundary remains external. The scaffold's Vega revision is the published `68c0b231402ae9485cc34ce530dc5239cb0ec194` commit. `distribution-check` validates structural integrity for normal CI. `distribution-release-check` blocks coordinated publication while any component is `pending` or `unavailable`; reviewed source authorized to produce final same-commit candidates is `ready`, while an already-published component is `released`. Final receipt values remain immutable after publication.
 
 ## Docker-First Hybrid Policy
 
-GHCR is the canonical delivery channel for normal local use. The released package scaffold selects `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.4.0`; existing `v0.3.0` sites can remain on their immutable previous release until deliberately updated. Its `make build`, `make serve` and `make test` targets mount the thin child site and run inside that image. The image contains both the installed Python control plane and the reviewed factory source at `/opt/unaltraweb`, so those targets load the theme as a path gem without downloading PyPI or RubyGems packages.
+### 0.5.1 component selection
+
+The coordinated core identity is **0.5.1**: gem, wheel, base runtime and MCP
+images were published together. The installed host launcher and runtime-aware
+generated Bundler state are included. The unchanged PDF worker retains its
+published 0.5.0 digest, alongside the 0.4.0 computation/capture workers and visual
+companions. A released PDF can be reused only by full digest; new/pending workers
+still require the coordinated version. The historical 0.5.0 receipt remains
+unchanged. Signed image/package evidence is recorded in the 0.5.1 receipt;
+promotion and anonymous-download checks passed before the post-release launcher
+pin was advanced.
+
+### Local delivery
+
+GHCR is the canonical delivery channel for normal local use. The released package scaffold selects `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.1`; existing sites can remain on their immutable previous release until deliberately updated. Its `make build`, `make serve` and `make test` targets mount the thin child site and run inside that image. The image contains both the installed Python control plane and the reviewed factory source at `/opt/unaltraweb`, so those targets load the theme as a path gem without downloading PyPI or RubyGems packages.
 
 Factory registration uses a stricter pin. gContExt runs `mcp-build`, which inspects or pulls the full `MCP_RELEASE_IMAGE` digest, and `mcp-stdio` launches that exact image. Checkout builds use local `:dev` names by default through `mcp-image`, `mcp-check` and `mcp-smoke`, so they do not shadow public semver references unless a maintainer explicitly overrides them. The digest is advanced in a separate post-release change after each new receipt exists; candidate source continues to select the last completed release instead of attempting to embed an unknown self-digest.
 
@@ -67,6 +123,95 @@ The distribution keeps native channels for interoperability rather than making t
 
 These remain real package boundaries: the MCP image installs the Python package and uses the core through Ruby's gem interface. The policy only makes their public registry installation optional for Docker users. It does not combine all toolchains into one image or duplicate worker layers in the wheel or gem.
 
+### Installed Docker launcher
+
+0.5.1 ships **`unaltraweb-mcp-docker`** and a complete host launcher
+under the installation prefix's `share/unaltraweb-launcher/`. The published 0.5.0
+wheel predates this addition; its receipt and bytes remain unchanged. An installed
+wheel containing the launcher can use the already-published full GHCR runtime
+without a local core checkout:
+
+```bash
+unaltraweb-mcp-docker prepare
+unaltraweb-mcp-docker check
+unaltraweb-mcp-docker smoke
+unaltraweb-mcp-docker serve --project /absolute/consumer
+```
+
+The installed default selects its package's full MCP release image, currently
+`ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.1`. It resolves that selection to the
+local immutable image ID before executing. The checkout's `MCP_RELEASE_IMAGE`
+is a separate digest pin advanced only after publication; it is not the installed
+wheel's default. This avoids sending a new package back to an older MCP while
+also avoiding an impossible self-digest in the candidate image/wheel.
+`--image` selects a different explicitly prepared image for a test or a reviewed
+adoption. `prepare` only inspects/pulls; `check` and `smoke` use the local image ID,
+without pulling, building, mounting a consumer or starting a preview. `serve`
+requires an explicit consumer or inherited `MCP_CONSUMER_WORKSPACE`; it starts one
+labelled stdio container and preserves the canonical host-path mirror for workers.
+`down --project /absolute/consumer` uses the same project-scoped cleanup helper.
+
+`unaltraweb-mcp-docker path` locates the installed profile from wheel metadata;
+`manifest` prints its discovery descriptor. The profile ships the same native
+schema-v1 `mcp-factory.yml`, a small launcher-only Makefile, and the bootstrap,
+project-ID, Docker CSV mount and cleanup scripts. Its `${factoryRoot}` is this
+installed directory, and the declared `make -C` transport and lifecycle targets
+remain usable. That directory can also be relocated as a unit and run with Make,
+a POSIX shell, Linux core utilities and Docker, without host Python or Ruby.
+The console adapter itself requires the wheel's Python interpreter. Linux/amd64
+is the acceptance platform; other host/platform combinations remain unverified.
+
+This adapter launches the **full container runtime**. The native `unaltraweb-mcp`
+CLI keeps the exact wheel-only/factory-required boundary declared in the BOM.
+Installing the adapter does not install Jekyll, workers or companion servers on
+the host, register a client, update a consumer scaffold, or change an active MCP.
+
+### Separate selections and compatibility evidence
+
+The site Makefile's `MCP_IMAGE`, native Gem/core revision, PDF worker, global MCP
+registration and companion selections are separate parts of an effective tuple.
+TIG/TIGIT retain build defaults 0.4.0; Geodisseny retains 0.5.0. A global MCP
+selection does not rewrite those defaults. Tests use synthetic sites,
+image-specific test resources and dynamically allocated loopback preview ports.
+
+Compatibility evidence is a set of tested tuples, not a continuous version range.
+The [initial owner preparation report](https://github.com/dosquartsdedocs/unaltraweb/blob/main/docs/agents/owner-preparation-2026-09-29.md)
+records all four 0.5.0 profiles, manual PDF coverage, the 0.4.0 comparison and
+the reproduced retained-cache failure. The 0.5.1 correction is recorded in the
+[follow-up report](https://github.com/dosquartsdedocs/unaltraweb/blob/main/docs/agents/owner-followup-76.md).
+Range adoption belongs at
+the native dependency/version checks, companion receipt checks and atomic
+consumer-integration selection. Exact wheel hashes, image digests and published
+receipts remain identity evidence even if future compatibility rules accept a
+range. Central catalogue/range fields await the accepted hub integration.
+
+### Generated Bundler state
+
+0.5.1 keys generated dependencies by the effective Ruby/platform, Bundler,
+installed gem inventory, core inputs and Bundler configuration, rather than a
+mutable Docker tag. The offline resolver prepares a verified cache under
+`tmp/unaltraweb-bundle/<identity>/`. Returning to an identity reuses its cache;
+changing identities does not rewrite another runtime's lock. Credential-bearing
+Bundler environment/configuration values contribute only hashes to the receipt.
+
+New native build/preview targets execute with invocation-owned copies of that
+generated state. Bundler can complete local default-gem checksum metadata without
+rewriting the verified cache or disabling checksum validation. An
+explicit `LOCAL_GEMFILE` is author-managed: its existing lock is required and
+used frozen. Project `Gemfile`, `Gemfile.lock` and Bundler configuration are
+preserved. Edited or incomplete generated caches fail for inspection instead of
+being silently repaired. Failed preparation directories remain under `tmp/`.
+
+For unchanged historical package Makefiles, the updated MCP prepares the same
+runtime-specific cache and passes invocation-owned Gemfile/lock copies to the
+old recipes. The retained `tmp/Gemfile.local.lock` remains untouched, so a later
+0.4.0 build can use its original selection. This adapter requires the Makefile to
+match its recorded scaffold baseline; authored Makefile customizations retain
+their own dependency policy. Those consumers can deliberately adopt the updated
+native targets through the normal reviewed scaffold workflow. New native targets
+require a containing core/runtime; the already-published 0.4.0 and 0.5.0 images do
+not acquire the correction automatically.
+
 ## Optional Wheel And Doctor
 
 A clean `unaltraweb-mcp` wheel works without a factory checkout for `version`, `new-web`, top-level `doctor`, constrained source management, scaffold synchronization, `site-doctor`, HTML audit, and pure inspection where feasible. Examples include `mcp list-tools`, `starter-templates`, `detect-site`, `site-context`, `profile-check`, content/language/bibliography inventories, and `build-health`.
@@ -139,7 +284,7 @@ For that reason:
 
 ## Docker Runtime
 
-Release `0.4.0` publishes the selected base runtime, MCP runtime and specialized workers. Local maintainers continue to use explicit development names such as `unaltraweb:dev`; generated sites select the reviewed semver MCP image rather than `main` or `latest`.
+Release `0.5.1` publishes the selected base/MCP runtime and packages while pinning the verified PDF worker and reusing unchanged specialized workers. Local maintainers continue to use explicit development names such as `unaltraweb:dev`; generated sites select the reviewed semver MCP image rather than `main` or `latest`.
 
 The base runtime owns Ruby, Jekyll and system dependencies. The MCP image builds on its exact candidate digest and adds the full reviewed factory plus the Python package. Specialized workers remain separate. This keeps each layer focused without adding Chromium, TeX or computation stacks to every site; the coordinated core-image workflow still rebuilds and verifies runtime, MCP and manual PDF candidates together.
 

data/docs/_documentation/en/42-docker-image.md

@@ -13,21 +13,21 @@ weight: 140
 permalink: "/docker-image/"
 nav_title: Docker Images
 ---
-Release `v0.4.0` currently publishes two core images. Published generated sites select the self-contained MCP/site image for normal local commands:
+Release `v0.5.0` currently publishes two core images. Published generated sites select the self-contained MCP/site image for normal local commands:
 
 ```text
-ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.4.0
+ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.0
 ```
 
 It contains the Python control plane and the reviewed factory at `/opt/unaltraweb`. Its lower-level base is:
 
 ```text
-ghcr.io/dosquartsdedocs/unaltraweb:0.4.0
+ghcr.io/dosquartsdedocs/unaltraweb:0.5.0
 ```
 
 The base provides Ruby, Bundler, Jekyll system dependencies, ImageMagick, Node for ExecJS and Python tooling. Generated Make targets run in the MCP image and load layouts, styles and plugins as a path gem from `/opt/unaltraweb`. RubyGems remains an optional native Bundler channel rather than a download required by the local Docker path.
 
-The `v0.4.0` receipt binds matching `unaltraweb:0.4.0` and `unaltraweb-mcp:0.4.0` references to their tested immutable digests. The semver aliases were promoted only after the coordinated receipt and tag checks completed.
+The `v0.5.0` receipt binds matching `unaltraweb:0.5.0` and `unaltraweb-mcp:0.5.0` references to their tested immutable digests. The semver aliases were promoted only after the coordinated receipt and tag checks completed.
 
 gContExt prepares and launches the MCP image through the full digest in `MCP_RELEASE_IMAGE`. That post-release pin is separate from the semver scaffold reference and cannot be shadowed by checkout builds, which use local `:dev` names. A new release advances the pin only after its receipt records the published digest.
 
@@ -58,7 +58,7 @@ make mcp-image
 make mcp-smoke-prebuilt MCP_IMAGE=unaltraweb-mcp:dev
 ```
 
-Both core GHCR packages are public, and unauthenticated `v0.4.0` pulls have been verified.
+Both core GHCR packages are public; their `v0.5.0` references resolve to the verified receipt digests.
 
 ## Computation Images
 
@@ -188,8 +188,8 @@ Selector-based screenshot authoring uses a separate Playwright image rather than
 ghcr.io/dosquartsdedocs/unaltraweb-web-capture@sha256:0bf1bc67fe63e1440bffe708a168beefa11c54441650a871ab99380d362f7c1e
 ```
 
-The `v0.4.0` contract reuses this already-published worker by immutable digest. The image contains pinned Playwright/Chromium, the capture worker, the Python status controller, and the core visual sources used in fingerprints. `make web-capture-image` builds the explicitly named `unaltraweb-web-capture:dev` maintainer image; set `WEB_CAPTURE_IMAGE` to that name when testing it. The manual `Web capture image` workflow publishes default-branch, commit, and semver/release tags to GHCR.
+The `v0.5.0` contract reuses the already-published 0.4.0 worker by immutable digest. The image contains pinned Playwright/Chromium, the capture worker, the Python status controller, and the core visual sources used in fingerprints. `make web-capture-image` builds the explicitly named `unaltraweb-web-capture:dev` maintainer image; set `WEB_CAPTURE_IMAGE` to that name when testing it. The manual `Web capture image` workflow publishes default-branch, commit, and semver/release tags to GHCR.
 
-Published `v0.4.0` sites consume `ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf:0.4.0`. `manual-pdf-image` reuses or pulls the selected image instead of rebuilding it locally. Maintainers use `make manual-pdf-image-dev` and then pass `MANUAL_PDF_IMAGE=unaltraweb-manual-pdf:dev` for local PDF runtime changes.
+Published `v0.5.0` scaffolds consume `ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:9e0b3a45753c170b795e9a9d6df61580085c113436beac5bf6c8de69b6562097`. `manual-pdf-image` reuses or pulls the selected image instead of rebuilding it locally. Maintainers use `make manual-pdf-image-dev` and then pass `MANUAL_PDF_IMAGE=unaltraweb-manual-pdf:dev` for local PDF runtime changes.
 
 Rendering creates an ephemeral Docker `--internal` network shared only by Jekyll and Chromium, keeps browser requests on the preview origin, blocks service workers, popups, and WebSockets, drops Linux capabilities, uses a read-only container root and bounded resources, and writes only the declared PNG/SVG outputs under the mounted project. Ordinary checks run without browser execution or network access.

data/docs/_documentation/en/45-retained-documents.md

@@ -0,0 +1,138 @@
+---
+title: Import A Retained Letter
+description: Verify and retain a Carta letter bundle, display its PDF on the web and include it in a manual.
+lang: en
+ref: retained_documents
+profiles:
+- unaltredocs
+documentation_profiles:
+- local-authors
+- core-developers
+section: Build A Site
+weight: 240
+permalink: /retained-documents/
+nav_title: Retained Documents
+---
+
+A retained letter combines its original PDF with the source, rendering inputs and
+provenance needed to inspect its origin. The importer keeps that complete unit in
+the receiving repository and creates a native page or chapter referencing the PDF.
+The website displays the original; a manual PDF includes all its pages.
+
+This capability belongs to the **0.6.0 development increment**. It requires a
+containing Python package and Jekyll core, plus the matching PDF worker for manual
+output. The published 0.5.1 runtime predates it. Changing the global MCP selection
+does not update a site's Gemfile, Makefile or PDF-worker selection.
+
+Native gem builds need Python with `PyYAML>=6,<7`, `pypdf>=6,<7` and
+`markdown-it-py>=3,<5`. The containing MCP/PDF images provide these dependencies;
+the containing reusable deployment workflow installs the PDF/text parsers when
+retained imports are present.
+
+## Supported Input
+
+The receiving profile accepts leaf `letter-pdf-v1` bundles from **Carta
+0.3.0rc1**, using the existing artifact handoff v1 envelope. Verification covers
+the supplied sender SHA-256, complete file inventory, retained render recipe,
+templates, source references, drawable resources and renderer identity. PDF
+inspection is bounded and rejects encrypted files, embedded or external files,
+JavaScript and unsupported actions. Internal destinations and textual HTTP,
+HTTPS and email links are supported.
+
+Renderable metadata is checked independently of the retained Pandoc AST. A
+resealed bundle with an unretained local link in a subject or author field is
+rejected even when its older parsing evidence does not mention that link.
+
+Limits are 64 MiB for the payload unit, 32 MiB for the PDF and 1–64 pages. The
+supported source subset excludes body images, raw markup, TeX, math and citations;
+attachments remain text labels. Composite bundles, edited PDF variants and
+Diapora composition require separate receiving profiles.
+
+Obtain the bundle's expected SHA-256 through the sender's trusted handoff. A hash
+computed only from an unknown local manifest establishes consistency, not its
+origin. Importing never executes the retained recipe or contacts the producer.
+
+## Import Into A Consumer
+
+Start with an initialized consumer Git repository. Place the complete incoming
+bundle under a workspace-relative directory such as `tmp/incoming/letter/`.
+The recovery area under `tmp/` must be ignored and untracked; durable destinations
+must be eligible for version control.
+
+Review a plan using the installed CLI. Here `BUNDLE_SHA` is the sender's verified
+manifest digest:
+
+```bash
+unaltraweb-mcp --project /absolute/consumer mcp import-artifact-bundle \
+  --path tmp/incoming/letter/bundle.json --sha256 "$BUNDLE_SHA" \
+  --import-id correspondence --content-path _chapters/en/correspondence.md \
+  --title "Retained correspondence"
+```
+
+To apply the reviewed request, repeat it with `--apply --confirm-import`.
+The MCP equivalent is `import_artifact_bundle` with `dry_run=false` and
+`confirm_import=true`; its default is a read-only plan.
+
+Choose a new Markdown destination under `_pages/`, or `_chapters/` for a manual,
+or `_documentation/` for a documentation site. An executable source owning the
+same Markdown basename blocks creation. The generated document starts as a draft
+in the consumer's default language, with a literal local permalink.
+
+The resulting paths are:
+
+| Path | Purpose |
+| --- | --- |
+| `.unaltraweb/artifacts/correspondence/bundle/` | Complete, unchanged incoming seal, outside the web output |
+| `.unaltraweb/artifacts/correspondence/integration.json` | Standard v1 integration record and byte-preserving PDF mapping |
+| `.unaltraweb/artifacts/correspondence/binding.json` | Native content path and integration-record digest |
+| `assets/documents/correspondence.pdf` | Public PDF, identical to the retained original |
+| `_chapters/en/correspondence.md` | Native chapter with the retained-document component |
+
+Version the complete durable unit together. The incoming directory and ignored
+recovery journal are not runtime dependencies. The retained archive is excluded
+from website output, but remains ordinary repository content.
+
+## Edit And Render The Native Document
+
+Add explanatory prose to the generated page or chapter while preserving its
+literal permalink and component:
+
+{% raw %}
+```liquid
+{% retained_document correspondence %}
+```
+{% endraw %}
+
+On the web, the component renders a PDF object with a labelled download link.
+The build checks the bound page's exact local PDF URL and the emitted PDF bytes.
+Exposing the retained archive in the website is an error. In a manual, the PDF
+builder includes every original page and fingerprints the entire retained unit
+and its checker implementation. A controller/worker mismatch therefore fails
+freshness verification rather than silently accepting an older checker.
+
+Run `artifact_import_check` or the CLI equivalent before building:
+
+```bash
+unaltraweb-mcp --project /absolute/consumer mcp artifact-import-check
+unaltraweb-mcp --project /absolute/consumer mcp artifact-import-check --output-folder _site
+```
+
+`site_check` and `site_doctor` include the native integrity check. For a local
+manual review, use `manual_pdf_preview_prepare`, then `build_site` and
+`preview_start`. Review the web page and composed PDF, then clean only the
+receipt-owned preview copies through `manual_pdf_preview_clean`.
+
+## Preservation And Recovery
+
+An identical reimport preserves authored prose. A changed mapped PDF, conflicting
+destination, unsafe path or modified seal blocks the operation; existing files
+are never overwritten. After an interrupted import, unchanged partial files may
+be adopted by an explicit retry of the same request. Differing partial files
+require inspection. The operation retains its prepared tree and journal under
+`tmp/unaltraweb-artifact-imports/` and performs no destructive rollback.
+
+The native check verifies references and content after the incoming producer copy
+has been removed or the receiving repository has moved. It also detects missing
+content, incomplete retention and altered mappings. The generic v1 verifier can
+independently inspect `integration.json`; it does not replace the native source
+and rendered-output checks.